Wdróż reklamy ikon

Reklamy z ikoną to małe miejsca docelowe z ikoną aplikacji, które uzupełniają wrażenia użytkownika systemu operacyjnego i są elastyczne, dzięki czemu mogą towarzyszyć większości działań na poziomie systemu operacyjnego, takich jak ekran blokady i ekran udostępniania. Reklamy z ikonami możesz wyświetlać pojedynczo lub w kilku grupach. Każda reklama zawiera zestaw elementów tekstowych i ciągów znaków, które Twoja aplikacja musi renderować. Te obrazy pokazują reklamy z ikonami wyświetlane w folderze aplikacji:

Z tego przewodnika dowiesz się, jak wysyłać żądania reklam z ikonami i je wyświetlać.

Wymagania wstępne

Zanim zaczniesz, musisz mieć GMA Next-Gen SDK w wersji 0.8.0-alpha01 lub nowszej.

Zawsze testuj za pomocą reklam testowych

Podczas tworzenia i testowania aplikacji używaj reklam testowych zamiast reklam produkcyjnych. Nieużywanie reklam testowych może spowodować zawieszenie konta.

Aby wyświetlać reklamy testowe, użyj własnych jednostek reklamowych i włącz urządzenia testowe lub użyj tego identyfikatora jednostki reklamowej testowej dla reklam z ikonami na Androida:

ca-app-pub-3940256099942544/1476272466
Szczegółowe informacje o reklamach testowych GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Wczytywanie reklamy z ikoną

Wczytaj reklamę z ikoną za pomocą żądania reklamy z ikoną i obsłuż zdarzenia wczytywania reklam:

Kotlin

private fun loadIconAd() {
  val request =
    IconAdRequest.Builder(AD_UNIT_ID)
      // The "AdChoices" badge is rendered at the top right corner of the icon ad
      // if left unspecified.
      .setAdChoicesPlacement(AdChoicesPlacement.BOTTOM_RIGHT)
      // It is recommended to specify the placement of your icon ad
      // to help Google optimize your icon ad performance.
      .setIconAdPlacement(IconAdPlacement.BROWSER)
      .build()

  IconAd.load(
    request,
    object : AdLoadCallback<IconAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(Constant.TAG, "Icon ad failed to load: $adError")
        showToast("Icon ad failed to load.")
      }

      override fun onAdLoaded(ad: IconAd) {
        Log.d(Constant.TAG, "Icon ad loaded")
        // Always call destroy() on ads on removal.
        iconAd?.destroy()
        iconAd = ad
        setAdEventCallback(ad)
        displayIconAd(ad)
      }
    },
  )
}

IconAdFragment.kt

Java

private void loadIconAd() {
  IconAdRequest request =
      new IconAdRequest.Builder(AD_UNIT_ID)
          // The "AdChoices" badge is rendered at the top right corner of the icon ad
          // if left unspecified.
          .setAdChoicesPlacement(AdChoicesPlacement.BOTTOM_RIGHT)
          // It is recommended to specify the placement of your icon ad
          // to help Google optimize your icon ad performance.
          .setIconAdPlacement(IconAdPlacement.BROWSER)
          .build();

  IconAd.load(
      request,
      new AdLoadCallback<IconAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(Constant.TAG, "Icon ad failed to load :" + adError);
          showToast("Icon ad failed to load with error code: " + adError.getCode());
        }

        @Override
        public void onAdLoaded(@NonNull IconAd ad) {
          Log.d(Constant.TAG, "Icon ad loaded.");

          // Always call destroy() on ads on removal.
          if (iconAd != null) {
              iconAd.destroy();
          }
          iconAd = ad;
          setAdEventCallback(ad);
          displayIconAd(ad);
        }
      });
}

IconAdFragment.java

Tworzenie widoku reklamy z ikoną

Reklamy z ikoną muszą używać elementu głównego IconAdView w przypadku swoich komponentów. W obszarze wyświetlania reklamy z ikoną umieść wszystkie elementy wizualne reklamy.

