Ota käyttöön kuva kuvassa -mainokset (beta)

Kuva kuvassa

Kuva kuvassa (PiP) -mainokset näkyvät kelluvassa ikkunassa, joka pysyy näytön sisällön, kuten artikkelien, syötteiden tai pelin, päällä. Tässä muodossa käyttäjät voivat olla vuorovaikutuksessa sovelluksesi kanssa mainoksen pysyessä näkyvissä. Jos haluat näyttää mainoksia, jotka eivät peitä koko näyttöä, valitse tämä muoto. Lue lisää kuva kuvassa -mainoksista .

Tämä opas käsittelee kuva kuvassa -mainosten pyytämistä ja näyttämistä sovelluksessasi GMA Next-Gen SDK avulla.

Ennen kuin aloitat

Ennen kuin jatkat, tee seuraavat toimet:

Lataa mainos

Lataa PictureInPictureAd luomalla mainospyyntö ja kutsumalla load metodia:

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

Korvaa AD_UNIT_ID mainosyksikkösi tunnuksella.

Näytä mainos

Jos haluat näyttää kuva kuvassa -mainoksen näytöllä, määritä kuva kuvassa -asetukset ja kutsu show metodia. Seuraava esimerkki asettaa mainoksen oletussijainnin ja esitysalueen näytöllä:

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

Aseta sijainti

Oletusarvoisesti GMA Next-Gen SDK näyttää kuva kuvassa -mainoksen näytön oikeassa alakulmassa ensimmäisen näyttökerran yhteydessä tai viimeisimmässä tunnetussa sijainnissa, jos mainosta on aiemmin näytetty. Voit mukauttaa mainoksen sijaintia määrittämällä sijainnin kuva kuvassa -asetuksissa. Seuraavassa esimerkissä mainos asetetaan sisällön päälle näytön vasempaan yläkulmaan:

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

Kaikki käytettävissä olevat sijainnit löytyvät kohdasta PictureInPictureAdPosition .

Esityksen laajuuden asettaminen

Oletusarvoisesti GMA Next-Gen SDK sitoo kuva kuvassa -mainoksen nykyiseen isäntänäyttöön. GMA Next-Gen SDK hylkää mainoksen, kun isäntänäytön näkymähierarkia ei ole enää muistissa. Jos haluat mainoksen pysyvän näkyvissä isäntänäytön poistamisen jälkeen muistista, aseta esityslaajuudeksi sovellus:

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

Lisätietoja on kohdassa Mainoksen näkyvyyden säilyttäminen eri näytöillä .

Aseta mainostapahtuman takaisinkutsu

Jotta voit käsitellä kuva kuvassa -mainoksen elinkaaritapahtumia, aseta tapahtumakutsun mainoksellesi ennen sen näyttämistä. Tämä kutsu raportoi vakiotapahtumat, kuten klikkaukset ja näyttökerrat. Tämä kutsu raportoi myös kuva kuvassa -kohtaisia ​​tapahtumia, kuten mainoksen näyttämisen tai piilottamisen:

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

Piilota mainos

Poistaaksesi kelluvan mainoksen näytöltä, kutsu hide metodia. Tämä metodi käynnistää mainoksen piilottaminen -tapahtuman takaisinkutsutoiminnon:

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

Mainosresurssien siivoaminen

Muistivuotoja voi välttää poistamalla viittauksen mainosobjektiin, kun sovelluksesi lopettaa mainoksen käytön. Esimerkiksi silloin, kun sovelluksesi ei enää näytä mainosta tai ole vuorovaikutuksessa sen kanssa. Näyttölaajuisten mainosten osalta poista viittaus, kun sovelluksesi poistaa isäntänäytön muistista. Sovelluslaajuisten mainosten osalta säilytä mainosviittaus käyttäjän navigoidessa näyttöjen välillä ja poista viittaus, kun käyttäjä sulkee mainoksen:

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

Pidä mainos näkyvissä eri näytöillä

Kun asetat esitysalueen sovellukselle, kuva kuvassa -mainos pysyy näkyvissä, vaikka sovelluksesi poistaisi isäntänäytön muistista. Jotta voit olla vuorovaikutuksessa mainoksen kanssa tai sulkea sen, kun käyttäjä siirtyy pois isäntänäytöltä, sovelluksesi on säilytettävä pääsy kuva kuvassa -mainokseen. Suosittelemme, että mainos säilytetään sovellustason yksittäisessä tai jaetussa tilahallinnassa yksittäisen näytön instanssimuuttujassa.

Esimerkki mainoksen näkyvyyden säilyttämisestä eri näytöillä on esimerkkisovelluksissamme: