Впровадження реклами «картинка в картинці» (бета-версія)

Картинка в картинці

Реклама «картинка в картинці» (PiP) відображається у плаваючому вікні, яке залишається поверх контенту на екрані, такого як статті, стрічки чи ігровий процес. Цей формат дозволяє користувачам взаємодіяти з вашим додатком, поки реклама залишається видимою. Щоб показувати рекламу, яка не займає весь екран, виберіть цей формат. Дізнайтеся більше про рекламу «картинка в картинці» .

У цьому посібнику розглядається запит і показ реклами «картинка в картинці» у вашому додатку за допомогою GMA Next-Gen SDK .

Перш ніж почати

Перш ніж продовжити, виконайте такі дії:

Завантажити оголошення

Щоб завантажити PictureInPictureAd , створіть запит оголошення та викличте метод load :

Котлін 

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

Ява 

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

Замініть AD_UNIT_ID на ідентифікатор вашого рекламного блоку.

Показати оголошення

Щоб відобразити рекламу «картинка в картинці» на екрані, налаштуйте параметри «картинка в картинці» та викличте метод show . У наступному прикладі встановлюється позиція реклами за замовчуванням та область відображення на екрані:

Котлін 

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.")
  }
}

Ява 

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

Встановіть позицію

За замовчуванням GMA Next-Gen SDK відображає рекламу «картинка в картинці» в правому нижньому куті екрана під час першого показу або в останній відомій позиції, якщо вона відображалася раніше. Щоб налаштувати місце показу реклами, встановіть позицію в налаштуваннях режиму «картинка в картинці». У наступному прикладі встановлюється позиція поверх контенту у верхньому лівому куті екрана:

Котлін 

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

Ява 

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

Щоб переглянути всі доступні позиції, див. PictureInPictureAdPosition .

Встановіть обсяг презентації

За замовчуванням GMA Next-Gen SDK прив’язує рекламу «картинка в картинці» до поточного екрана хоста. GMA Next-Gen SDK закриває рекламу, коли ієрархія переглядів екрана хоста більше не зберігається в пам’яті. Щоб реклама залишалася видимою після видалення екрана хоста з пам’яті, встановіть область видимості презентації на додаток:

Котлін 

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

Ява 

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

Щоб отримати додаткові відомості, див. розділ «Забезпечення видимості оголошення на всіх екранах» .

Налаштувати зворотний виклик події реклами

Щоб обробляти події життєвого циклу реклами «картинка в картинці», налаштуйте зворотний виклик події на свою рекламу перед її показом. Цей зворотний виклик повідомляє про стандартні події, такі як кліки та покази. Цей зворотний виклик також повідомляє про події, специфічні для «картинки в картинці», наприклад, коли реклама відображається або приховується:

Котлін 

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

Ява 

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

Приховати оголошення

Щоб видалити плаваючу рекламу з екрана, викличте метод hide . Цей метод викликає зворотний виклик події ad hidden:

Котлін 

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.")
  }
}

Ява 

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

Очищення рекламних ресурсів

Щоб уникнути витоків пам’яті, видаліть посилання на об’єкт реклами, коли ваш додаток завершить використання реклами. Наприклад, коли ваш додаток більше не відображає рекламу або не взаємодіє з нею. Для реклами, обмеженої обсягом екрана, видаліть посилання, коли ваш додаток видаляє головний екран з пам’яті. Для реклами, обмеженої обсягом програми, збережіть посилання на рекламу, поки користувач переміщується між екранами, і видаліть посилання, коли користувач закриває рекламу:

Котлін 

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

Ява 

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

Забезпечте видимість реклами на всіх екранах

Коли ви встановлюєте область видимості презентації для програми, реклама «картинка в картинці» залишається видимою, навіть коли ваша програма видаляє екран хоста з пам’яті. Щоб взаємодіяти з рекламою або закривати її, коли користувач залишає екран хоста, ваша програма повинна зберігати доступ до реклами «картинка в картинці». Ми рекомендуємо зберігати рекламу в одиночному об’єкті програми або в менеджері спільного стану, а не в змінній екземпляра окремого екрана.

Щоб переглянути приклад того, як забезпечити видимість реклами на всіх екранах, перегляньте наші зразки програм: