BuzzAd Benefit API Callback(AOS 1.5.0, iOS 1.2.0)
index
広告インプレッション/クリック/参加ステータスに関するコールバックの変化
順序 (Android OS/iOSは名称のみ異なるだけで動作は同一のため、以下ではAndroid OSの名称を基準に説明を行う)
Android OS : onImpressed → onClicked → (onRewardRequested) → onRewarded → onParticipated
iOS : didImpressAd → didClickAd → willRequestRewardForAd → didRewardForAd → didParticipateAd
onImpressed
定義
広告インプレッションが発生(=NativeAdViewの広告レイアウトの50%以上が表示された状態)
重複呼び出しの有無
1つの広告あたり、1回だけ呼び出される
推奨設定
X
onClicked
定義
広告がユーザーによってクリックされる (=clickableViewsで指定したcomponentがクリックされた状態)
静止画バナー/動画広告のいずれにおいてもonClickEvent/shouldClickAd (AOS/iOS)を通じたclickイベントの受け取りが可能(下記参照)
この時静止画バナー広告の場合はLPへの遷移を開始し、動画広告の場合はサーバーから動画のアセットを取得し、再生を開始する
重複呼び出しの有無
1つの広告あたり重複しての呼び出しが可能。(ユーザーが広告をクリックしてLPに遷移後アプリに戻ってきてから再度クリックしたり、下記のように動画の一時停止/再生ボタンが行われたり、インラインで再生中に全画面表示に切り替えたりする場合等)
注意
動画広告の場合、mediaView内の再生/全画面再生/リプレイ/ランディングボタンがユーザーに表示されており、(Appendix画像 参照) これらのボタンをクリックしたときに全く反応がないのはUX上不自然なため、mediaViewを clickableViewsに指定していなくても該当の4か所のボタンはクリックが可能になっており、クリック時に onClicked コールバックが呼び出される
また、動画再生中に一時停止/再開動作のため、上にある再生ボタンが複数回押されることがあるが、この場合にも毎回 onClicked コールバックが呼び出される
推奨設定
Xっk
onRewardRequested (新規追加)
定義
広告についてのリワード付与条件を満たし、リワード付与リクエストが行われたことを示す
静止画広告の場合クリック後にしてLPに遷移後すぐに(1秒) 戻るボタンが押されなかった時、した場合動画広告の場合、最小再生時間を経過
重複呼び出しの有無
通常1回呼び出されるが、下の onRewardedの Failure条件を満たす場合呼び出されなかったり(リワード付与対象ではない場合) 重複して呼び出されたりすることがある (サーバーにてエラーにより付与が正しく行われずユーザーが再試行する場合)
注意
該当のコールバックは省略可能(リワード付与条件を満たさない場合リワードが付与されないのですが、このときはonRewarded コールバックにFailureとして送信される)
推奨設定
リワード付与完了についてのレスポンスを受け取るまでの間にローディング画像等を表示
動画の場合最小再生時間まで再生後リワードが付与されonClicked コールバックが複数回呼び出されるためonClicked コールバックではないonRewardRequested コールバックでローディング画像を表示することを推奨
onRewarded (新規追加)
定義
リワード関連の処理が完了したことを示す
重複呼び出しの有無
SUCCESSは1回のみ呼び出され、Failureの場合多様な理由により重複して呼び出されることがある
ステータス(result パラメータに含まれている AOS/iOS 伝達値)
SUCCESS / BABRewardResultSuccess : リワードの付与に成功し、付与完了
ALREADY_PARTICIPATED / BABRewardResultAlreadyParticipated : すでに参加済みの広告である
MISSING_REWARD / BABRewardResultMissingReward : リワードがない広告である
すでに参加済みの広告(rewardStatusが received) もこのコールバックが呼ばれるため、別途処理が必要
TOO_SHORT_TO_PARTICIPATE / BABRewardResultTooShortToParticipate : 静止画広告の場合ユーザーがクリック後にすぐに(1秒以内)戻るボタンを押してアプリに戻ってきた
NETWORK_TIMEOUT / BABRewardResultTimeout : リワード付与をリクエストしたがレスポンスを待つ間にタイムアウト(5秒)が発生した
BROWSER_NOT_LAUNCHED / BABRewardResultBrowserNotLaunched :広告をクリックしたが何らかの理由でブラウザが開かなかった
REQUEST_ERROR / BABRewardResultRequestError : 有効でないユーザーによるリワード付与リクエストが発生した
UNKNOWN_NETWORK_ERROR / BABRewardResultNetworkError : 何らかの理由によりネットワークエラーが発生した
UNKNOWN_SERVER_ERROR / BABRewardResultServerError : 何らかの理由でサーバー側にエラーが発生した
UNKNOWN_CLIENT_ERROR / BABRewardResultClientError : 何らかの理由でランタイムエラーが発生した
UNKNOWN_ERROR / BABRewardResultUnknownError : 上記以外のすべてのエラー
推奨設定
すべての場合においてonRewardRequestedで作成した “ローディング画像"がある場合は削除
SUCCESSの場合リワード付与完了アニメーションを表示
ALREADY_PARTICIPATED またはMISSING REWARDにてrewardStatusが receivedの場合についてすでに付与済みの広告である旨のメッセージを表示
TOO_SHORT_TO_PARTICIPATEにて広告をもう少し見るとリワードが付与される旨のメッセージを表示
それ以外の場合は通常のエラーメッセージを表示
onParticipated
定義
広告への参加完了
重複呼び出しの有無
1回だけ呼び出される
注意
ユーザーが1つの広告(A)に参加済みとなった時、その広告だけでなくSDKが現在読み込み済みのすべての同一広告(Buzzvilが付与したID値で区分)についても該当のコールバックが呼び出され広告のisParticipatedが trueに変更される
추천 대응
isParticipatedが trueの広告に対して適用するUI (リワード部分をなくし、付与処理済みであることを示すチェック表示など)を適用
CF. MediaViewイベントリスナーはAOSの場合連携文書を通じて動画プレイヤーにて発生したエラー値が送信される。 iOSは当該機能はなし。動画の詳細な再生ステータスについてのイベントリスナーは次回SDKアップデートで提供予定
ディープリンクURLを使用する広告に対するパラメータの受け渡し
Launcher使用時、nativeAd.getAd().getCreative().isDeeplink() / ad.creative.isDeeplink (AOS / iOS) の値として判断可能
trueの場合ブラウザが読み込まれるとGoogle Play Storeまたは広告主のアプリへと遷移するため、これについての適切な処理が必要
デフォルト値はfalseとして伝達
AOS: onClickEvent / iOS : shouldClickAd methodを使用したクリックHooking
動画/静止画広告の区分なく、そして動画広告内でもインライン再生時と全画面再生時の区分なくすべてonClickEvent/shouldClickAd methodでクリック時のイベントフッキングが可能
それぞれのmethodは各NativeAdViewオブジェクト(AOS)と Adviewオブジェクト(iOS)下に属する
APPENDIX
動画広告のMediaView関連画像
Reference: BuzzAd Benefit API 변경사항 (AOS 1.5.0, iOS 1.2.0)