Implementar anuncios de imagen en imagen (beta)

Imagen en imagen

Los anuncios de imagen en imagen se muestran en una ventana flotante que se mantiene en la parte superior del contenido de la pantalla, como artículos, feeds o partidas. Este formato permite a los usuarios interactuar con tu aplicación mientras el anuncio sigue visible. Elige este formato si quieres mostrar anuncios que no ocupen toda la pantalla. Más información sobre los anuncios de imagen en imagen

En esta guía se explica cómo solicitar y mostrar anuncios de imagen en imagen en tu aplicación con GMA Next-Gen SDK.

Antes de empezar

Antes de continuar, haz lo siguiente:

Cargar anuncios

Para cargar un PictureInPictureAd, crea una solicitud de anuncio y llama al método load:

Kotlin

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

  PictureInPictureAd.load(
    request,
    object : AdLoadCallback<PictureInPictureAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Picture-in-Picture ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

Java

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

  PictureInPictureAd.load(
      request,
      new AdLoadCallback<PictureInPictureAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Picture-in-Picture ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

Sustituye AD_UNIT_ID por el ID de tu bloque de anuncios.

Mostrar anuncios

Para mostrar el anuncio de imagen en imagen en la pantalla, configura las opciones de imagen en imagen y llama al método show. En el siguiente ejemplo se define la posición predeterminada del anuncio y el ámbito de presentación en la pantalla:

Kotlin

private fun showPictureInPictureAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    val options =
      PictureInPictureAdOptions.Builder()
        // Uses the Google Mobile Ads SDK's default screen position.
        .setPosition(PictureInPictureAdPosition.DEFAULT)
        // Binds the ad lifecycle to the host screen.
        .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

Java

private void showPictureInPictureAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    PictureInPictureAdOptions options =
        new PictureInPictureAdOptions.Builder()
            // Uses the Google Mobile Ads SDK's default screen position.
            .setPosition(PictureInPictureAdPosition.DEFAULT)
            // Binds the ad lifecycle to the host screen.
            .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
            .build();
    pipAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

Definir la posición

De forma predeterminada, GMA Next-Gen SDK muestra un anuncio de imagen en imagen en la esquina inferior derecha de la pantalla cuando se muestra por primera vez, o en la última posición conocida si se ha mostrado anteriormente. Para personalizar dónde aparece el anuncio, define la posición en las opciones de imagen en imagen. En el siguiente ejemplo se define la posición en la parte superior del contenido, en la esquina superior izquierda de la pantalla:

Kotlin

private fun createTopLeftPositionOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Sets the ad position to the top-left corner of the screen.
    .setPosition(PictureInPictureAdPosition.TOP_LEFT)
    .build()
}

Java

private PictureInPictureAdOptions createTopLeftPositionOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Sets the ad position to the top-left corner of the screen.
      .setPosition(PictureInPictureAdPosition.TOP_LEFT)
      .build();
}

Para ver todos los puestos disponibles, consulta PictureInPictureAdPosition.

Definir el ámbito de la presentación

De forma predeterminada, GMA Next-Gen SDK vincula un anuncio de imagen en imagen a la pantalla del host actual. GMA Next-Gen SDK cierra el anuncio cuando la jerarquía de vistas de la pantalla del host ya no está en la memoria. Para que el anuncio siga visible después de que se quite la pantalla del host de la memoria, define el ámbito de presentación en la aplicación:

Kotlin

private fun createApplicationScopedOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Keeps the ad visible beyond the host screen's lifecycle.
    .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
    .build()
}

Java

private PictureInPictureAdOptions createApplicationScopedOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Keeps the ad visible beyond the host screen's lifecycle.
      .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
      .build();
}

Para obtener más información, consulta Mantener el anuncio visible en todas las pantallas.

Definir la retrollamada de eventos de anuncios

Para gestionar los eventos del ciclo de vida de los anuncios de imagen en imagen, define la retrollamada de eventos en tu anuncio antes de mostrarlo. Esta retrollamada registra eventos estándar, como clics e impresiones. Esta retrollamada también informa de eventos específicos de Imagen en imagen, como cuándo se muestra o se oculta el anuncio:

Kotlin

private fun setAdEventCallback(pipAd: PictureInPictureAd) {
  pipAd.adEventCallback =
    object : PictureInPictureAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Picture-in-Picture ad shown.")
      }

      override fun onAdHidden() {
        Log.d(TAG, "Picture-in-Picture ad hidden.")
      }

      override fun onAdImpression() {
        Log.d(TAG, "Picture-in-Picture ad recorded an impression.")
      }

      override fun onAdClicked() {
        Log.d(TAG, "Picture-in-Picture ad recorded a click.")
      }

      override fun onAdShowedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        Log.w(
          TAG,
          "Picture-in-Picture ad failed to show full screen content: $fullScreenContentError",
        )
      }

      override fun onAdPaid(value: AdValue) {
        Log.d(TAG, "Picture-in-Picture ad paid: ${value.valueMicros} ${value.currencyCode}")
      }
    }
}

Java

private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) {
  pipAd.setAdEventCallback(
      new PictureInPictureAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Picture-in-Picture ad shown.");
        }

        @Override
        public void onAdHidden() {
          Log.d(TAG, "Picture-in-Picture ad hidden.");
        }

        @Override
        public void onAdImpression() {
          Log.d(TAG, "Picture-in-Picture ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          Log.d(TAG, "Picture-in-Picture ad recorded a click.");
        }

        @Override
        public void onAdShowedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.w(
              TAG,
              "Picture-in-Picture ad failed to show full screen content: "
                  + fullScreenContentError);
        }

        @Override
        public void onAdPaid(@NonNull AdValue value) {
          Log.d(
              TAG,
              "Picture-in-Picture ad paid: "
                  + value.getValueMicros()
                  + " "
                  + value.getCurrencyCode());
        }
      });
}

Ocultar el anuncio

Para quitar el anuncio flotante de la pantalla, llama al método hide. Este método invoca la retrollamada del evento de anuncio oculto:

Kotlin

private fun hidePictureInPictureAd() {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    ad.hide()
  } else {
    Log.d(TAG, "No ad to hide.")
  }
}

Java

private void hidePictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.hide();
  } else {
    Log.d(TAG, "No ad to hide.");
  }
}

Limpiar los recursos publicitarios

Para evitar fugas de memoria, elimina la referencia al objeto de anuncio cuando tu aplicación termine de usarlo. Por ejemplo, cuando tu aplicación ya no muestra el anuncio o no vuelve a interactuar con él. En el caso de los anuncios con ámbito de pantalla, elimina la referencia cuando tu aplicación quite la pantalla host de la memoria. En el caso de los anuncios específicos de la aplicación, conserva la referencia del anuncio mientras el usuario se desplaza por las pantallas y elimina la referencia cuando el usuario cierre el anuncio:

Kotlin

private fun cleanUpPictureInPictureAd() {
  pipAd?.destroy()
  pipAd = null
}

Java

private void cleanUpPictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.destroy();
    pipAd = null;
  }
}

Mantener el anuncio visible en todas las pantallas

Si defines el ámbito de la presentación en la aplicación, el anuncio de imagen en imagen seguirá visible aunque tu aplicación elimine la pantalla de alojamiento de la memoria. Para interactuar con el anuncio o cerrarlo cuando el usuario abandone la pantalla principal, tu aplicación debe conservar el acceso al anuncio de imagen en imagen. Te recomendamos que mantengas el anuncio en un singleton a nivel de aplicación o en un gestor de estado compartido en lugar de en la variable de instancia de una sola pantalla.

Para ver un ejemplo de cómo mantener un anuncio visible en todas las pantallas, consulta nuestras aplicaciones de ejemplo: