Ad Placement API を使用する

Ad Placement API には、次のように、グローバル名前空間で定義された adBreak() と adConfig() の 2 つの関数が含まれています。ほとんどの引数は、広告を準備し表示するための主要なステップを処理するために指定する関数です。

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 un-mute the 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
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

これらの関数は、ゲーム内の広告の配置と設定に使用されます。これらの関数に渡すことができる有効な引数は、上記の引数のみです。この中で必須となる引数は、後述のとおり、広告の種類によって異なります。

adBreak() は、ゲーム内に広告を配置するうえで主要な役割を果たす関数です。広告プレースメントを定義し、広告を表示するために必要なすべてのものを指定する「プレースメント設定」と呼ばれるオブジェクトを取ります。

adBreak() 関数の役割はあくまで、広告を表示可能な場所を定義することに留まります。実際に広告が表示されるかどうかは、たとえば次の要素に左右されます。

  • 宣言した広告プレースメントのタイプ
    • どのタイミングで表示される広告か（ゲーム開始時、ステージ間、プレーヤーがゲームを一時停止したとき）
  • 現在のプレーヤーに合った広告が存在するかどうか
    • 該当プレーヤーにとって的確な広告かどうか
    • 該当プレーヤーによるデータ プライバシーや同意に関する設定に適合しているかどうか
  • ユーザーに最近表示された広告の数
  • パブリッシャー様が該当ゲームに対して指定した制御設定（フリークエンシーなど）
    • タグ内のヒントとして指定した設定
    • AdSense 内での設定（注: AdSense でご利用いただける制御設定は改良により順次変化します）

表示される広告の種類も、同様の要素に左右されます。

adBreak() を呼び出しても、広告がまったく表示されないこともある点に注意しましょう。この関数の役割はあくまで、広告を表示可能な場所を宣言することです。

これは、広告が利用可能かどうかをコードで常に把握し、広告を表示するかどうかをゲーム内で決定する従来の API とは異なります。この方法では、Ad Placement API を使用して、特定のプレースメントに広告を表示するかどうかを「コントロールの反転」というパターンで判断できるようにしています。

ゲームの API をこのモデルに移行する理由は、まず、ゲーム内で記述する必要があるコードが短縮されることです。また、優れたユーザー エクスペリエンスを実現するとともに、ポリシーを遵守したプレースメントを簡単に配信できるようになったことで、最も成果の高いフォーマットの一部をゲーム パブリッシャーに提供できるようになりました。さらに、このモデルでは、ゲーム内に広告を表示するプロセスと、表示する広告の種類や数に関する収益化の判断が、より明確に区別されています。

このモデルは、ゲームを変更して新バージョンとしてリリースすることなく、収益化に関する設定の変更やユーザー エクスペリエンスの制御ができるようすることを目指すものです。当面はタグ内でヒントを指定する必要がありますが、今後のリリースでは、AdSense と AdMob の管理画面で直接管理できるようになる予定です。

インタースティシャル

インタースティシャル広告は、プレーヤーがゲームを開始した時点やレベルをクリアした後など、ゲーム内のさまざまな場面で表示される全画面広告です。ゲームが一時停止され、ドキュメント全体に表示されます。プレーヤーは、広告をクリックするか（広告がブラウザの別のタブに表示されます）、広告を閉じて先に進むことができます。

インタースティシャル広告を配置するには、プレースメント設定内の次のフィールドに値を入力します。

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

type 引数は必須です。プレースメントには必ず名前を付けることをおすすめします。その他のコールバックは任意です。

呼び出しシーケンス

インタースティシャル広告の呼び出しシーケンスを確認します。

インタースティシャル広告の呼び出しシーケンスの図

説明

インタースティシャル – 呼び出しシーケンスの詳細
H5 ゲーム Ad Placement API
  広告の初期化とプリロード
ゲームの実行  

広告を表示する機会

adBreak() →

 
 

利用可能な広告があり、今が広告表示のチャンスです

← beforeAd()
ゲームが一時停止し、音声がミュートされて、広告の表示準備が開始されます。

API への return →

 
  Ad Placement API はインタースティシャル広告をレンダリングします。プレーヤーが広告をクリックできます（クリックすると、新しいタブに表示されます）。ゲームのプレイを続けるには、広告を閉じる必要があります。
  ← afterAd() は広告が表示された場合に呼び出されます
ゲームが一時停止を解除して音声のミュートを解除します。  
  ← adBreakDone()adBreakDone() は必ず呼び出されます（広告が表示されていなくても）
このプレースメントに関する分析がゲームに記録されます。  

備考

  • adBreak() は、すぐに返される非同期関数です。
  • プレースメントに表示する広告がない場合、コールバックは呼び出されません（beforeAd() も afterAd() も呼び出されません）。
  • 広告の表示中はゲームが続行しないようにするには、beforeAd() コールバックを使用して音声をミュートし、ゲームを一時停止します。
  • beforeAd() は同期的であるため、返されるまで Ad Placement API によって広告が表示されません。
  • afterAd() 呼び出しを受け取ったら、ゲームを再起動して音声のミュートを解除します。
  • 指定した場合、広告がこのプレースメントに表示されていなくても、必ず adBreakDone() が呼び出されます。
  • 別の広告が表示されている間に adBreak() を呼び出すと失敗し、JavaScript コンソールに警告が表示されます。

プレロール

プレロールは、ゲームが UI を読み込む前に表示されるインタースティシャルです。プレーヤーがゲームに移動したときに最初に表示されるページです。プレロールはページ読み込みのかなり早い段階で行われ、ゲームがまだ表示されていないため、ゲームの一時停止とミュートのための通常の呼び出しは必要ありません。代わりに、adBreakDone() コールバックを使用して、ゲームの開始と広告表示の順序を設定します（つまり、UI をレンダリングし、音声の再生を開始します）。ページの読み込みごとにトリガーできるプレロールは 1 つのみです。

呼び出しシーケンス

プレロールの呼び出しは、ページ読み込みのかなり早い段階で行われます。この時点ではゲームは UI をレンダリングしていないため、beforeAd() と afterAd() のコールバックを渡さないでください。代わりに、プレースメントの後に adBreakDone() コールバックを使用してゲームを開始します。この処理は、広告が含まれていなくても必ず呼び出されます。

プレロール広告呼び出しシーケンスの図

次のコードをゲームのロジックの早い段階で呼び出すと、プレロール広告が配置されます。このコードが呼び出される前に UI をレンダリングしないでください。

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
プレロール - 呼び出しシーケンスの詳細
H5 ゲーム Ad Placement API
  API 初期化と広告の事前キャッシュ開始
ゲームは実行されているが、開始しておらず、UI が表示されていない  

adBreak(type:'preroll',…) →

 
 

Ad Placement API は、広告の初期化と読み込みを完了します。広告があれば表示されます。プレーヤーが広告がクリックすると、広告が新しいタブに表示されます。ゲームを再開するには、広告を閉じる必要があります。

 

← adBreakDone() は必ず呼び出されます（広告が表示されなくても）

ゲームの UI が画面にレンダリングされ、プレーヤーが操作できるようになります。ゲームは必要に応じて adBreakDone() に渡された placementInfo オブジェクトを使用できます（追加の分析を記録するためなど）。

  

備考

  • プレロールは常に広告のプリロードを試みます。
    • プレロールの場合、adConfig(preloadAds: ‘on') を呼び出す必要はありません。
  • 他の広告プレースメントと同様に、プレロールでは広告が表示される場合とされない場合があります。
  • beforeAd() と afterAd() はプレロールに渡さないでください。
    • プレロール広告はゲーム開始前に実行されるため、ゲーム音声を一時停止またはミュートする必要はありません。
    • プレロールで beforeAd() または afterAd() を渡すと、呼び出しは失敗し、JavaScript コンソールにエラーが記録されます。
  • プレロールは自動的に、Ad Placement API が初期化されて広告のプリロードが行われるのを待ちます。
    • ただし、呼び出しが無期限に遅延することを防ぐタイムアウト（2 秒）があります。これにより、adBreakDone() が適切なタイミングで呼び出され、ゲームが開始されます。
    • adBreakDone() は広告がない場合でも必ず呼び出されます。
  • ゲーム開始前にプレロールを使用して広告を配置することをおすすめします。
    • または、API の初期化と広告のプリロードを使用してゲームロジックをシーケンスするメカニズムとして、adConfig() への onReady() コールバックを使用できます。

リワード広告

リワード広告を使用すると、広告を視聴することを選んだユーザーに報酬としてアプリ内アイテムを進呈できます。インタースティシャルはオプトアウトであり、プレーヤーに広告が表示され、プレーヤーはこの広告を閉じることを選択できます。リワード広告はオプトインです。プレーヤーは、報酬を受け取るために広告を視聴するかどうかを選択できます。

いつでも広告を閉じることができるインタースティシャルとは異なり、報酬を受け取るには、広告を一定時間視聴する必要があります（時間は、表示されている広告クリエイティブによって異なります）。

リワード広告はプレーヤーにとってオプションであるため、ゲームフローの中に組み込む必要があります。ゲーム内に報酬プロンプトをレンダリングし、広告を視聴するユーザーに報酬を割り当てる関数を設定する必要があります。

報酬として、アプリ外で価値のあるものを提供することはできません。金銭的価値を持たず（または簡単に金銭的価値と交換することもできず）、商品やサービスと交換できないものである必要があります。プレーヤーにクリックを促すこともできません。 詳しくは、インタースティシャルとリワードに関するポリシー（下書き）をご確認ください。

プレーヤーにとって報酬はオプションであるため、ゲーム内で意味がある場所であればどこにでも追加でき、インタースティシャルと組み合わせて使用することもできます。インタースティシャルと同様に、このプレースメントはリワード広告を表示する機会です。 Ad Placement API は、リワード広告がゲームの特定のタイミングで実際に提供される場合にのみ、コードを呼び出します。

ここでも、目標は、ゲームと Ad Placement API を一度統合したら、後はタグや AdSense でコントロールを使用して、表示する広告の組み合わせを自在に変更できるようにすることです。ゲームを再コーディングして再リリースする必要はありません。

リワード広告のプレースメントのタイプは常に 'reward' で、プレースメント設定のすべてのフィールドを使用できます。

adBreak({
   type: 'reward',                      // 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 it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

主な新機能として、リワード広告のプロンプトをレンダリングするためのシグナルをトリガーする beforeReward() と、プレーヤーが広告の視聴を完了したときに報酬割り当てのために呼び出される adViewed() があります。

リワード プレースメントは、次のように定義できます。

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

リワード広告はまず、広告を視聴したプレーヤーに報酬を提供するというプロンプトをユーザーに表示します。

広告のメッセージ例: 動画を視聴するとライフがもらえます！

リワード広告の呼び出しシーケンス

リワード広告の呼び出しシーケンスの図

説明

リワード広告 – 呼び出しシーケンスの詳細
H5 ゲーム Ad Placement API
  初期化と広告の事前キャッシュ
ゲームの実行  

adBreak(type:'reward', ... ) →

 
 

広告があるため、リワード広告のプレースメントを開始します。beforeReward() は、adBreak() の呼び出しと同期して直後に呼び出されます

← beforeReward(showAdFn)

ゲームで報酬プロンプトがレンダリングされます。これは、広告を視聴すると報酬を受け取ることができる旨をプレーヤーに知らせるものです。新しいライフやコインなど、複数の種類の報酬を提供できます。

プレーヤーは、報酬プロンプトをクリックするか、閉じることができます。無視することもできます。

プロンプトをクリックすると、ゲームはプレーヤーがリクエストした報酬を保存し、showAdFn()... を呼び出します。

報酬プロンプトを閉じるか無視した場合、報酬プレースメント タイプで adBreak() をもう一度呼び出すまで何も起こりません。この時点で、状態がリセットされ、この呼び出しから削除されます。アプリが前の広告ブレークから showAdFn を呼び出しても効果はありません。

  

showAdFn() →

 
  ← beforeAd()

ゲームが一時停止し、音声がミュートされて広告の表示準備が整います

API への return →

 
  広告が表示されます。広告には、「閉じる」ボタンと広告の残り時間を示すカウントダウンがあります。
プレーヤーが広告を閉じた場合
  ← adDismissed()
プレーヤーは広告を閉じ、報酬は提供されません。  
プレーヤーが広告を最後まで視聴した場合
  ← adViewed()
プレーヤーは広告を最後まで視聴し、報酬を獲得しました（通常は、下記の afterAd() の呼び出しでゲームが再起動すると取得されるゲーム ステータスを設定することで行われます）。  
広告を視聴した、または広告を閉じた後
  ← afterAd() は広告が表示された場合に呼び出されます
ゲームが一時停止を解除して音声のミュートを解除します。  
  ← adBreakDone()adBreakDone() は必ず呼び出されます（広告が表示されていなくても）
このプレースメントに関する分析がゲームに記録されます。  

備考

  • adBreak() は、すぐに返される非同期関数です。
  • プレースメントに表示する広告がない場合、コールバックは呼び出されません（beforeAd() も beforeReward() も呼び出されません）。
  • 広告の表示中はゲームが続行しないようにするには、beforeAd() コールバックを使用して音声をミュートし、ゲームを一時停止します。
  • beforeAd() は同期的であるため、返されるまで Ad Placement API によって広告が表示されません。
  • afterAd() 呼び出しを受け取ったら、ゲームを再起動して音声のミュートを解除します。
  • 指定した場合、広告がこのプレースメントに表示されていなくても、必ず adBreakDone() が呼び出されます。
  • 別の広告が表示されている間に adBreak() を呼び出すと失敗し、JavaScript コンソールに警告が表示されます。