Cómo utilizar la API de Ad Placement

La API de Ad Placement contiene dos funciones: adBreak() y adConfig(), definidas en el siguiente espacio de nombres global. La mayoría de los argumentos son funciones que proporcionas y que te permiten controlar los pasos clave para preparar y mostrar un anuncio:

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
});

Estas funciones se usan para ubicar y configurar anuncios dentro del juego. Los argumentos anteriores son los únicos que se pueden pasar a estas funciones. Los diferentes tipos de anuncios requieren diferentes subconjuntos de estos argumentos, como se detalla a continuación.

adBreak() es la función clave para colocar anuncios en tu juego. Define una colocación de anuncios y toma un objeto llamado configuración de posición que especifica todo lo necesario para mostrar un anuncio.

La función adBreak() define una posición en la que podría mostrarse un anuncio. La publicación de un anuncio depende de factores como los siguientes:

• El tipo de posición del anuncio que declaró
  • ¿Este anuncio está al principio del partido? ¿Entre niveles? ¿El momento en el que el jugador pausó el juego?
• Si existe un anuncio adecuado para el jugador actual
  • ¿Este anuncio es relevante para ellos?
  • ¿Es coherente con la configuración de privacidad y consentimiento de sus datos?
• La cantidad de anuncios que vio el jugador recientemente
• La configuración de controles; por ejemplo, la frecuencia de los anuncios que configuró para este juego
  • como sugerencias en la etiqueta
  • En AdSense, tenga en cuenta que los controles disponibles en AdSense evolucionarán con el tiempo.

El tipo de anuncio que se muestra también depende de factores similares.

Ten en cuenta que es posible que una llamada a adBreak() no muestre un anuncio. Solo declara un lugar en el que podría mostrarse un anuncio.

Esto se diferencia de las API tradicionales en las que tu código siempre sabe si un anuncio está disponible y tú decides si mostrarlo en el juego. Este enfoque de permitir que la API de Ad Placement decida si un anuncio se muestra en una posición en particular es un patrón que a veces se denomina "inversión de control".

El motivo por el que realizamos la transición de nuestra API de juegos a este modelo es que, en primer lugar, acorta el código que tienes que escribir en tu juego. En segundo lugar, facilita la entrega de posiciones que cumplen con las políticas y brinda una excelente experiencia del usuario, lo que, a su vez, nos permitió ofrecer algunos de nuestros formatos con mejor rendimiento a los publicadores de juegos. Por último, separa con mayor claridad el proceso de colocar anuncios en tu juego de las decisiones de monetización sobre el tipo y la cantidad de anuncios que se mostrarán.

Queremos que puedas cambiar la configuración de monetización y controlar la experiencia del usuario sin tener que editar ni lanzar una nueva versión de tu juego, inicialmente al especificar sugerencias en la etiqueta. Sin embargo, en futuras versiones podremos proporcionar controles directamente en los frontends de AdSense y AdMob.

Anuncios intersticiales

Un anuncio intersticial es un anuncio de pantalla completa que puede mostrarse en diferentes momentos dentro del juego, como cuando el jugador inicia el juego o después de completar un nivel. Pausa el juego y cubre todo el documento. El jugador puede hacer clic en el anuncio (en cuyo caso, el anuncio se muestra en otra pestaña de su navegador) o descartarlo y así poder continuar con el juego.

Nota: Se puede mostrar un anuncio intersticial antes de que el juego cargue incluso su interfaz de usuario. Este tipo de anuncio se denomina anuncio previo al video y debe tratarse de manera ligeramente diferente a los anuncios intersticiales normales. Más información sobre los anuncios previos al video

Para colocar un anuncio intersticial, propaga los siguientes campos dentro de la configuración de posición:

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
});

El argumento type es obligatorio, y te recomendamos que nombres siempre tus posiciones. Las otras devoluciones de llamada son opcionales.

Secuencia de llamadas

Revise la secuencia de llamada de un anuncio intersticial.

Descripción

Intersticial: secuencia de llamada detallada
Su juego H5	API de Ad Placement
	Inicialización y precarga de anuncios
Cómo ejecutar el juego
Una buena oportunidad para mostrar un anuncio... adBreak() →
	Hay un anuncio disponible y ahora es un buen momento para mostrarlo... ← beforeAd()
El juego se detiene, silencia el sonido y se prepara para mostrar el anuncio. return para la API →
	La API de Ad Placement renderiza el anuncio intersticial. El reproductor puede hacer clic en el anuncio (que se muestra en una pestaña nueva). Deben descartar el anuncio para poder seguir jugando.
	← Se llama a afterAd() si se mostró un anuncio
El juego reanuda el sonido y lo activa.
	← adBreakDone()Siempre se llama a adBreakDone() (incluso si no se mostró un anuncio).
El juego registra estadísticas sobre esta posición.

Notas

