Usa 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 colocar y configurar anuncios en tu juego. Los argumentos que se muestran arriba son los únicos argumentos válidos 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 posición del anuncio 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 declaraste
  • ¿Este anuncio se muestra al inicio del juego? ¿Entre niveles? ¿En un momento en el que el jugador pausó el juego?
• Indica si existe un anuncio adecuado para el reproductor actual
  • ¿Este anuncio es relevante para ellos?
  • ¿Es coherente con su configuración de privacidad y consentimiento de datos?
• La cantidad de anuncios que vio el reproductor recientemente
• La configuración de los controles (por ejemplo, la frecuencia de los anuncios) que configuraste para este juego
  • Como sugerencias en la etiqueta
  • En AdSense, ten 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 una llamada a adBreak() podría no mostrar ningún anuncio. Simplemente declara un lugar donde podría mostrarse un anuncio.

Esto es diferente de las APIs tradicionales, en las que tu código siempre sabe si hay un anuncio disponible y tú decides dentro del juego si mostrarlo. Este enfoque de permitir que la API de Ad Placement decida si se muestra un anuncio en una posición en particular es un patrón al que a veces se hace referencia como "inversión de control".

El motivo por el que estamos realizando la transición de nuestra API de juegos a este modelo es, en primer lugar, que acorta el código que debes escribir en tu juego. En segundo lugar, facilita la publicación de posiciones que cumplen con las políticas y ofrecen una excelente experiencia del usuario, lo que, a su vez, nos permitió publicar algunos de nuestros formatos con mejor rendimiento para los publicadores de juegos. Por último, separa de forma más clara 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. Para ello, inicialmente, especificaremos sugerencias en la etiqueta. Sin embargo, en versiones futuras, podremos proporcionar controles directamente en las interfaces de AdSense y AdMob.

Anuncios intersticiales

Un anuncio intersticial es un anuncio de pantalla completa que se puede mostrar en diferentes momentos dentro de tu juego, por ejemplo, cuando el jugador comienza el juego o después de que completa un nivel. Pausa el juego, cubre todo el documento y el jugador puede hacer clic en el anuncio (en cuyo caso, el anuncio se muestra en otra pestaña del navegador) o descartarlo para continuar con el juego.

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

Para colocar un anuncio intersticial, completa los siguientes campos dentro de la configuración de la 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 siempre nombres tus posiciones. Las otras devoluciones de llamada son opcionales.

Secuencia de llamadas

Revisa la secuencia de llamadas de un anuncio intersticial.

Descripción

Intersticial: Secuencia de llamadas detallada
Tu juego H5	Ad Placement API
	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 pausa, se silencia el sonido y se prepara para mostrar el anuncio. return a la API →
	La API de Ad Placement renderiza el anuncio intersticial. El jugador puede hacer clic en el anuncio (que se muestra en una pestaña nueva). Debe descartar el anuncio para seguir jugando.
	← afterAd() se llama si se mostró un anuncio
