Используйте API размещения рекламы

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() — ключевая функция для размещения рекламы в игре. Она определяет место размещения рекламы и принимает объект, называемый конфигурацией размещения , который определяет всё необходимое для показа рекламы.

Функция adBreak() определяет место, где может быть показано объявление. Показ объявления зависит от следующих факторов:

  • Тип размещения рекламы, который вы заявили
    • Эта реклама появляется в начале игры? Между уровнями? В тот момент, когда игрок поставил игру на паузу?
  • Существует ли подходящая реклама для текущего игрока
    • Имеет ли эта реклама отношение к ним?
    • Соответствует ли это их настройкам конфиденциальности данных и согласия?
  • Количество рекламы, которую игрок видел в последнее время
  • Настройки управления, например, частота показа рекламы, которые вы настроили для этой игры.
    • Либо как подсказки в теге, либо,
    • В AdSense — обратите внимание, что элементы управления, доступные в AdSense, со временем будут развиваться.

Вид показываемой рекламы также зависит от аналогичных факторов.

Обратите внимание, что вызов adBreak() может вообще не показывать рекламу. Он просто указывает место, где может быть показана реклама.

Это отличается от традиционных API, в которых ваш код всегда знает, доступна ли реклама, и вы решаете в игре, показывать её или нет. Такой подход, когда 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 является обязательным, и мы рекомендуем всегда называть места размещения . Остальные обратные вызовы необязательны.

Последовательность вызовов

Проверьте последовательность вызовов для промежуточной рекламы.

Диаграмма последовательности вызовов межстраничной рекламы

Описание

Interstitial – Подробная последовательность вызовов
Ваша игра H5 API размещения рекламы
Инициализация и предварительная загрузка рекламы
Запуск игры

Хорошая возможность показать рекламу...

adBreak() →

Есть доступное объявление, и сейчас самое время его показать...

← beforeAd()

Игра останавливается, отключает звук и готовится к показу рекламы.

return к API →

API размещения рекламы отображает полноэкранную рекламу. Игрок может нажать на рекламу (она откроется в новой вкладке). Чтобы продолжить игру, необходимо закрыть рекламу.
← afterAd() вызывается, если была показана реклама
Игра снимается с паузы и включается звук.
← adBreakDone() adBreakDone() вызывается всегда (даже если реклама не была показана)
Игра ведет аналитику по данному размещению.

Примечания

  • adBreak() — асинхронная функция, которая возвращает результат немедленно.
  • Если для размещения нет рекламы, то ни один из обратных вызовов не вызывается, то есть ни один из методов beforeAd() и afterAd() не вызывается.
  • Чтобы гарантировать, что ваша игра не продолжит работу во время показа рекламы, используйте обратный вызов beforeAd() , чтобы отключить звук и приостановить игру.
  • beforeAd() является синхронным, 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,
})
Preroll – Подробная последовательность вызовов
Ваша игра H5 API размещения рекламы
Начинается инициализация API и предварительное кэширование рекламы
Работает, но не запущен и не отображает пользовательский интерфейс.

adBreak(type:'preroll',…) →

API размещения рекламы завершает инициализацию и загрузку рекламы. Если есть реклама, она отображается. Игрок может нажать на неё (она откроется в новой вкладке). Чтобы начать игру, необходимо закрыть её.

← adBreakDone() всегда вызывается (даже если реклама не была показана)

Игровой интерфейс отображается на экране, и игрок теперь может с ним взаимодействовать. Игра может использовать объект placementInfo переданный в adBreakDone() по мере необходимости (например, для регистрации дополнительной аналитики).

Примечания

  • Преролл всегда будет пытаться предварительно загрузить рекламу:
    • Вызов adConfig(preloadAds: 'on') не требуется для прероллов.
  • Как и другие места размещения рекламы, преролл может показывать или не показывать рекламу.
  • beforeAd() и afterAd() не следует передавать в преролл.
    • Поскольку реклама в начале игры показывается перед ее началом, нет необходимости приостанавливать или отключать звук игры.
    • Если вы передадите beforeAd() или afterAd() с предварительной трансляцией, вызов завершится ошибкой, и в консоли JavaScript будет зарегистрирована ошибка.
  • Преролл автоматически ожидает, пока API размещения рекламы инициализируется и предварительно загружает рекламу:
    • Однако существует тайм-аут (2 с), который предотвращает бесконечное затягивание вызова. Это гарантирует своевременный вызов adBreakDone() и запуск игры.
    • adBreakDone() вызывается всегда, даже если рекламы нет.
  • Мы рекомендуем вам использовать преролл для размещения рекламы перед началом игры.
    • В качестве альтернативы вы можете использовать обратный вызов onReady() для adConfig() в качестве механизма для упорядочивания логики вашей игры с инициализацией API и предварительной загрузкой рекламы.

Реклама с вознаграждением

Реклама с вознаграждением позволяет вознаграждать игроков внутриигровыми предметами, если они решат посмотреть рекламу. В то время как полноэкранная реклама не требует отказа , игрок видит рекламу и может её закрыть. Реклама с вознаграждением — это реклама с согласием . Игрок сам выбирает, хочет ли он смотреть рекламу и когда именно, чтобы получить вознаграждение.

В отличие от полноэкранной рекламы, где игрок может закрыть рекламу в любой момент, для получения вознаграждения он должен просматривать рекламу в течение определенного минимального периода времени (который может варьироваться в зависимости от показываемого рекламного креатива).

Поскольку реклама с вознаграждением не является обязательной для игрока, она требует более глубокой интеграции в игровой процесс. Вам необходимо предоставить функции для отображения подсказки о вознаграждении в игре и для назначения вознаграждения игроку, посмотревшему рекламу.

Награды не должны иметь ценности вне вашего приложения, не должны иметь денежной стоимости (или легко обмениваться на неё), не должны продаваться или обмениваться на товары и услуги, и не должны побуждать игроков нажимать на рекламу. Подробнее см. в проекте политики для полноэкранных объявлений и наград.

Поскольку награды не являются обязательными для игрока, вы можете добавлять их в любое удобное место в игре и использовать в дополнение к полноэкранным объявлениям. Как и полноэкранные объявления, эти места размещения предоставляют возможность показывать рекламу с вознаграждением. API размещения рекламы будет вызывать ваш код только в том случае, если реклама с вознаграждением будет показана в определённом моменте игры.

Цель здесь снова состоит в том, чтобы позволить вам интегрировать вашу игру с 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 API размещения рекламы
Инициализация и предварительное кэширование рекламы
Запуск игры

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

Есть доступная реклама, поэтому начните размещение рекламы с вознаграждением. beforeReward() вызывается синхронно – сразу после вызова adBreak()

← beforeReward(showAdFn)

Игра отображает подсказку о награде. Это даёт игроку возможность получить награду, посмотрев рекламу. Награды могут быть разными (например, новая жизнь или золотая монета).

Игрок может нажать на подсказку о вознаграждении, отклонить ее или просто игнорировать.

Если они нажимают на подсказку, игра сохраняет тип запрошенной награды и вызывает showAdFn()...

В противном случае, если запрос на вознаграждение будет отклонен или проигнорирован, ничего не произойдёт, пока вы не выполните ещё один вызов adBreak() с типом размещения вознаграждения. После этого API размещения рекламы сбросит и очистит состояние, оставшееся после этого вызова. Если приложение вызовет showAdFn из предыдущей рекламной паузы, это не повлияет на результат.

showAdFn() →

← beforeAd()

Игра останавливается, отключает звук и готовится к показу рекламы.

return к API →

API показывает рекламу. У неё есть кнопка закрытия и обратный отсчёт оставшегося времени показа.
ЕСЛИ игрок закроет рекламу...
← adDismissed()
Игрок отклонил рекламу, и игра не выдала награду.
ИНАЧЕ игрок досмотрит рекламу до конца...
← adViewed()
Игрок досматривает рекламу до конца, и игра выдает награду. (Обычно это достигается путем установки некоторого игрового состояния, которое затем активируется при перезапуске игры с помощью вызова afterAd() ниже).
После просмотра или закрытия рекламы...
← afterAd() вызывается, если была показана реклама
Игра снимается с паузы и включается звук.
← adBreakDone() adBreakDone() вызывается всегда (даже если реклама не была показана)
Игра ведет аналитику по данному размещению.

Примечания

  • adBreak() — асинхронная функция, которая возвращает результат немедленно.
  • Если для размещения нет рекламы, то ни один из обратных вызовов не вызывается, то есть не вызывается ни один из методов beforeAd() и beforeReward() .
  • Чтобы гарантировать, что ваша игра не продолжит работу во время показа рекламы, используйте обратный вызов beforeAd() , чтобы отключить звук и приостановить игру.
  • beforeAd() является синхронным, API размещения рекламы не будет показывать рекламу, пока не вернется.
  • Перезапустите игру и включите звук, когда получите вызов afterAd() .
  • Если указано, adBreakDone() всегда вызывается, даже если реклама не была показана в этом месте размещения.
  • Вызов adBreak() во время показа другой рекламы завершится ошибкой, а на консоли JavaScript будет отображено предупреждение.