• adBreak() es una función asíncrona que se muestra de inmediato.
• Si no hay anuncios para mostrar para una posición, no se llama a ninguna de las devoluciones de llamada, es decir, ninguna beforeAd(), afterAd().
• A fin de asegurarte de que tu juego no se siga ejecutando mientras se muestra el anuncio, usa la devolución de llamada beforeAd() para silenciar el sonido y pausar el juego.
• beforeAd() es síncrono, por lo que la API de Ad Placement no mostrará un anuncio hasta que regrese.
• Reinicia el juego y activa el sonido cuando recibas la llamada afterAd().
• Si se proporciona, siempre se llama a adBreakDone(), incluso si un anuncio no se mostró en esta posición.
• Llamar a adBreak() mientras se muestra otro anuncio fallará y se mostrará una advertencia en la Consola de JavaScript.

Anuncios previos al video

Un anuncio previo al video es un anuncio intersticial que se muestra antes de que el juego cargue su IU. Es lo primero que ve un jugador cuando navega a tu juego. Debido a que un anuncio previo al video ocurre muy temprano en la carga de la página y tu juego aún no se muestra, no es necesario que realices las llamadas habituales para pausar y silenciar el juego. En su lugar, usa la devolución de llamada adBreakDone() para secuenciar el inicio de tu juego con el anuncio, es decir, renderizar la IU y comenzar a reproducir sonido. Solo se puede activar un anuncio previo al video por cada carga de página.

Secuencia de llamadas

La llamada para un anuncio previo al video se realiza al comienzo de la carga de la página. Como el juego no procesó su IU en este punto, no debes pasar las devoluciones de llamada beforeAd() y afterAd(). En su lugar, usa la devolución de llamada adBreakDone() para iniciar tu juego después de la posición, ya que se garantiza que se llamará incluso si no había ningún anuncio.

Si llamas al siguiente código, al comienzo de la lógica del juego, se colocará un anuncio previo al video. No se debe procesar la IU antes de llamar a este código.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

Anuncio previo al video: secuencia detallada de la llamada
Su juego H5	API de Ad Placement
	Comienza la inicialización de la API y el almacenamiento previo en caché de los anuncios
Se está ejecutando, pero no se inició y no mostró una IU
adBreak(type:'preroll',…) →
	La API de colocación de anuncios termina de inicializarse y cargarse anuncios. Si hay un anuncio, este se muestra. El reproductor puede hacer clic en el anuncio (que se muestra en una pestaña nueva). Deben descartarlo para que se inicie el juego.
	← Siempre se llama a adBreakDone() (incluso si no se mostró un anuncio).
La IU del juego se renderiza en la pantalla y el jugador ahora puede interactuar con ella. El juego puede usar el objeto placementInfo que se pasó a adBreakDone() según sea necesario (por ejemplo, para registrar estadísticas adicionales).

Notas

• Un anuncio previo al video siempre intentará precargar anuncios:
  • No se requiere la llamada a adConfig(preloadAds: ‘on') con anuncios previos al video.
• Al igual que otras colocaciones de anuncios, un anuncio previo al video puede mostrar un anuncio o no.
• No se deben pasar beforeAd() ni afterAd() a un anuncio previo al video.
  • Debido a que los anuncios previos al video se publican antes de que comience el juego, no es necesario pausar ni silenciar el sonido del juego.
  • Si pasas beforeAd() o afterAd() con un anuncio previo al video, la llamada fallará y se registrará un error en la Consola de JavaScript.
• Un anuncio previo al video espera automáticamente a que la API de Ad Placement se inicialice y cargue previamente los anuncios:
  • Sin embargo, hay un tiempo de espera (2) que evita que la llamada se retrase indefinidamente. Esto garantiza que se llame a adBreakDone() de manera oportuna y que se inicie el juego.
  • Siempre se llama a adBreakDone(), incluso si no hay anuncios.
• Te recomendamos que uses un anuncio previo al video para colocar anuncios antes de que comience el juego.
  • Como alternativa, puedes usar la devolución de llamada onReady() a adConfig() como un mecanismo para secuenciar la lógica del juego con la inicialización de la API y la carga previa de anuncios.

Anuncios recompensados

Un anuncio recompensado te permite recompensar a los jugadores con elementos integrados en la app si deciden ver un anuncio. Mientras que los anuncios intersticiales se inhabilitan, se muestra el anuncio a un jugador que puede descartarlo. Los anuncios recompensados son los que deben habilitar la función. El jugador elige si quiere mirar un anuncio y cuándo quiere recibir una recompensa.

A diferencia de los anuncios intersticiales, donde el reproductor puede descartar el anuncio en cualquier momento y para recibir una recompensa, debe ver el anuncio por un período mínimo (que puede variar según la creatividad del anuncio que se muestra).

Debido a que los anuncios recompensados son opcionales para el jugador, requieren una integración más profunda en tu flujo de juego. Debes proporcionar funciones para renderizar una solicitud de recompensa en el juego y asignar la recompensa al jugador si mira el anuncio.

Las recompensas no deben tener un valor fuera de la app, no tener (o intercambiarse con facilidad) un valor monetario y tampoco deben ser vendibles ni intercambiables por bienes y servicios. Tampoco debes alentar a los jugadores a hacer clic en los anuncios. Consulte el borrador de la política para anuncios intersticiales y recompensados a fin de obtener más detalles.

Debido a que las recompensas son opcionales para el jugador, puedes agregarlas en cualquier lugar que tenga sentido dentro de tu juego y usarlas junto con los anuncios intersticiales. Al igual que los anuncios intersticiales, estas posiciones son oportunidades para mostrar anuncios recompensados. La API de Ad Placement solo llamará a tu código si se ofrece un anuncio recompensado en un punto específico del juego.

Una vez más, el objetivo aquí es permitirte integrar tu juego con la API de Ad Placement una vez y luego, con el tiempo, mediante controles en la etiqueta o en AdSense, puedes cambiar la combinación precisa de anuncios que se activan, sin tener que volver a codificar y lanzar tu juego.

El tipo de posición de una recompensa siempre es 'reward' y se pueden usar todos los campos de esta configuración.

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
});

