Implementacija oglasov slika v sliki (beta)

Slika v sliki

Oglasi slika v sliki (PiP) se prikazujejo v plavajočem oknu, ki ostane nad vsebino na zaslonu, kot so članki, viri ali igranje. Ta oblika omogoča uporabnikom interakcijo z vašo aplikacijo, medtem ko oglas ostane viden. Če želite prikazovati oglase, ki ne zavzamejo celotnega zaslona, ​​izberite to obliko. Več o oglasih slika v sliki .

Ta vodnik obravnava zahtevanje in prikazovanje oglasov slika v sliki v vaši aplikaciji z uporabo GMA Next-Gen SDK .

Preden začnete

Preden nadaljujete, naredite naslednje:

Naloži oglas

Če želite naložiti oglas PictureInPictureAd , ustvarite zahtevo za oglas in pokličite metodo 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);
        }
      });
}

Zamenjajte AD_UNIT_ID z ID-jem oglasne enote.

Prikaži oglas

Če želite oglas slika v sliki prikazati na zaslonu, konfigurirajte možnosti slike v sliki in pokličite metodo show . Naslednji primer nastavi privzeti položaj oglasa in obseg predstavitve na zaslon:

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

Nastavite položaj

GMA Next-Gen SDK privzeto prikaže oglas »slika v sliki« v spodnjem desnem kotu zaslona, ​​ko je prvič prikazan, ali na zadnjem znanem mestu, če je bil prikazan prej. Če želite prilagoditi, kje se oglas prikaže, nastavite položaj v možnostih slike v sliki. Naslednji primer nastavi položaj na vrhu vsebine v zgornjem levem kotu zaslona:

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

Za vse razpoložljive položaje glejte PictureInPictureAdPosition .

Nastavitev obsega predstavitve

GMA Next-Gen SDK privzeto veže oglas »slika v sliki« na trenutni zaslon gostitelja. GMA Next-Gen SDK zavrže oglas, ko hierarhija pogledov zaslona gostitelja ni več v pomnilniku. Če želite, da oglas ostane viden tudi po odstranitvi zaslona gostitelja iz pomnilnika, nastavite obseg predstavitve na aplikacijo:

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

Za več informacij glejte razdelek Ohranite vidnost oglasa na vseh zaslonih .

Nastavite povratni klic oglasnega dogodka

Za obravnavo dogodkov življenjskega cikla oglasa »slika v sliki« nastavite povratni klic dogodka na oglas, preden ga prikažete. Ta povratni klic poroča o standardnih dogodkih, kot so kliki in prikazi. Ta povratni klic poroča tudi o dogodkih, specifičnih za sliko v sliki, na primer kdaj je oglas prikazan ali skrit:

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

Skrij oglas

Če želite odstraniti plavajoči oglas z zaslona, ​​pokličite metodo hide . Ta metoda sproži povratni klic dogodka 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.");
  }
}

Čiščenje oglasnih virov

Da bi se izognili uhajanju pomnilnika, spustite sklic na oglasni objekt, ko vaša aplikacija preneha uporabljati oglas. Na primer, ko vaša aplikacija ne prikazuje več oglasa ali z njim ne komunicira več. Pri oglasih, ki so omejeni na zaslon, sklic spustite, ko aplikacija odstrani gostiteljski zaslon iz pomnilnika. Pri oglasih, ki so omejeni na aplikacijo, ohranite sklic na oglas, medtem ko uporabnik krmari med zasloni, in sklic spustite, ko uporabnik zapre oglas:

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

Ohranite vidnost oglasa na vseh zaslonih

Ko nastavite obseg predstavitve na aplikacijo, oglas »slika v sliki« ostane viden, tudi če aplikacija odstrani gostiteljski zaslon iz pomnilnika. Če želite, da lahko uporabnik komunicira z oglasom ali ga zapre, ko zapusti gostiteljski zaslon, mora vaša aplikacija ohraniti dostop do oglasa »slika v sliki«. Priporočamo, da oglas shranite v upravitelju posameznega zaslona na ravni aplikacije ali v upravitelju skupnega stanja in ne v spremenljivki primerka posameznega zaslona.

Za primer, kako ohraniti oglas viden na vseh zaslonih, si oglejte naše vzorčne aplikacije: