使用 Ad Placement API

Ad Placement API 包含 adBreak() 和 adConfig() 这两个在以下全局命名空间中定义的函数。大多数参数都是您提供的函数，可让您处理准备和展示广告的关键步骤：

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() 是用于在游戏内投放广告的关键函数。它可定义广告展示位置，并接收一个名为 placement config 的对象，此对象指定了展示广告所需的所有内容。

adBreak() 函数可定义广告的展示位置。广告是否能真正展示取决于多种因素，例如以下因素：

  • 您声明的广告展示位置的类型
    • 此广告是在游戏开始时，在游戏关卡之间，还是在玩家已暂停游戏时展示？
  • 是否存在适合向当前玩家展示的广告
    • 此广告是否与玩家相关？
    • 是否符合玩家的数据隐私和意见征求设置？
  • 玩家近期看到的广告数量
  • 您为相应游戏配置的控制设置（例如广告展示频次）
    • 可以是标记中的提示，或者是
    • AdSense 中的控件（请注意：AdSense 的控件会随着时间的推移而变化。）

展示的广告种类也取决于类似的因素。

请注意，调用 adBreak() 可能根本不会展示广告。它仅会声明广告可以展示的位置。

这与传统 API 不同，在传统 API 中，您的代码始终知道是否有广告可供投放，并且是否在游戏内展示此广告是由您决定的。而这种方法则让 Ad Placement API 决定广告是否在特定展示位置展示，因此有时被称为“控制反转”模式。

我们出于多方考虑，决定在游戏 API 中改用这种模型。首先，此模型可以缩减您需要在游戏内编写的代码。其次，这种模型可让我们更轻松地提供符合政策要求且能带来出色用户体验的展示位置，从而允许我们向游戏发行商提供一些效果出众的广告格式。最后，该模型可以将游戏中投放广告的流程分离出来，从而与那些事关展示的广告类型及数量的创收决策进行更明晰的区分。

我们希望您能够在不修改游戏和发布游戏新版本的情况下，更改创收设置并控制用户体验，现阶段，您需要在标记中指定提示。但在以后的版本中，我们将能够直接在 AdSense 和 AdMob 前端提供控制功能。

插页式广告

插页式广告是一种全屏广告，可在游戏中的不同时刻展示，例如在玩家开始游戏时，或在玩家过关后。插页式广告会暂停游戏，覆盖整个文档，而玩家可以选择点击广告（在这种情况下，广告会在浏览器的新标签页中展示），也可以选择关闭广告，以便继续玩游戏。

如要投放插页式广告，请按以下形式填充 placement config 内的字段：

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()
游戏暂停、静音，并准备展示广告。

return 到 API →

 
  Ad Placement API 呈现插页式广告。玩家可点击广告（广告将在新标签页中展示）。他们必须关闭广告才能继续玩游戏。
  ← 如果广告已展示，则调用 afterAd()
游戏取消暂停并取消静音。  
  ← 始终调用 adBreakDone()adBreakDone()（即使广告未展示也调用）
游戏记录有关此展示位置的分析数据。  

备注

  • adBreak() 是异步函数，会立即返回结果。
  • 如果没有要在某个展示位置展示的广告，则不会调用任何回调（即，不调用 beforeAd()、afterAd()）。
  • 为了确保在广告展示期间游戏不会继续，请使用 beforeAd() 回调来静音并暂停游戏。
  • beforeAd() 是同步的，因此在它返回之前，Ad Placement API 不会展示广告。
  • 收到 afterAd() 调用后，重新开始游戏并取消静音。
  • 如果提供，系统将始终调用 adBreakDone()，即使此展示位置未展示广告也是如此。
  • 在展示其他广告时调用 adBreak() 会失败，并且 JavaScript 控制台上会显示警告消息。

前贴片广告

前贴片广告是在游戏界面加载之前显示的插页式广告。这是玩家进入游戏后最先看到的内容。由于前贴片广告是在网页加载初期展示，这时您的游戏还未显示，因此无需暂停游戏和将其静音的常规调用。您可以改用 adBreakDone() 回调来安排游戏启动与广告的顺序，即呈现界面并开始播放声音。每次网页加载时只能触发一个前贴片广告。

调用顺序

在网页加载初期调用前贴片广告。由于此时游戏界面尚未呈现，因此您不应传递 beforeAd() 和 afterAd() 回调。请改为使用 adBreakDone() 回调，以便在该展示位置之后启动游戏，因为即使没有广告，它也会得到调用。

前贴片广告调用顺序示意图

在游戏运行逻辑早期调用以下代码会投放前贴片广告。在调用此代码之前，您的界面不应呈现给用户。

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
前贴片广告 - 详细的调用顺序
您的 H5 游戏 Ad Placement API
  开始初始化 API 并预缓存广告
正在运行但尚未启动，且未显示界面  

adBreak(type:'preroll',…) →

 
 

Ad Placement API 完成初始化和广告加载。如果展示广告，玩家可点击广告（广告将在新标签页中展示）。玩家必须关闭广告，才能开始游戏。

 

← 始终调用 adBreakDone()adBreakDone()（即使广告未展示也调用）

游戏界面会呈现在屏幕上，玩家现在可以与之互动。游戏可以根据需要使用传递给 adBreakDone() 的 placementInfo 对象（例如，记录其他分析数据）。

  

备注

  • 前贴片广告始终会尝试预加载广告：
    • 前贴片广告无需调用 adConfig(preloadAds: ‘on')。
  • 与其他广告展示位置一样，前贴片广告不一定会展示广告。
  • beforeAd() 和 afterAd() 不应传递到前贴片广告。
    • 由于前贴片广告在游戏开始之前投放，因此无需暂停游戏或将其静音。
    • 如果您通过前贴片广告传递 beforeAd() 或 afterAd()，调用将失败，并且 JavaScript 控制台将记录错误。
  • 前贴片广告会自动等待 Ad Placement API 初始化并预加载广告：
    • 此外，超时事件 (2s) 可以防止调用无限延迟。这可以确保及时调用 adBreakDone()，让游戏启动。
    • 即使没有广告，也会始终调用 adBreakDone()。
  • 我们建议您在游戏开始前使用前贴片展示位置投放广告。
    • 或者，您也可以将 adConfig() 的 onReady() 回调作为一种机制，以利用 API 初始化和预加载广告来对游戏运行逻辑进行排序。

激励广告

借助激励广告，您可以在玩家选择观看广告后，为其提供应用内商品作为奖励。相较而言，插页式广告可以选择退出观看，因此玩家看到广告后，可以选择将其关闭。激励广告则是由用户主动收看。玩家可以选择是否以及何时观看广告，以获得奖励。

与插页式广告（玩家可以随时关闭广告）不同，为了获得奖励，他们必须观看广告达到一定的时间（可能会因展示的广告素材而异）。

由于激励广告对玩家来说是可选的，因此激励广告需要更与游戏流程实现更深层的整合。您必须提供函数，以在游戏内显示奖励提示，并在玩家观看广告后为其分配奖励。

奖励不得在应用之外具有价值，不得有货币价值（或能被轻松兑换成货币），也不得是可出售商品或用于交换商品和服务，而且您不应鼓励玩家点击广告。 如需了解详情，请参阅针对插页式广告和激励广告的政策草稿版。

由于奖励对玩家来说是可选的，因此您可以在游戏内所有合适的位置添加奖励，并将其与插页式广告一起使用。与插页式广告一样，这些展示位置也是展示激励广告的机会。 只有在游戏中的特定时间点实际展示了激励广告，Ad Placement API 才会调用您的代码。

同样，这样做也是为了让您在将游戏与 Ad Placement API 集成后，逐步使用标记中的控件或 AdSense 中的控件，对已开始投放的广告阵容进行更精准的调整，而无需重新编写代码以及重新发布游戏。

激励广告展示位置类型始终为 'reward'，且 placement config 中的所有字段均可使用。

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() 之前，系统不会执行任何操作，此时 Ad Placement API 会重置并清除该调用中的状态。如果应用从上一个广告插播时间点调用 showAdFn，则无效。

  

showAdFn() →

 
  ← beforeAd()

游戏暂停、静音，并准备展示广告。

return 到 API →

 
  API 展示广告。系统会显示“关闭”按钮，以及广告剩余时间倒计时。
如果玩家关闭广告…
  ← adDismissed()
玩家关闭了广告，游戏不会发放奖励。  
或者玩家完整观看广告…
  ← adViewed()
玩家完整观看广告，游戏发放奖励。（这通常是通过以下方式实现的：设置在游戏重新开始并调用以下 afterAd() 时会选择的某些游戏状态）。  
用户观看或关闭广告后…
  ← 如果广告已展示，则调用 afterAd()
游戏取消暂停并取消静音。  
  ← 始终调用 adBreakDone()adBreakDone()（即使广告未展示也调用）
游戏记录有关此展示位置的分析数据。  

备注

  • adBreak() 是异步函数，会立即返回结果。
  • 如果没有要在某个展示位置展示的广告，则不会调用任何回调（即，不调用 beforeAd()、beforeReward()）。
  • 为了确保在广告展示期间游戏不会继续，请使用 beforeAd() 回调来静音并暂停游戏。
  • beforeAd() 是同步的，因此在它返回之前，Ad Placement API 不会展示广告。
  • 收到 afterAd() 调用后，重新开始游戏并取消静音。
  • 如果提供，系统将始终调用 adBreakDone()，即使此展示位置未展示广告也是如此。
  • 在展示其他广告时调用 adBreak() 会失败，并且 JavaScript 控制台上会显示警告消息。