Kép a képben hirdetések megvalósítása (béta)

Kép a képben

A kép a képben (PiP) hirdetések egy lebegő ablakban jelennek meg, amely a képernyőn megjelenő tartalom, például cikkek, hírfolyamok vagy játékmenet felett marad. Ez a formátum lehetővé teszi a felhasználók számára, hogy interakcióba lépjenek az alkalmazással, miközben a hirdetés látható marad. Ha olyan hirdetéseket szeretne megjeleníteni, amelyek nem foglalják el a teljes képernyőt, válassza ezt a formátumot. Tudjon meg többet a kép a képben hirdetésekről .

Ez az útmutató a kép a képben hirdetések alkalmazásban történő kérését és megjelenítését ismerteti GMA Next-Gen SDK használatával.

Mielőtt elkezdené

Mielőtt folytatná, tegye a következőket:

Hirdetés betöltése

Egy PictureInPictureAd betöltéséhez hozz létre egy hirdetési kérelmet, és hívd meg a load metódust:

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

Jáva 

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

Cserélje le AD_UNIT_ID részt a hirdetési egység azonosítójára.

Hirdetés megjelenítése

A kép a képben hirdetés képernyőn való megjelenítéséhez konfigurálja a kép a képben beállításokat, és hívja meg a show metódust. A következő példa beállítja a hirdetés alapértelmezett pozícióját és a megjelenítési hatókört a képernyőn:

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

Jáva 

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

Állítsa be a pozíciót

Alapértelmezés szerint GMA Next-Gen SDK egy kép a képben hirdetést jelenít meg a képernyő jobb alsó sarkában, amikor először megjelenik, vagy az utolsó ismert pozícióban, ha korábban megjelent. A hirdetés megjelenési helyének testreszabásához állítsa be a pozíciót a kép a képben beállításokban. A következő példa a tartalom tetején, a képernyő bal felső sarkában állítja be a pozíciót:

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

Jáva 

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

Az összes elérhető pozícióért lásd: PictureInPictureAdPosition .

A prezentáció hatókörének beállítása

Alapértelmezés szerint GMA Next-Gen SDK egy kép a képben hirdetést köt az aktuális gazdaképernyőhöz. GMA Next-Gen SDK elveti a hirdetést, ha a gazdaképernyő nézethierarchiája már nincs a memóriában. Ha azt szeretné, hogy a hirdetés látható maradjon a gazdaképernyő memóriából való eltávolítása után, állítsa be a megjelenítési hatókört az alkalmazásra:

Kotlin 

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

Jáva 

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

További információkért lásd: A hirdetés láthatóságának megőrzése több képernyőn is .

Hirdetési esemény visszahívásának beállítása

A kép a képben hirdetések életciklus-eseményeinek kezeléséhez állítsa be az eseményvisszahívást a hirdetésen a megjelenítés előtt. Ez a visszahívás a szokásos eseményeket, például a kattintásokat és a megjelenítéseket jelenti. Ez a visszahívás a kép a képben-specifikus eseményeket is jelenti, például amikor a hirdetés megjelenik vagy elrejtődik:

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

Jáva 

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

Hirdetés elrejtése

A lebegő hirdetés eltávolításához a képernyőről hívjuk meg a hide metódust. Ez a metódus meghívja az ad hidden esemény visszahívását:

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

Jáva 

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

Hirdetési erőforrások tisztítása

A memóriavesztés elkerülése érdekében távolítsa el a hirdetési objektumra mutató hivatkozást, amikor az alkalmazás befejezi a hirdetés használatát. Például, amikor az alkalmazás már nem jeleníti meg a hirdetést, vagy nem lép kapcsolatba vele. Képernyő-hatókörű hirdetések esetén távolítsa el a hivatkozást, amikor az alkalmazás eltávolítja a gazdaképernyőt a memóriából. Alkalmazás-hatókörű hirdetések esetén őrizze meg a hirdetésreferenciát, amíg a felhasználó a képernyők között navigál, és távolítsa el a hivatkozást, amikor a felhasználó bezárja a hirdetést:

Kotlin 

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

Jáva 

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

Tartsa a hirdetést láthatóan minden képernyőn

Amikor a megjelenítési hatókört az alkalmazásra állítja be, a kép a képben hirdetés látható marad akkor is, ha az alkalmazás eltávolítja a tárhelyképernyőt a memóriából. Ahhoz, hogy a hirdetéssel interakcióba léphessen vagy azt el tudjon vetni, amikor a felhasználó elnavigál a tárhelyképernyőről, az alkalmazásnak meg kell őriznie a hozzáférést a kép a képben hirdetéshez. Javasoljuk, hogy a hirdetést egy alkalmazásszintű egyoldalas vagy megosztott állapotkezelőben tárolja, ne pedig egyetlen képernyő példányváltozójában.

Ha például azt szeretné, hogyan lehet egy hirdetést több képernyőn is láthatóvá tenni, tekintse meg mintaalkalmazásainkat: