関数のシグネチャ:
adBreak(
type: '<type>', // The type of this placement
name: '<name>', // A descriptive name for this placement
beforeAd: () => {}, // Prepare for the ad. Mute and pause the game flow
afterAd: () => {}, // Resume the game and re-enable sound
beforeReward: (showAdFn) => {}, // Show reward prompt (call showAdFn() if clicked)
adDismissed: () => {}, // Player dismissed the ad before completion
adViewed: () => {}, // Ad was viewed and closed
adBreakDone: (placementInfo) => {}, // Always called (if provided) even if an ad didn't show
);
adBreak() パラメータ
| 名前 | 型 | 説明 |
|---|---|---|
| すべてのプレースメント タイプ | ||
type |
文字列 | プレースメントのタイプ。値:
|
name |
文字列 | （省略可）ゲーム内でのこの広告のプレースメントの名前です。これは内部の識別子であり、プレーヤーには表示されませんが、今後のリリースでは、この識別子を使用してレポート機能と最適化機能を有効にすることができます。 すべてのプレースメントに名前を付けることをおすすめします。 |
beforeAd |
関数 | （省略可）広告が表示される前に呼び出されます。ゲームが一時停止し、音声がミュートされます。これらの操作は同期的に行われる必要があります。このコールバックが終了すると、すぐに広告が表示されます。 |
afterAd |
関数 | （省略可）広告の終了後（理由を問わず）呼び出されます。リワード広告の場合は、プレーヤーの操作に応じて、adDismissed または adViewed の後に呼び出されます。この関数は、ゲームフローを再開するために使用されます。たとえば、音声のミュートを解除して次のレベルを開始するために使用します。 |
adBreakDone |
関数 | （省略可）広告が表示されなくても、adBreak() の最後の手順として必ず呼び出されます。関数は、次のように定義された placementInfo オブジェクトを引数として受け取ります。adBreakDone と placementInfo() をご覧ください。 |
| リワード広告プレースメントのみ... | ||
beforeReward |
関数 | リワード広告が利用可能な場合に呼び出されます。この関数は 1 つの引数 showAdFn() を受け取ります。これは、リワード広告を表示するために呼び出す必要があります。 |
adDismissed |
関数 | リワード広告でプレーヤーが広告を閉じたときにのみ呼び出されます。広告が最後まで再生される前にプレーヤーが広告を閉じた場合にのみ呼び出されます。この場合、報酬は付与されません。 |
adViewed |
関数 | リワード広告でプレーヤーが広告を最後まで再生し、報酬を受け取るべきときにのみ、のために呼び出されます。 |
adBreakDone() and placementInfo
Ad Placement API に表示する広告がない場合、渡されたさまざまな before / after コールバックは呼び出されません。ただし、adBreakDone() コールバックを指定すると、広告が表示されていなくても、常に呼び出されます。これにより、プレースメントに関するさらなる分析結果を記録するなど、プレースメントに対して必要な追加の作業を行うことができます。
adBreakDone() 関数は引数として、次のように定義された placementInfo オブジェクトを受け取ります。
{
breakType: '<type>',
breakName: '<name>',
breakFormat: 'interstitial|reward',
breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}
このオブジェクト内のフィールドには、次のセマンティクスがあります。
breakTypeはadBreak()に渡される型引数です。breakNameはadBreak()に渡される名前引数です。breakStatusはこのプレースメントのステータスで、次のいずれかの値になります。
breakStatus |
理由 |
|---|---|
'notReady' |
Ad Placement API が初期化されていない |
'timeout' |
Ad Placement API の応答に時間がかかりすぎたため、プレースメントがタイムアウトした |
'invalid' |
プレースメントが無効であったため、無視された。たとえば、1 回のページ読み込みにつき使用できるプレロール プレースメントは 1 つのみで、それ以降のプレロールはこのステータスで失敗します |
'error' |
コールバックで JavaScript エラーが発生した |
'noAdPreloaded' |
広告がまだ読み込まれていないため、このプレースメントはスキップされた |
'frequencyCapped' |
このプレースメントにフリークエンシー キャップが適用されたため、広告が表示されなかった |
'ignored' |
ユーザーが次のプレースメントに到達する前に報酬のプロンプトをクリックしなかった。つまり、showAdFn() が次の adBreak() の前に呼び出されなかった |
'other' |
別の理由で広告が表示されなかった（例: まだ広告の取得中だった、または画面のサイズ変更や回転によって以前にキャッシュされた広告が破棄された） |
'dismissed' |
ユーザーが視聴完了前にリワード広告を閉じた |
'viewed' |
ユーザーが広告を閲覧した |
注: adBreakDone() は常に、adBreak() が最後に呼び出すコールバックです。
afterAd() を使用して広告の表示後にゲームの一時停止を解除した場合、ゲームが再開した後に adBreakDone() が呼び出されます。分析のロギングなどではこれが適切な場合もありますが、ゲームが再起動する前に追加の作業を行う場合は、ゲームの一時停止を解除するロジックを afterAd() から adBreakDone() に移動します。