Zdarzenia niestandardowe reklam natywnych

Wybierz platformę: Android (beta) Nowy-wybrany Android iOS

Wymagania wstępne

Skonfiguruj zdarzenia niestandardowe.

Wysyłanie żądania reklamy natywnej

Gdy w łańcuchu zapośredniczenia kaskadowego zostanie osiągnięty element zamówienia zdarzenia niestandardowego, wywoływana jest metoda loadNativeAd() w klasie o nazwie podanej podczas tworzenia zdarzenia niestandardowego. W tym przypadku metoda znajduje się w klasie SampleCustomEvent, która następnie wywołuje metodę loadNativeAd() w klasie SampleNativeCustomEventLoader.

Aby wysłać żądanie reklamy natywnej, utwórz lub zmodyfikuj klasę, która rozszerza klasę Adapter, aby zaimplementować metodę loadNativeAd(). Jeśli klasa rozszerzająca klasę Adapter już istnieje, zaimplementuj w niej metodę loadNativeAd(). Dodatkowo utwórz nową klasę, aby zaimplementować klasę UnifiedNativeAdMapper.

W naszym przykładzie zdarzenia niestandardowego, SampleCustomEvent rozszerza klasę Adapter, a następnie deleguje zadania do SampleNativeCustomEventLoader.

Java

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;

import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...
public class SampleCustomEvent extends Adapter {
  private SampleNativeCustomEventLoader nativeLoader;

  @Override
  public void loadNativeAd(
      @NonNull MediationNativeAdConfiguration adConfiguration,
      @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) {
    nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback);
    nativeLoader.loadAd();
  }
}

Klasa SampleNativeCustomEventLoader odpowiada za te zadania:

  • wczytywanie reklamy natywnej;

  • implementowanie klasy UnifiedNativeAdMapper;

  • otrzymywanie i zgłaszanie wywołań zwrotnych zdarzeń reklamowych do GMA Next-Gen SDK.

Opcjonalny parametr zdefiniowany w interfejsie Ad Managera jest uwzględniany w konfiguracji reklamy. Dostęp do parametru można uzyskać za pomocą kodu adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Ten parametr jest zwykle identyfikatorem jednostki reklamowej, którego pakiet SDK sieci reklamowej wymaga podczas tworzenia instancji obiektu reklamy.

Java

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationNativeAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...

public class SampleNativeCustomEventLoader extends SampleNativeAdListener {
  /** Configuration for requesting the native ad from the third-party network. */
  private final MediationNativeAdConfiguration mediationNativeAdConfiguration;

  /** Callback that fires on loading success or failure. */
  private final MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback>
      mediationAdLoadCallback;

  /** Callback for native ad events. */
  private MediationNativeAdCallback nativeAdCallback;

  /** Constructor */
  public SampleNativeCustomEventLoader(
      @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration,
      @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback>
              mediationAdLoadCallback) {
    this.mediationNativeAdConfiguration = mediationNativeAdConfiguration;
    this.mediationAdLoadCallback = mediationAdLoadCallback;
  }

  /** Loads the native ad from the third-party ad network. */
  public void loadAd() {
    // Create one of the Sample SDK's ad loaders to request ads.
    Log.i("NativeCustomEvent", "Begin loading native ad.");
    SampleNativeAdLoader loader =
        new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext());

    // All custom events have a server parameter named "parameter" that returns
    // back the parameter entered into the UI when defining the custom event.
    String serverParameter = mediationNativeAdConfiguration
        .getServerParameters()
        .getString(MediationConfiguration
        .CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
    Log.d("NativeCustomEvent", "Received server parameter.");

    loader.setAdUnit(serverParameter);

    // Create a native request to give to the SampleNativeAdLoader.
    SampleNativeAdRequest request = new SampleNativeAdRequest();
    NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions();
    if (options != null) {
      // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
      // send just the URLs for the images.
      request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets());

      request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
      switch (options.getMediaAspectRatio()) {
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN:
        default:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
      }
    }

    loader.setNativeAdListener(this);

    // Begin a request.
    Log.i("NativeCustomEvent", "Start fetching native ad.");
    loader.fetchAd(request);
  }
}

W zależności od tego, czy reklama zostanie pobrana, czy wystąpi błąd, wywołasz metodę albo onSuccess() albo onFailure(). Metoda onSuccess() jest wywoływana przez przekazanie instancji klasy, która implementuje MediationNativeAd.

Zwykle te metody są implementowane w wywołaniach zwrotnych z pakietu SDK innej firmy, który implementuje Twój adapter. W tym przykładzie pakiet SDK ma klasę SampleAdListener z odpowiednimi wywołaniami zwrotnymi:

Java

@Override
public void onNativeAdFetched(SampleNativeAd ad) {
  SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad);
  mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper);
}

@Override
public void onAdFetchFailed(SampleErrorCode errorCode) {
  mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode));
}

Mapowanie reklam natywnych

Różne pakiety SDK mają własne unikalne formaty reklam natywnych. Jeden może zwracać obiekty zawierające np. pole „title”, a inny – „headline”. Ponadto metody używane do śledzenia wyświetleń i przetwarzania kliknięć mogą się różnić w zależności od pakietu SDK.

Klasa UnifiedNativeAdMapper odpowiada za usuwanie tych różnic i dostosowywanie obiektu reklamy natywnej z zapośredniczonego pakietu SDK do interfejsu oczekiwanego przez GMA Next-Gen SDK. Zdarzenia niestandardowe powinny rozszerzać tę klasę, aby tworzyć własne mapowania specyficzne dla zapośredniczonego pakietu SDK. Oto przykładowy mapper reklam z naszego przykładowego projektu zdarzenia niestandardowego:

Java

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper;
import com.google.android.gms.ads.nativead.NativeAd;
...

public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper {

  private final SampleNativeAd sampleAd;

  public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
    sampleAd = ad;
    setHeadline(sampleAd.getHeadline());
    setBody(sampleAd.getBody());
    setCallToAction(sampleAd.getCallToAction());
    setStarRating(sampleAd.getStarRating());
    setStore(sampleAd.getStoreName());
    setIcon(
        new SampleNativeMappedImage(
            ad.getIcon(), ad.getIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setAdvertiser(ad.getAdvertiser());

    List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>();
    imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(),
        SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setImages(imagesList);

    if (sampleAd.getPrice() != null) {
      NumberFormat formatter = NumberFormat.getCurrencyInstance();
      String priceString = formatter.format(sampleAd.getPrice());
      setPrice(priceString);
    }

    Bundle extras = new Bundle();
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
    this.setExtras(extras);

    setOverrideClickHandling(false);
    setOverrideImpressionRecording(false);

    setAdChoicesContent(sampleAd.getInformationIcon());
  }

  @Override
  public void recordImpression() {
    sampleAd.recordImpression();
  }

  @Override
  public void handleClick(View view) {
    sampleAd.handleClick(view);
  }

  // The Sample SDK doesn't do its own impression/click tracking, instead relies on its
  // publishers calling the recordImpression and handleClick methods on its native ad object. So
  // there's no need to pass a reference to the View being used to display the native ad. If
  // your mediated network does need a reference to the view, the following method can be used
  // to provide one.

  @Override
  public void trackViews(View containerView, Map<String, View> clickableAssetViews,
      Map<String, View> nonClickableAssetViews) {
    super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews);
    // If your ad network SDK does its own impression tracking, here is where you can track the
    // top level native ad view and its individual asset views.
  }

  @Override
  public void untrackView(View view) {
    super.untrackView(view);
    // Here you would remove any trackers from the View added in trackView.
  }
}

Teraz przyjrzymy się bliżej kodowi konstruktora.

Zachowywanie odwołania do obiektu reklamy natywnej z zapośredniczenia

Konstruktor akceptuje parametr SampleNativeAd, czyli klasę reklamy natywnej używaną przez pakiet SDK do reklam natywnych. Mapper potrzebuje odwołania do reklamy z zapośredniczenia, aby mógł przekazywać zdarzenia kliknięć i wyświetleń. Klasa SampleNativeAd jest przechowywana jako zmienna lokalna.

Ustawianie właściwości zmapowanych komponentów

Konstruktor używa obiektu SampleNativeAd do wypełniania komponentów w klasie UnifiedNativeAdMapper.

Ten fragment kodu pobiera dane o cenie reklamy z zapośredniczenia i używa ich do ustawienia ceny mappera:

Java

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

W tym przykładzie reklama z zapośredniczenia przechowuje cenę jako wartość double, a Ad Manager używa do tego samego komponentu wartości String. Mapper odpowiada za obsługę tych typów konwersji.

Mapowanie komponentów z obrazem

Mapowanie komponentów z obrazem jest bardziej skomplikowane niż mapowanie typów danych, takich jak double czy String. Obrazy mogą być pobierane automatycznie lub zwracane jako wartości URL. Mogą się też różnić pod względem skali pikseli na cal.

Aby ułatwić zarządzanie tymi szczegółami, GMA Next-Gen SDK udostępnia klasę NativeAd.Image. Podobnie jak w przypadku mapowania reklamy natywnej z zapośredniczenia musisz utworzyć podklasę klasy UnifiedNativeAdMapper, tak samo w przypadku mapowania komponentów z obrazem musisz utworzyć podklasę klasy NativeAd.Image.

Oto przykład klasy SampleNativeMappedImage zdarzenia niestandardowego:

Java

public class SampleNativeMappedImage extends NativeAd.Image {

  private Drawable drawable;
  private Uri imageUri;
  private double scale;

  public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) {
    this.drawable = drawable;
    this.imageUri = imageUri;
    this.scale = scale;
  }

  @Override
  public Drawable getDrawable() {
    return drawable;
  }

  @Override
  public Uri getUri() {
    return imageUri;
  }

  @Override
  public double getScale() {
    return scale;
  }
}

Klasa SampleNativeAdMapper używa w tym wierszu zmapowanej klasy obrazu do ustawienia komponentu z obrazem mappera:

Java

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

Dodawanie pól do pakietu dodatków

Niektóre pakiety SDK z zapośredniczeniem udostępniają dodatkowe komponenty poza tymi, które są dostępne w formacie reklamy natywnej Ad Managera. Klasa UnifiedNativeAdMapper zawiera metodę setExtras(), która służy do przekazywania tych komponentów wydawcom. Klasa SampleNativeAdMapper używa jej do komponentu „stopień niesamowitości” pakietu SDK:

Java

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

Wydawcy mogą pobierać dane za pomocą metody getExtras() klasy NativeAd.

AdChoices

Twoje zdarzenie niestandardowe odpowiada za udostępnianie ikony Informacja za pomocą metody setAdChoicesContent() w klasie UnifiedNativeAdMapper. Oto fragment kodu z klasy SampleNativeAdMapper, który pokazuje, jak udostępnić ikonę Informacja:

Java

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

Zdarzenia wyświetleń i kliknięć

Zarówno GMA Next-Gen SDK, jak i pakiet SDK z zapośredniczeniem muszą wiedzieć, kiedy nastąpi wyświetlenie lub kliknięcie, ale tylko jeden z nich musi śledzić te zdarzenia. Zdarzenia niestandardowe mogą korzystać z 2 różnych metod w zależności od tego, czy zapośredniczony pakiet SDK obsługuje śledzenie wyświetleń i kliknięć.

Śledzenie kliknięć i wyświetleń za pomocą GMA Next-Gen SDK

Jeśli zapośredniczony pakiet SDK nie śledzi wyświetleń i kliknięć, ale udostępnia metody rejestrowania kliknięć i wyświetleń, GMA Next-Gen SDK może śledzić te zdarzenia i powiadamiać o nich adapter. Klasa UnifiedNativeAdMapper zawiera 2 metody: recordImpression() i handleClick(), które zdarzenia niestandardowe mogą implementować, aby wywoływać odpowiednią metodę w obiekcie reklamy natywnej z zapośredniczenia:

Java

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

Ponieważ klasa SampleNativeAdMapper zawiera odwołanie do obiektu reklamy natywnej pakietu SDK Sample, może wywołać odpowiednią metodę w tym obiekcie, aby zgłosić kliknięcie lub wyświetlenie. Pamiętaj, że metoda handleClick() przyjmuje 1 parametr: obiekt View odpowiadający komponentowi reklamy natywnej, który został kliknięty.

Śledzenie kliknięć i wyświetleń za pomocą zapośredniczonego pakietu SDK

Niektóre pakiety SDK z zapośredniczeniem mogą preferować samodzielne śledzenie kliknięć i wyświetleń. W takim przypadku należy zastąpić domyślne śledzenie kliknięć i wyświetleń, wykonując te 2 wywołania w konstruktorze klasy UnifiedNativeAdMapper:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, muszą zgłaszać zdarzenia onAdClicked() i onAdImpression() do pakietu SDK do reklam mobilnych Google.

Aby śledzić wyświetlenia i kliknięcia, zapośredniczony pakiet SDK prawdopodobnie potrzebuje dostępu do widoków. Zdarzenie niestandardowe powinno zastąpić metodę trackViews() i użyć jej do przekazania widoku reklamy natywnej do zapośredniczonego pakietu SDK w celu śledzenia. Przykładowy pakiet SDK z naszego przykładowego projektu zdarzenia niestandardowego (z którego pochodzą fragmenty kodu w tym przewodniku) nie korzysta z tej metody, ale jeśli by to robił, kod zdarzenia niestandardowego wyglądałby tak:

Java

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

Jeśli zapośredniczony pakiet SDK obsługuje śledzenie poszczególnych zasobów, może sprawdzić w clickableAssetViews, które widoki powinny być klikalne. Kluczem tego mapowania jest nazwa komponentu w NativeAdAssetNames. Klasa UnifiedNativeAdMapper oferuje odpowiednią metodę untrackView(), którą zdarzenia niestandardowe mogą zastąpić, aby zwolnić odwołania do widoku i odłączyć go od obiektu reklamy natywnej.

Przekazywanie zdarzeń zapośredniczenia do GMA Next-Gen SDK

Wszystkie wywołania zwrotne obsługiwane przez zapośredniczenie znajdziesz w MediationNativeAdCallback dokumentacji.

Ważne jest, aby zdarzenie niestandardowe przekazywało jak najwięcej tych wywołań zwrotnych, jak to możliwe, aby Twoja aplikacja otrzymywała równoważne zdarzenia z GMA Next-Gen SDK. Oto przykład użycia wywołań zwrotnych:

W ten sposób kończymy implementację zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny w GitHub.