Poniższy przykład pokazuje układ, który umożliwia utworzenie widoku reklamy z ikoną:

<?xml version="1.0" encoding="utf-8"?>
<com.google.android.libraries.ads.mobile.sdk.iconad.IconAdView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

  <LinearLayout
      android:id="@+id/icon_ad_container"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_gravity="center"
      android:background="#00FFC107"
      android:orientation="vertical">

    <LinearLayout
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:orientation="horizontal">
      <TextView
          android:id="@+id/ad_badge"
          android:width="15dp"
          android:height="15dp"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:background="#FFC107"
          android:text="Ad"
          android:textColor="#FFFFFF"
          android:textSize="12sp" />
      <TextView
          android:id="@+id/ad_headline"
          android:textStyle="normal"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:layout_gravity="center"
          android:autoText="true"
          android:inputType="text|textMultiLine"
          android:textColor="#808080"
          android:textSize="12sp" />
    </LinearLayout>

    <com.google.android.material.imageview.ShapeableImageView xmlns:app="http://schemas.android.com/apk/res-auto"
        android:id="@+id/ad_icon"
        android:layout_width="100dp"
        android:layout_height="100dp"
        android:layout_gravity="center"
        android:adjustViewBounds="true"
        android:background="@android:color/holo_green_light"
        android:contentDescription="@string/content_description_icon_ad"
        android:theme="@style/Theme.AppCompat.Light"
        app:shapeAppearanceOverlay="@style/roundedCorners"
        app:strokeColor="@null" />

    <RatingBar
        android:id="@+id/ad_stars"
        style="?android:attr/ratingBarStyleSmall"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:isIndicator="true"
        android:numStars="5"
        android:stepSize="0.5" />
    <Button
        android:id="@+id/ad_call_to_action"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:gravity="center"
        android:textSize="12sp" />
  </LinearLayout>

</com.google.android.libraries.ads.mobile.sdk.iconad.IconAdView>

Wyświetlanie reklamy z ikoną na ekranie

Aby wyświetlić reklamę z ikoną na ekranie, wykonaj te czynności:

  1. Rozwiń widok reklamy z ikoną i dodaj go do hierarchii widoków.

  2. Wypełnij każdy widok dziecka odpowiednim komponentem reklamy z ikoną.

W przykładzie poniżej pokazujemy, jak wyświetlić reklamę z ikoną na ekranie:

Kotlin

val iconAdViewBinding = IconAdBinding.inflate(layoutInflater)
// Add the ad view to the active view hierarchy.
binding.iconAdContainer.addView(iconAdViewBinding.root)
val iconAdView = iconAdViewBinding.root

// Populate the view elements with their respective icon ad asset.
iconAdView.callToActionView = iconAdViewBinding.adCallToAction
iconAdView.headlineView = iconAdViewBinding.adHeadline
iconAdView.iconView = iconAdViewBinding.adIcon
iconAdView.starRatingView = iconAdViewBinding.adStars
IconAdFragment.kt

Java

IconAdBinding iconAdViewBinding = IconAdBinding.inflate(getLayoutInflater());
// Add the ad view to the active view hierarchy.
binding.iconAdContainer.addView(iconAdViewBinding.getRoot());
IconAdView iconAdView = iconAdViewBinding.getRoot();

// Populate the view elements with their respective icon ad asset.
iconAdView.setCallToActionView(iconAdViewBinding.adCallToAction);
iconAdView.setHeadlineView(iconAdViewBinding.adHeadline);
iconAdView.setIconView(iconAdViewBinding.adIcon);
iconAdView.setStarRatingView(iconAdViewBinding.adStars);
IconAdFragment.java

Umożliwienie klikania reklamy z ikoną

Funkcja GMA Next-Gen SDK rejestruje detektory kliknięć dla każdego widoku zasobu, który jest mapowany po wywołaniu funkcji registerIconAd(). Przed zarejestrowaniem reklamy z ikoną zmapuj właściwości wyświetlenia reklamy z ikoną na odpowiedni widok w hierarchii widoków:

Kotlin

// Map each asset view property to the corresponding view in your view hierarchy.
iconAdViewBinding.adCallToAction.text = iconAd.callToAction
iconAdViewBinding.adHeadline.text = iconAd.headline
iconAdViewBinding.adIcon.setImageDrawable(iconAd.icon.drawable)
iconAd.starRating?.toFloat().also { value ->
  if (value != null) {
    iconAdViewBinding.adStars.rating = value
  }
}

// Register the icon ad with the view presenting it.
iconAdView.registerIconAd(iconAd)
IconAdFragment.kt

Java

// Map each asset view property to the corresponding view in your view hierarchy.
iconAdViewBinding.adCallToAction.setText(iconAd.getCallToAction());
iconAdViewBinding.adHeadline.setText(iconAd.getHeadline());
iconAdViewBinding.adIcon.setImageDrawable(iconAd.getIcon().getDrawable());

if (iconAd.getStarRating() != null) {
  iconAdViewBinding.adStars.setRating(iconAd.getStarRating().floatValue());
}

// Register the icon ad with the view presenting it.
iconAdView.registerIconAd(iconAd);
IconAdFragment.java
.

Opcjonalnie: ustaw wywołanie zwrotne zdarzenia reklamy z ikoną.

Aby obsługiwać zdarzenia cyklu życia reklamy z ikoną, ustaw wywołanie zwrotne zdarzenia:

Kotlin

iconAd.adEventCallback =
  object : IconAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Icon ad showed full screen content.
    }

    override fun onAdDismissedFullScreenContent() {
      // Icon ad dismissed full screen content.
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Icon ad failed to show full screen content.
    }

    override fun onAdImpression() {
      // Icon ad recorded an impression.
    }

    override fun onAdClicked() {
      // Icon ad recorded a click.
    }

    override fun onAdPaid(value: AdValue) {
      // Icon ad estimated to have earned money.
    }
  }
IconAdFragment.kt

Java

iconAd.setAdEventCallback(
    new IconAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Icon ad showed full screen content.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Icon ad dismissed full screen content.
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Icon ad failed to show full screen content.
      }

      @Override
      public void onAdImpression() {
        // Icon ad recorded an impression.
      }

      @Override
      public void onAdClicked() {
        // Icon ad recorded a click.
      }

      @Override
      public void onAdPaid(@NonNull AdValue value) {
        // Icon ad estimated to have earned money.
      }
    });
IconAdFragment.java

Optymalizowanie wydajności

W kolejnych sekcjach znajdziesz opcjonalne kroki wdrażania, które pozwolą Ci zoptymalizować skuteczność reklam z ikonami.

Używanie korelatora do wczytywania wielu reklam

Podczas wczytywania wielu reklam z ikonami, które mają być wyświetlane razem, wysyłaj kolejne żądania z tą samą wartością korelatora, aby mieć pewność, że wczytane reklamy są unikalne. Okres ważności korelatora wynosi 10 sekund. Serwer nie uznaje za powiązane żądań, które zostały wysłane w odstępie większym niż 10 sekund.

W przykładzie poniżej pokazujemy, jak ustawić wartość korelatora w żądaniu reklamy:

Kotlin

val correlator = Correlator.generateCorrelator()
val request =
      IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setCorrelator(correlator)
        .build()

Java

Correlator correlator = Correlator.generateCorrelator();
IconAdRequest request =
    new IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setCorrelator(correlator)
        .build();

Ustawianie miejsca docelowego reklamy z ikoną

Aby pomóc Google w określeniu miejsca docelowego reklamy z ikoną i zoptymalizowaniu jej skuteczności, zalecamy określenie w momencie wysyłania żądania, gdzie chcesz wyświetlać reklamy z ikonami.

Użyj wartości wyliczeniowej IconAdPlacement, która najlepiej odzwierciedla Twój przypadek użycia:

Kotlin

val request =
  IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
    .setIconAdPlacement(IconAdPlacement.BROWSER)
    .build()

Java

IconAdRequest request =
    new IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setIconAdPlacement(IconAdPlacement.BROWSER)
        .build();