El juego se reanuda y se activa el sonido.
	← adBreakDone()adBreakDone() siempre se llama (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 ningún anuncio para mostrar en una posición, no se llama a ninguna de las devoluciones de llamada,es decir, no se llama a ninguna de beforeAd() ni afterAd().
• Para asegurarte de que el juego no siga ejecutándose 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 devuelva un valor.
• Reinicia el juego y reactiva el sonido cuando recibas la llamada de afterAd().
• Si se proporciona, siempre se llama a adBreakDone(), incluso si no se mostró un anuncio en esta posición.
• Si llamas a adBreak() mientras se muestra otro anuncio, se producirá un error 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. Dado que el anuncio previo al video ocurre muy al principio de la carga de la página y tu juego aún no se muestra, no se requieren las llamadas habituales para pausar y silenciar tu juego. En cambio, usas la devolución de llamada adBreakDone() para secuenciar el inicio del 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 muy temprano en la carga de la página. Como el juego no renderizó 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 el juego después de la posición, ya que se garantiza que se llamará incluso si no hubo un anuncio.

Si llamas al siguiente código al principio de la lógica del juego, se colocará un anuncio previo al video. Tu IU no debe renderizarse antes de que se llame 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 de llamadas detallada
Tu juego H5	Ad Placement API
	Se inicia la inicialización de la API y el almacenamiento previo en caché de los anuncios
Se está ejecutando, pero no se inició ni mostró una IU.
adBreak(type:'preroll',…) →
	La API de Ad Placement termina de inicializar y cargar anuncios. Si hay un anuncio, se muestra. El jugador puede hacer clic en el anuncio (que se muestra en una pestaña nueva). Debe descartarlo para que comience el juego.
	← adBreakDone() siempre se llama (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 pasa a adBreakDone() según sea necesario (por ejemplo, para registrar estadísticas adicionales).

Notas

• Un anuncio previo al video siempre intentará precargar anuncios:
  • No es necesario llamar a adConfig(preloadAds: ‘on') con los anuncios previos al video.
• Al igual que en otras posiciones de anuncios, es posible que en los anuncios previos al video se muestre o no un anuncio.
• beforeAd() y afterAd() no se deben pasar a un anuncio previo al video.
  • Dado 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 se inicialice la API de Ad Placement y se precarguen los anuncios:
  • Sin embargo, hay un tiempo de espera (2 s) que evita que la llamada se retrase de forma indefinida. 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 un anuncio.
• 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() para adConfig() como 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 tus jugadores con elementos integrados en la aplicación si eligen mirar un anuncio. Mientras que los intersticiales son opcionales, a los jugadores se les muestra el anuncio y pueden optar por descartarlo. Los anuncios recompensados son opcionales. El jugador elige si quiere mirar un anuncio y cuándo hacerlo para recibir una recompensa.

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

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

Las recompensas no deben tener valor fuera de tu app, no deben tener (ni poder intercambiarse fácilmente por) valor monetario, no deben ser vendibles ni intercambiables por bienes y servicios, y no debes alentar a los jugadores a hacer clic en los anuncios. Consulta el borrador de la política sobre anuncios intersticiales y recompensados para obtener más detalles.

Dado que las recompensas son opcionales para el jugador, puedes agregarlas en cualquier lugar que tenga sentido dentro del juego y usarlas además de los anuncios intersticiales. Al igual que los intersticiales, estas posiciones son oportunidades para mostrar anuncios recompensados. La API de Ad Placement solo llamará a tu código si realmente se ofrecerá un anuncio recompensado en un punto específico de tu 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, usar los controles de la etiqueta o de AdSense para cambiar la combinación precisa de anuncios que se activan, sin tener que volver a codificar y lanzar tu juego.

El tipo de una posición recompensada siempre es 'reward' y se pueden usar todos los campos de la configuración de la posició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 renderizar el mensaje de recompensa, y adViewed(), a la que se llama cuando el jugador visualizó el anuncio correctamente, para que puedas asignarle su recompensa.

Podrías definir una posición recompensada 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 tu juego que le ofrece al jugador una recompensa si mira un anuncio.

Secuencia de llamadas para un anuncio recompensado

Descripción

Anuncio recompensado: Secuencia de llamadas detallada
Tu juego H5	Ad Placement API
	Inicialización y almacenamiento previo en caché de anuncios
Cómo ejecutar el juego
adBreak(type:'reward', ... ) →
	Hay un anuncio disponible, por lo que se inicia la posición de anuncio recompensado. Se llama a beforeReward() de forma síncrona, inmediatamente después de la llamada a adBreak(). ← beforeReward(showAdFn)
El juego renderiza la instrucción de recompensa. Esto le ofrece al jugador la oportunidad de obtener una recompensa mirando un anuncio. Se puede ofrecer más de un tipo de recompensa (por ejemplo, una vida nueva o una moneda de oro). El jugador puede hacer clic en un mensaje de recompensa, descartarlo o simplemente ignorarlo. Si hace clic en una instrucción, el juego almacena el tipo de recompensa que solicitó y llama a showAdFn().... De lo contrario, si se descarta o ignora el mensaje de recompensa, no sucederá nada hasta que realices otra llamada a adBreak() con un tipo de posición de recompensa, momento en el que la API de Ad Placement 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, se silencia el sonido y se prepara para mostrar el anuncio. return a la API →
	La API muestra el anuncio. Tiene un botón para descartar y una cuenta regresiva del tiempo restante del anuncio.
SI el reproductor descarta el anuncio…
	← adDismissed()
El jugador descartó el anuncio y el juego no emitió la recompensa.
DE LO CONTRARIO, el reproductor mira el anuncio hasta el final…
	← adViewed()
El jugador miró el anuncio hasta el final y el juego emitió la recompensa. (Por lo general, esto se haría configurando algún estado del juego que luego se recupera cuando el juego se reinicia con la llamada a afterAd() que se muestra a continuación).
Después de que se mira o descarta el anuncio…
	← Se llama a afterAd() si se mostró un anuncio
El juego se reanuda y se activa el sonido.
	← adBreakDone()adBreakDone() siempre se llama (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 un anuncio para mostrar en una posición, no se llama a ninguna de las devoluciones de llamada, es decir, no se llama a ninguna de beforeAd() ni beforeReward().
• Para asegurarte de que el juego no siga ejecutándose 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 devuelva un valor.
• Reinicia el juego y reactiva el sonido cuando recibas la llamada de afterAd().
• Si se proporciona, siempre se llama a adBreakDone(), incluso si no se mostró un anuncio en esta posición.
• Si llamas a adBreak() mientras se muestra otro anuncio, se producirá un error y se mostrará una advertencia en la consola de JavaScript.