Ieviest attēla attēlā reklāmas (beta versija)

Attēls attēlā

Attēla attēlā (PiP) reklāmas tiek rādītas peldošā logā, kas paliek virs ekrānā redzamā satura, piemēram, rakstiem, plūsmām vai spēlēm. Šis formāts ļauj lietotājiem mijiedarboties ar jūsu lietotni, kamēr reklāma paliek redzama. Lai rādītu reklāmas, kas neaizņem visu ekrānu, izvēlieties šo formātu. Uzziniet vairāk par attēla attēlā reklāmām .

Šajā rokasgrāmatā ir aprakstīta attēla attēlā reklāmu pieprasīšana un rādīšana lietotnē, izmantojot GMA Next-Gen SDK .

Pirms sākat

Pirms turpināt, veiciet tālāk norādītās darbības.

Ielādēt reklāmu

Lai ielādētu PictureInPictureAd , izveidojiet reklāmas pieprasījumu un izsauciet load metodi:

Kotlins 

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

Aizstājiet AD_UNIT_ID ar savas reklāmas vienības ID.

Rādīt reklāmu

Lai ekrānā parādītu attēla attēlā reklāmu, konfigurējiet attēla attēlā opcijas un izsauciet metodi show . Šajā piemērā tiek iestatīta reklāmas noklusējuma pozīcija un prezentācijas tvērums ekrānā:

Kotlins 

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

Iestatiet pozīciju

Pēc noklusējuma GMA Next-Gen SDK pirmo reizi parādot attēlu attēlā reklāmu, tā tiek rādīta ekrāna apakšējā labajā stūrī vai pēdējā zināmajā pozīcijā, ja tāda ir rādīta iepriekš. Lai pielāgotu reklāmas rādīšanas vietu, iestatiet pozīciju attēla attēlā opcijās. Šajā piemērā pozīcija satura augšpusē tiek iestatīta ekrāna augšējā kreisajā stūrī:

Kotlins 

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

Visas pieejamās pozīcijas skatiet PictureInPictureAdPosition .

Iestatiet prezentācijas tvērumu

Pēc noklusējuma GMA Next-Gen SDK saista attēla attēlā reklāmu ar pašreizējo resursdatora ekrānu. GMA Next-Gen SDK noraida reklāmu, ja resursdatora ekrāna skata hierarhija vairs nav atmiņā. Lai reklāma paliktu redzama pēc resursdatora ekrāna noņemšanas no atmiņas, iestatiet prezentācijas tvērumu uz lietojumprogrammu:

Kotlins 

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

Plašāku informāciju skatiet sadaļā Reklāmas redzamības saglabāšana dažādos ekrānos .

Iestatīt reklāmas notikuma atzvanīšanas funkciju

Lai apstrādātu attēla attēlā reklāmas dzīves cikla notikumus, pirms reklāmas rādīšanas iestatiet tai notikuma atzvanīšanas funkciju. Šī atzvanīšanas funkcija ziņo par standarta notikumiem, piemēram, klikšķiem un iespaidiem. Šī atzvanīšanas funkcija ziņo arī par attēla attēlā specifiskiem notikumiem, piemēram, reklāmas rādīšanas vai paslēpšanas laiku:

Kotlins 

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

Paslēpt reklāmu

Lai noņemtu peldošo reklāmu no ekrāna, izsauciet metodi hide . Šī metode izsauc notikuma “ad hidden” atzvanīšanas funkciju:

Kotlins 

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

Reklāmu resursu sakopšana

Lai izvairītos no atmiņas noplūdēm, izmetiet atsauci uz reklāmas objektu, kad lietotne beidz izmantot reklāmu. Piemēram, ja lietotne vairs nerāda reklāmu vai nemijiedarbojas ar to. Ekrāna darbības jomas reklāmām izmetiet atsauci, kad lietotne noņem resursdatora ekrānu no atmiņas. Lietotnes darbības jomas reklāmām saglabājiet reklāmas atsauci, kamēr lietotājs pārvietojas starp ekrāniem, un izmetiet atsauci, kad lietotājs aizver reklāmu:

Kotlins 

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

Saglabājiet reklāmu redzamu dažādos ekrānos

Ja prezentācijas tvērumu iestatāt lietojumprogrammai, attēla attēlā reklāma paliek redzama pat tad, ja lietotne no atmiņas noņem mitināšanas ekrānu. Lai mijiedarbotos ar reklāmu vai to aizvērtu, kad lietotājs pāriet prom no mitināšanas ekrāna, lietotnei ir jāsaglabā piekļuve attēla attēlā reklāmai. Iesakām reklāmu glabāt lietotnes līmeņa atsevišķā vai koplietojamā stāvokļa pārvaldniekā, nevis atsevišķa ekrāna instances mainīgajā.

Lai skatītu piemēru, kā nodrošināt reklāmas redzamību dažādos ekrānos, skatiet mūsu lietotņu paraugus: