Implementați reclame imagine în imagine (beta)

Imagine în imagine

Reclamele de tip imagine în imagine (PiP) se afișează într-o fereastră flotantă care rămâne deasupra conținutului de pe ecran, cum ar fi articole, fluxuri sau jocuri. Acest format permite utilizatorilor să interacționeze cu aplicația dvs. în timp ce reclama rămâne vizibilă. Pentru a afișa reclame care nu ocupă întregul ecran, alegeți acest format. Aflați mai multe despre reclamele de tip imagine în imagine .

This guide covers requesting and displaying picture-in-picture ads in your app using GMA Next-Gen SDK .

Înainte de a începe

Înainte de a continua, faceți următoarele:

Încărcați un anunț

To load a PictureInPictureAd , create an ad request and call the load method:

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

Înlocuiți AD_UNIT_ID cu ID-ul unității de anunțuri.

Afișați anunțul

Pentru a afișa reclama imagine în imagine pe ecran, configurați opțiunile de imagine în imagine și apelați metoda show . Următorul exemplu setează poziția implicită a reclamei și domeniul de prezentare pe ecran:

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

Setați poziția

În mod implicit, GMA Next-Gen SDK afișează o reclamă imagine în imagine în colțul din dreapta jos al ecranului atunci când este afișată pentru prima dată sau în ultima poziție cunoscută, dacă a fost afișată anterior. Pentru a personaliza locul în care apare reclama, setați poziția în opțiunile de imagine în imagine. Următorul exemplu setează poziția deasupra conținutului, în colțul din stânga sus al ecranului:

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 all available positions, see PictureInPictureAdPosition .

Setați domeniul de aplicare al prezentării

În mod implicit, GMA Next-Gen SDK leagă o reclamă imagine în imagine de ecranul gazdă curent. GMA Next-Gen SDK închide reclama atunci când ierarhia de vizualizare a ecranului gazdă nu mai este în memorie. Pentru a păstra reclama vizibilă după ce ecranul gazdă este eliminat din memorie, setați domeniul de aplicare al prezentării la aplicație:

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

For more information, see Keep the ad visible across screens .

Setați apelul invers pentru evenimentul anunțului

Pentru a gestiona evenimentele din ciclul de viață al anunțurilor imagine în imagine, setați apelul de reapel al evenimentului în anunț înainte de afișarea acestuia. Acest apel de reapel raportează evenimente standard, cum ar fi clicuri și afișări. Acest apel de reapel raportează, de asemenea, evenimente specifice imaginii în imagine, cum ar fi momentul în care anunțul este afișat sau ascuns:

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

Ascunde anunțul

To remove the floating ad from the screen, call the hide method. This method invokes the ad hidden event callback:

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

Curățați resursele publicitare

Pentru a evita pierderile de memorie, eliminați referința la obiectul anunțului atunci când aplicația termină de utilizat anunțul. De exemplu, atunci când aplicația nu mai afișează sau nu mai interacționează cu anunțul. Pentru anunțurile la nivel de ecran, eliminați referința atunci când aplicația elimină ecranul gazdă din memorie. Pentru anunțurile la nivel de aplicație, păstrați referința anunțului în timp ce utilizatorul navighează pe ecrane și eliminați referința atunci când utilizatorul închide anunțul:

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

Mențineți anunțul vizibil pe toate ecranele

Când setați domeniul de aplicare al prezentării pentru aplicație, reclama imagine în imagine rămâne vizibilă chiar și atunci când aplicația elimină ecranul gazdă din memorie. Pentru a interacționa cu reclama sau a o închide atunci când utilizatorul părăsește ecranul gazdă, aplicația trebuie să păstreze accesul la reclama imagine în imagine. Vă recomandăm să păstrați reclama într-un singleton la nivel de aplicație sau într-un manager de stare partajat, mai degrabă decât într-o variabilă de instanță a unui singur ecran.

For an example of how to keep an ad visible across screens, see our sample apps: