Reklamy natywne

Wybierz platformę: Android iOS Android (starsza wersja)

Gdy reklama natywna się wczyta, GMA Next-Gen SDK wywołuje detektor odpowiedniego formatu reklamy. Aplikacja jest wtedy odpowiedzialna za wyświetlenie reklamy, choć nie musi tego robić od razu. Aby ułatwić wyświetlanie formatów reklam zdefiniowanych przez system, pakiet SDK udostępnia kilka przydatnych zasobów, które opisujemy poniżej.

Ważne: Więcej informacji o reklamach natywnych znajdziesz w naszym poradniku dotyczącym reklam natywnych. Zapoznaj się też z zasadami i wytycznymi dotyczącymi reklam natywnych, aby dowiedzieć się, jak renderować reklamy natywne.

Definiowanie klasy NativeAdView

Zdefiniuj klasę NativeAdView. Ta klasa jest klasą ViewGroup i jest kontenerem najwyższego poziomu dla klasy NativeAdView. Każdy widok reklamy natywnej zawiera komponenty reklamy natywnej, takie jak element widoku MediaView lub element widoku Title, które muszą być elementami podrzędnymi obiektu NativeAdView.

Układ XML

Dodaj do projektu plik XML NativeAdView:

<com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
    android:orientation="vertical">
        <LinearLayout
        android:orientation="horizontal">
          <ImageView
          android:id="@+id/ad_app_icon" />
          <TextView
            android:id="@+id/ad_headline" />
        </LinearLayout>
        <!--Add remaining assets such as the image and media view.-->
    </LinearLayout>
</com.google.android.libraries.ads.mobile.sdk.nativead.NativeAdView>

Jetpack Compose

1. Uwzględnij folder JetpackCompose Utilities. Ten folder zawiera obiekty pomocnicze do tworzenia obiektu NativeAdView i komponentów.

Utwórz NativeAdView:

  import com.google.android.gms.compose_util.NativeAdAttribution
  import com.google.android.gms.compose_util.NativeAdView

  @Composable
  /** Display a native ad with a user defined template. */
  fun DisplayNativeAdView(nativeAd: NativeAd) {
      NativeAdView {
          // Display the ad attribution.
          NativeAdAttribution(text = context.getString("Ad"))
          // Add remaining assets such as the image and media view.
        }
    }

Obsługa wczytanej reklamy natywnej

Gdy reklama natywna się wczyta, obsłuż zdarzenie wywołania zwrotnego, rozwiń widok reklamy natywnej i dodaj go do hierarchii widoków:

Kotlin

// Build an ad request with native ad options to customize the ad.
val adTypes = listOf(NativeAd.NativeAdType.NATIVE)
val adRequest = NativeAdRequest
  .Builder("ca-app-pub-3940256099942544/2247696110", adTypes)
  .build()

val adCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      activity?.runOnUiThread {

        val nativeAdBinding = NativeAdBinding.inflate(layoutInflater)
        val adView = nativeAdBinding.root
        val frameLayout = myActivityLayout.nativeAdPlaceholder

        // Populate and register the native ad asset views.
        displayNativeAd(nativeAd, nativeAdBinding)

        // Remove all old ad views and add the new native ad
        // view to the view hierarchy.
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
      }
    }
  }

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback)

Java

// Build an ad request with native ad options to customize the ad.
List<NativeAd.NativeAdType> adTypes = Arrays.asList(NativeAd.NativeAdType.NATIVE);
NativeAdRequest adRequest = new NativeAdRequest
                                .Builder("ca-app-pub-3940256099942544/2247696110", adTypes)
                                .build();

NativeAdLoaderCallback adCallback = new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
      if (getActivity() != null) {
        getActivity()
          .runOnUiThread(() -> {
            // Inflate the native ad view and add it to the view hierarchy.
            NativeAdBinding nativeAdBinding = NativeAdBinding.inflate(getLayoutInflater());
            NativeAdView adView = (NativeAdView) nativeAdBinding.getRoot();
            FrameLayout frameLayout = myActivityLayout.nativeAdPlaceholder;

            // Populate and register the native ad asset views.
            displayNativeAd(nativeAd, nativeAdBinding);

            // Remove all old ad views and add the new native ad
            // view to the view hierarchy.
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        });
      }
    }
};

// Load the native ad with our request and callback.
NativeAdLoader.load(adRequest, adCallback);

Pamiętaj, że wszystkie komponenty danej reklamy natywnej powinny być renderowane w układzie NativeAdView. GMA Next-Gen SDK próbuje zarejestrować ostrzeżenie, gdy komponenty natywne są renderowane poza układem widoku reklamy natywnej.

Klasy widoku reklamy udostępniają też metody rejestrowania widoku używanego w przypadku poszczególnych komponentów oraz rejestrowania samego obiektu NativeAd. Zarejestrowanie widoków w ten sposób umożliwia pakietowi SDK automatyczne wykonywanie takich zadań jak:

• Rejestrowanie kliknięć
• Rejestrowanie wyświetleń, gdy na ekranie widoczny jest pierwszy piksel
• Wyświetlanie nakładki Informacja

Wyświetlanie reklamy natywnej

Poniższy przykład pokazuje, jak wyświetlić reklamę natywną:

Kotlin

private fun displayNativeAd(nativeAd: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  val nativeAdView = nativeAdBinding.root
  nativeAdView.advertiserView = nativeAdBinding.adAdvertiser
  nativeAdView.bodyView = nativeAdBinding.adBody
  nativeAdView.callToActionView = nativeAdBinding.adCallToAction
  nativeAdView.headlineView = nativeAdBinding.adHeadline
  nativeAdView.iconView = nativeAdBinding.adAppIcon
  nativeAdView.priceView = nativeAdBinding.adPrice
  nativeAdView.starRatingView = nativeAdBinding.adStars
  nativeAdView.storeView = nativeAdBinding.adStore

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.text = nativeAd.advertiser
  nativeAdBinding.adBody.text = nativeAd.body
  nativeAdBinding.adCallToAction.text = nativeAd.callToAction
  nativeAdBinding.adHeadline.text = nativeAd.headline
  nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.icon?.drawable)
  nativeAdBinding.adPrice.text = nativeAd.price
  nativeAd.starRating?.toFloat().let { value ->
    nativeAdBinding.adStars.rating = value
  }
  nativeAdBinding.adStore.text = nativeAd.store

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.visibility = getAssetViewVisibility(nativeAd.advertiser)
  nativeAdBinding.adBody.visibility = getAssetViewVisibility(nativeAd.body)
  nativeAdBinding.adCallToAction.visibility = getAssetViewVisibility(nativeAd.callToAction)
  nativeAdBinding.adHeadline.visibility = getAssetViewVisibility(nativeAd.headline)
  nativeAdBinding.adAppIcon.visibility = getAssetViewVisibility(nativeAd.icon)
  nativeAdBinding.adPrice.visibility = getAssetViewVisibility(nativeAd.price)
  nativeAdBinding.adStars.visibility = getAssetViewVisibility(nativeAd.starRating)
  nativeAdBinding.adStore.visibility = getAssetViewVisibility(nativeAd.store)

  // Inform GMA Next-Gen SDK that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia)
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return [View.VISIBLE] if the asset is not null, [View.INVISIBLE] otherwise.
*/
private fun getAssetViewVisibility(asset: Any?): Int {
  return if (asset == null) View.INVISIBLE else View.VISIBLE
}

Java

private void displayNativeAd(ad: NativeAd, nativeAdBinding : NativeAdBinding) {
  // Set the native ad view elements.
  NativeAdView nativeAdView = nativeAdBinding.getRoot();
  nativeAdView.setAdvertiserView(nativeAdBinding.adAdvertiser);
  nativeAdView.setBodyView(nativeAdBinding.adBody);
  nativeAdView.setCallToActionView(nativeAdBinding.adCallToAction);
  nativeAdView.setHeadlineView(nativeAdBinding.adHeadline);
  nativeAdView.setIconView(nativeAdBinding.adAppIcon);
  nativeAdView.setPriceView(nativeAdBinding.adPrice);
  nativeAdView.setStarRatingView(nativeAdBinding.adStars);
  nativeAdView.setStoreView(nativeAdBinding.adStore);

  // Set the view element with the native ad assets.
  nativeAdBinding.adAdvertiser.setText(nativeAd.getAdvertiser());
  nativeAdBinding.adBody.setText(nativeAd.getBody());
  nativeAdBinding.adCallToAction.setText(nativeAd.getCallToAction());
  nativeAdBinding.adHeadline.setText(nativeAd.getHeadline());
  if (nativeAd.getIcon() != null) {
      nativeAdBinding.adAppIcon.setImageDrawable(nativeAd.getIcon().getDrawable());
  }
  nativeAdBinding.adPrice.setText(nativeAd.getPrice());
  if (nativeAd.getStarRating() != null) {
      nativeAdBinding.adStars.setRating(nativeAd.getStarRating().floatValue());
  }
  nativeAdBinding.adStore.setText(nativeAd.getStore());

  // Hide views for assets that don't have data.
  nativeAdBinding.adAdvertiser.setVisibility(getAssetViewVisibility(nativeAd.getAdvertiser()));
  nativeAdBinding.adBody.setVisibility(getAssetViewVisibility(nativeAd.getBody()));
  nativeAdBinding.adCallToAction.setVisibility(getAssetViewVisibility(nativeAd.getCallToAction()));
  nativeAdBinding.adHeadline.setVisibility(getAssetViewVisibility(nativeAd.getHeadline()));
  nativeAdBinding.adAppIcon.setVisibility(getAssetViewVisibility(nativeAd.getIcon()));
  nativeAdBinding.adPrice.setVisibility(getAssetViewVisibility(nativeAd.getPrice()));
  nativeAdBinding.adStars.setVisibility(getAssetViewVisibility(nativeAd.getStarRating()));
  nativeAdBinding.adStore.setVisibility(getAssetViewVisibility(nativeAd.getStore()));

  // Inform GMA Next-Gen SDK that you have finished populating
  // the native ad views with this native ad.
  nativeAdView.registerNativeAd(nativeAd, nativeAdBinding.adMedia);
}

/**
* Determines the visibility of an asset view based on the presence of its asset.
*
* @param asset The native ad asset to check for nullability.
* @return {@link View#VISIBLE} if the asset is not null, {@link View#INVISIBLE} otherwise.
*/
private int getAssetViewVisibility(Object asset) {
    return (asset == null) ? View.INVISIBLE : View.VISIBLE;
}

Uwaga: jeśli wolisz renderować reklamę natywną bez instancji MediaView, podczas wywoływania metody registerNativeAd() przekaż wartość null parametru widoku multimediów.

Nakładka Informacja

Pakiet SDK dodaje nakładkę Informacja do każdego widoku reklamy. W wybranym rogu widoku reklamy natywnej zostaw miejsce na automatycznie wstawiane logo Informacja. Ważne jest, aby nakładka Informacja była widoczna, dlatego należy odpowiednio dobrać kolory tła i obrazy. Więcej informacji o wyglądzie i działaniu nakładki znajdziesz w artykule Opisy pól reklam natywnych.

Oznaczenie reklamy

Musisz wyświetlać oznaczenie reklamy, aby wskazać, że widok jest reklamą. Więcej informacji znajdziesz w wytycznych dotyczących zasad.

Obsługa kliknięć

Nie implementuj żadnych niestandardowych modułów obsługi kliknięć w żadnych widokach nad widokiem reklamy natywnej ani w jego obrębie. Kliknięcia komponentów widoku reklamy są obsługiwane przez pakiet SDK, o ile prawidłowo wypełnisz i zarejestrujesz widoki komponentów.

Aby wykrywać kliknięcia, zaimplementuj wywołanie zwrotne kliknięcia GMA Next-Gen SDK:

Kotlin

private fun setEventCallback(nativeAd: NativeAd) {
  nativeAd.adEventCallback =
    object : NativeAdEventCallback {
      override fun onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.")
      }
    }
}

Java

private void setEventCallback(NativeAd nativeAd) {
  nativeAd.setAdEventCallback(new NativeAdEventCallback() {
      @Override
      public void onAdClicked() {
        Log.d(Constant.TAG, "Native ad recorded a click.");
      }
  });
}

ImageScaleType

Klasa MediaView ma właściwość ImageScaleType podczas wyświetlania obrazów. Jeśli chcesz zmienić sposób skalowania obrazu w elemencie MediaView, ustaw odpowiedni element ImageView.ScaleType za pomocą metody setImageScaleType() elementu MediaView:

Kotlin

nativeAdViewBinding.mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP

Java

nativeAdViewBinding.mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);

MediaContent

Klasa MediaContent zawiera dane związane z treściami multimedialnymi reklamy natywnej, które są wyświetlane za pomocą klasy MediaView. Gdy właściwość MediaView mediaContent jest ustawiona z instancją MediaContent:

• Jeśli komponent wideo jest dostępny, jest buforowany i zaczyna się odtwarzać w MediaView. Aby sprawdzić, czy zasób wideo jest dostępny, sprawdź hasVideoContent().

• Jeśli reklama nie zawiera komponentu wideo, pobierany jest komponent mainImage i umieszczany w elemencie MediaView.

Dodaj podsumowanie kreacji

Ostrzeżenie: dostęp do tej funkcji jest ograniczony. Aby poprosić o dostęp, skontaktuj się z menedżerem konta.

W aplikacjach do czatu konwersacyjnego i czatu z AI GMA Next-Gen SDK udostępnia komponent podsumowania kreacji (creativeSummary) na potrzeby kreacji. Możesz zintegrować reklamy z procesami czatu w aplikacji za pomocą wiadomości powitalnej.

Dodawanie widoku tekstu do układu

Dodaj element TextView dla komponentu podsumowania kreacji w układzie kontenera NativeAdView:

<TextView
    android:id="@+id/ad_creative_summary"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:textSize="13sp" />

Wypełnianie i rejestrowanie widoku

Wypełnij TextView wartością creativeSummary i zarejestruj we właściwości creativeSummaryView obiektu NativeAdView. Zarejestrowanie widoku umożliwia automatyczne śledzenie kliknięć komponentu podsumowania kreacji.

Uwaga: interfejsy API creativeSummary i creativeSummaryView wymagają adnotacji @OptIn(ExperimentalApi::class).

Kotlin

private fun populateCreativeSummary(
  nativeAd: NativeAd,
  nativeAdBinding: NativeAdBinding,
  nativeAdView: NativeAdView,
) {
  val summary = nativeAd.creativeSummary
  if (summary == null) {
    nativeAdBinding.adCreativeSummary.visibility = View.GONE
    return
  }

  nativeAdBinding.adCreativeSummary.text = summary
  nativeAdBinding.adCreativeSummary.visibility = View.VISIBLE
  nativeAdView.creativeSummaryView = nativeAdBinding.adCreativeSummary
}

Java

private void populateCreativeSummary(
    NativeAd nativeAd, NativeAdBinding nativeAdBinding, NativeAdView nativeAdView) {
  String summary = nativeAd.getCreativeSummary();
  if (summary == null) {
    nativeAdBinding.adCreativeSummary.setVisibility(View.GONE);
    return;
  }

  nativeAdBinding.adCreativeSummary.setText(summary);
  nativeAdBinding.adCreativeSummary.setVisibility(View.VISIBLE);
  nativeAdView.setCreativeSummaryView(nativeAdBinding.adCreativeSummary);
}

Śledzenie kliknięć i zmodyfikowany tekst

• Renderowanie bezpośrednie: gdy renderujesz dokładny ciąg znaków creativeSummary dostarczony przez pakiet SDK, zarejestruj go we właściwości creativeSummaryView w kontenerze NativeAdView, aby umożliwić obsługę kliknięć przez pakiet SDK.
• Zmodyfikowane wprowadzenia: jeśli aplikacja modyfikuje, podsumowuje lub dołącza niestandardowy tekst konwersacyjny do podsumowania kreacji, umieść zmodyfikowany tekst poza kontenerem NativeAdView.

Niszczenie reklamy

Po wyświetleniu reklamy natywnej zniszcz ją. Ten przykład niszczy reklamę natywną:

Kotlin

nativeAd.destroy()

Java

nativeAd.destroy();

Dalsze kroki

Zapoznaj się z tymi tematami:

• Prywatność użytkownika

Przykład

Pobierz i uruchom przykładową aplikację, która pokazuje, jak używać GMA Next-Gen SDK.