Las nuevas funciones clave son beforeReward(), que es el activador que indica que debes procesar el mensaje de recompensa, y adViewed(), que se llama cuando el jugador vio el anuncio de forma correcta para que puedas asignar su recompensa.

Puede definir una posición de recompensa de la siguiente manera:

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

Los anuncios recompensados comienzan con un mensaje en el juego que ofrece al jugador una recompensa si ve un anuncio.

Secuencia de llamadas para un anuncio recompensado

Descripción

Anuncio recompensado: secuencia de llamada detallada
Su juego H5	API de Ad Placement
	Inicialización y almacenamiento previo en caché de los anuncios
Cómo ejecutar el juego
adBreak(type:'reward', ... ) →
	Hay un anuncio disponible, así que comienza una posición de anuncio recompensado. beforeReward() se llama de forma síncrona, inmediatamente después de la llamada a adBreak(). ← beforeReward(showAdFn)
El juego procesa el mensaje de recompensa. Esto le brinda al jugador la oportunidad de obtener una recompensa por ver un anuncio. Se podría ofrecer más de un tipo de recompensa (por ejemplo, una nueva vida o una moneda de oro). El jugador puede hacer clic en un mensaje de recompensa, descartarlo o ignorarlo. Si hace clic en un mensaje, el juego almacena el tipo de recompensa que solicitó y llama a showAdFn().... De lo contrario, si se descarta o se ignora la solicitud de recompensa, no sucederá nada hasta que realice otra llamada a adBreak() con un tipo de posición de recompensa, momento en el que la API de Ad Placement se restablecerá y limpiará el estado de esta llamada. Si la app llama a showAdFn desde una pausa publicitaria anterior, no tendrá ningún efecto.
showAdFn() →
	← beforeAd()
El juego se pausa, silencia el sonido y se prepara para mostrar el anuncio return para la API →
	La API muestra el anuncio. Tiene un botón para descartar y una cuenta regresiva de cuánto tiempo queda en el anuncio.
Si el reproductor descarta el anuncio...
	← adDismissed()
El jugador descartó el anuncio y el juego no emite la recompensa.
O BIEN el reproductor mira el anuncio hasta que finaliza...
	← adViewed()
El jugador miró el anuncio hasta el final y el juego emite la recompensa. (Por lo general, esto se configura configurando un estado del juego que luego se retoma cuando se reinicia el juego con la llamada a afterAd() a continuación).
Después de ver o descartar el anuncio...
	← Se llama a afterAd() si se mostró un anuncio.
El juego reanuda el sonido y lo activa.
	← adBreakDone()Siempre se llama a adBreakDone() (incluso si no se mostró un anuncio).
El juego registra estadísticas sobre esta posición.

Notas

• adBreak() es una función asíncrona que se muestra de inmediato.
• Si no hay anuncios para mostrar para una posición, no se llama a ninguna de las devoluciones de llamada, es decir, no se llama a beforeAd() ni a beforeReward().
• A fin de asegurarte de que tu juego no se siga ejecutando mientras se muestra el anuncio, usa la devolución de llamada beforeAd() para silenciar el sonido y pausar el juego.
• beforeAd() es síncrono, por lo que la API de Ad Placement no mostrará un anuncio hasta que regrese.
• Reinicia el juego y activa el sonido cuando recibas la llamada afterAd().
• Si se proporciona, siempre se llama a adBreakDone(), incluso si un anuncio no se mostró en esta posición.
• Llamar a adBreak() mientras se muestra otro anuncio fallará y se mostrará una advertencia en la Consola de JavaScript.