Implementer billede-i-billede-annoncer (beta)

Billede-i-billede

Billede-i-billede-annoncer (PiP) vises i et flydende vindue, der forbliver oven på indhold på skærmen, f.eks. artikler, feeds eller gameplay. Dette format giver brugerne mulighed for at interagere med din app, mens annoncen forbliver synlig. For at vise annoncer, der ikke optager hele skærmen, skal du vælge dette format. Få mere at vide om billede-i-billede-annoncer .

Denne vejledning dækker anmodning om og visning af billede-i-billede-annoncer i din app ved hjælp af GMA Next-Gen SDK .

Før du begynder

Før du fortsætter, skal du gøre følgende:

Indlæs en annonce

For at indlæse en PictureInPictureAd skal du oprette en annonceanmodning og kalde 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);
        }
      });
}

Erstat AD_UNIT_ID med dit annonceenheds-ID.

Vis annoncen

For at vise billede-i-billede-annoncen på skærmen skal du konfigurere dine billede-i-billede-indstillinger og kalde show metoden. Følgende eksempel angiver standardpositionen for annoncen og præsentationsomfanget 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.");
  }
}

Indstil positionen

Som standard viser GMA Next-Gen SDK en billede-i-billede-annonce i nederste højre hjørne af skærmen, når den vises første gang, eller på den sidst kendte position, hvis den tidligere er blevet vist. For at tilpasse, hvor annoncen vises, skal du angive positionen i dine billede-i-billede-indstillinger. Følgende eksempel angiver positionen oven på indholdet i øverste venstre hjørne af skærmen:

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

For alle ledige stillinger, se PictureInPictureAdPosition .

Angiv præsentationens omfang

Som standard binder GMA Next-Gen SDK en billede-i-billede-annonce til den aktuelle værtskærm. GMA Next-Gen SDK lukker annoncen, når værtskærmens visningshierarki ikke længere er i hukommelsen. For at holde annoncen synlig, efter at værtskærmen er fjernet fra hukommelsen, skal du indstille præsentationsomfanget til applikationen:

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

Du kan finde flere oplysninger i afsnittet "Gør annoncen synlig på tværs af skærme" .

Indstil tilbagekaldet for annoncehændelsen

For at håndtere livscyklushændelser for billede-i-billede-annoncer skal du indstille hændelseskaldet på din annonce, før den vises. Dette tilbagekald rapporterer standardhændelser, såsom klik og visninger. Dette tilbagekald rapporterer også billede-i-billede-specifikke hændelser, såsom hvornår annoncen vises eller skjules:

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

Skjul annoncen

For at fjerne den flydende annonce fra skærmen skal du kalde hide metoden. Denne metode kalder ad hidden-hændelseskaldet tilbage:

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

Ryd op i annonceressourcer

For at undgå hukommelseslækager skal du slette din reference til annonceobjektet, når din app er færdig med at bruge annoncen. For eksempel når din app ikke længere viser eller interagerer med annoncen igen. For skærmbaserede annoncer skal du slette referencen, når din app fjerner værtsskærmen fra hukommelsen. For appbaserede annoncer skal du beholde annoncereferencen, mens brugeren navigerer på tværs af skærme, og slette referencen, når brugeren lukker annoncen:

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

Hold annoncen synlig på tværs af skærme

Når du indstiller præsentationsomfanget for applikationen, forbliver billede-i-billede-annoncen synlig, selvom din app fjerner værtsskærmen fra hukommelsen. For at interagere med eller lukke annoncen, når brugeren navigerer væk fra værtsskærmen, skal din app bevare adgangen til billede-i-billede-annoncen. Vi anbefaler at gemme annoncen i en singleton på appniveau eller en delt tilstandsadministrator i stedet for i en enkelt skærms instansvariabel.

For et eksempel på, hvordan du holder en annonce synlig på tværs af skærme, se vores eksempelapps: