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

Функция 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 является обязательным, и мы рекомендуем всегда называть места размещения . Другие обратные вызовы являются необязательными.

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

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

Описание

Примечания

• 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,
})

Примечания

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

Объявления с вознаграждением

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

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

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

Вознаграждения не должны иметь ценности за пределами вашего приложения, они не должны иметь (или легко обмениваться) денежной стоимости, не должны продаваться или обмениваться на товары и услуги, и вы не должны поощрять игроков нажимать на рекламу. Дополнительные сведения см. в проекте политики в отношении межстраничных объявлений и вознаграждений.

Поскольку награды не являются обязательными для игрока, вы можете добавить их в любое место, где это имеет смысл в вашей игре, и использовать их в дополнение к межстраничным объявлениям. Как и межстраничные объявления, эти места размещения позволяют показывать рекламу с вознаграждением. 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,
});

Объявления с вознаграждением начинаются с подсказки в вашей игре, предлагающей игроку вознаграждение, если он увидит рекламу.

Последовательность звонков для объявления с вознаграждением

Описание

Примечания

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