Implementera bild-i-bild-annonser (beta)

Bild-i-bild

Bild-i-bild-annonser (PiP) visas i ett flytande fönster som visas ovanpå innehållet på skärmen, till exempel artiklar, flöden eller spel. Det här formatet låter användare interagera med din app medan annonsen förblir synlig. Om du vill visa annonser som inte tar över hela skärmen väljer du det här formatet. Läs mer om bild-i-bild-annonser .

Den här guiden beskriver hur du begär och visar bild-i-bild-annonser i din app med GMA Next-Gen SDK .

Innan du börjar

Innan du fortsätter, gör följande:

Ladda en annons

För att ladda en PictureInPictureAd , skapa en annonsförfrågan och anropa load metoden:

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

Ersätt AD_UNIT_ID med ditt annonsenhets-ID.

Visa annonsen

För att visa bild-i-bild-annonsen på skärmen, konfigurera dina bild-i-bild-alternativ och anropa show metoden. Följande exempel anger annonsens standardposition och presentationens omfattning på skärmen:

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

Ställ in positionen

Som standard visar GMA Next-Gen SDK en bild-i-bild-annons i skärmens nedre högra hörn när den visas första gången, eller på den senast kända positionen om den tidigare visats. För att anpassa var annonsen visas, ange positionen i dina bild-i-bild-inställningar. Följande exempel anger positionen ovanpå innehållet i skärmens övre vänstra hörn:

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

För alla tillgängliga tjänster, se PictureInPictureAdPosition .

Ange presentationens omfattning

Som standard binder GMA Next-Gen SDK en bild-i-bild-annons till den aktuella värdskärmen. GMA Next-Gen SDK stänger annonsen när värdskärmens vyhierarki inte längre finns i minnet. För att hålla annonsen synlig efter att värdskärmen har tagits bort från minnet, ange presentationsomfånget till programmet:

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

För mer information, se Håll annonsen synlig på alla skärmar .

Ställ in återanropet för annonshändelsen

För att hantera händelser i bild-i-bild-annonser, ställ in händelseanropet på din annons innan den visas. Detta anrop rapporterar standardhändelser, såsom klick och visningar. Detta anrop rapporterar även bild-i-bild-specifika händelser, såsom när annonsen visas eller döljs:

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

Dölj annonsen

För att ta bort den flytande annonsen från skärmen, anropa metoden hide . Den här metoden anropar händelseanropet ad hidden:

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

Rensa upp annonsresurser

För att undvika minnesläckor, ta bort din referens till annonsobjektet när din app är klar med att använda annonsen. Till exempel när din app inte längre visar eller interagerar med annonsen igen. För skärmomfattande annonser, ta bort referensen när din app tar bort värdskärmen från minnet. För appomfattande annonser, behåll annonsreferensen medan användaren navigerar mellan skärmar och ta bort referensen när användaren stänger annonsen:

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

Håll annonsen synlig på alla skärmar

När du ställer in presentationsområdet för appen förblir bild-i-bild-annonsen synlig även när appen tar bort värdskärmen från minnet. För att interagera med eller stänga annonsen när användaren navigerar bort från värdskärmen måste appen behålla åtkomst till bild-i-bild-annonsen. Vi rekommenderar att du lagrar annonsen i en singleton på appnivå eller en delad tillståndshanterare snarare än i en enskild skärms instansvariabel.

För ett exempel på hur du kan se en annons på olika skärmar, se våra exempelappar: