Zdarzenia niestandardowe w reklamach natywnych

Wymagania wstępne

Dokończ konfigurację zdarzeń niestandardowych.

Wysyłanie żądania reklamy natywnej

Po dotarciu do elementu zamówienia zdarzenia niestandardowego w łańcuchu zapośredniczenia kaskadowegothe loadNativeAd() method zostaje wywołana z nazwą klasy podaną podczas tworzenia zdarzenia niestandardowego. W tym przypadku jest to metoda SampleCustomEvent, która wywołuje metodęthe loadNativeAd() method in SampleNativeCustomEventLoader.

Aby wysłać żądanie reklamy natywnej, utwórz lub zmodyfikuj klasę obejmującą rozszerzenie Adapter, aby zaimplementować loadNativeAd(). Jeśli klasa z rozszerzeniem Adapter już istnieje, zaimplementuj w niej loadNativeAd(). Dodatkowo utwórz nową klasę do zaimplementowania UnifiedNativeAdMapper.

W naszym przykładzie zdarzenia niestandardowego SampleCustomEvent implementuje tagthe Adapter interface , a potem przekazuje dostęp do funkcjiSampleNativeCustomEventLoader.

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

SampleNativeCustomEventLoader jest odpowiedzialny za następujące zadania:

• Wczytuję reklamę natywną

• Wdrożenie funkcji UnifiedNativeAdMapper interface

• Odbieranie i raportowanie wywołań zwrotnych zdarzeń reklamowych do pakietu SDK do reklam mobilnych Google

Opcjonalny parametr zdefiniowany w interfejsie Ad Manager jest uwzględniany w konfiguracji reklamy. Dostęp do parametru możesz uzyskać poprzez adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Ten parametr to zwykle identyfikator jednostki reklamowej, którego pakiet SDK sieci reklamowej wymaga do utworzenia instancji obiektu reklamowego.

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 się pobierze czy wystąpi błąd, wywołaj metodę onSuccess() lub onFailure(). onSuccess() jest wywoływane przez przekazanie instancji klasy, która implementuje MediationNativeAd.

Zwykle metody te są implementowane w wywołaniach zwrotnych z zewnętrznego pakietu SDK zaimplementowanego przez adapter. W tym przykładzie przykładowy pakiet SDK zawiera element SampleAdListener ze 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 formaty reklam natywnych. Jeden z nich może zwracać obiekty, które zawierają pole „title”, a inny – „headline”. Poza tym metody śledzenia wyświetleń i przetwarzania kliknięć mogą być różne w zależności od pakietu SDK.

UnifiedNativeAdMapper odpowiada za uzgodnienie tych różnic i dostosowanie obiektu reklamy natywnej pakietu SDK zapośredniczonego pakietu SDK tak, aby odpowiadał interfejsowi oczekiwanemu przez pakiet SDK do reklam mobilnych Google. Zdarzenia niestandardowe powinny rozszerzyć tę klasę o własne narzędzia do tworzenia map odpowiednie dla zapośredniczonego pakietu SDK. Oto przykład narzędzia do mapowania reklam z naszego przykładowego projektu zdarzeń niestandardowych:

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 przyjrzyjmy się bliżej kodowi konstruktora.

Przesyłaj odwołanie do obiektu reklamy natywnej zapośredniczonej

Konstruktor akceptuje parametr SampleNativeAd, czyli klasę reklamy natywnej używaną przez przykładowy pakiet SDK do wyświetlania reklam natywnych. Twórca map potrzebuje odwołania do reklamy zapośredniczonej, by przekazywać zdarzenia kliknięć i wyświetleń. SampleNativeAd jest przechowywana jako zmienna lokalna.

Ustaw właściwości mapowanego zasobu

Do wypełniania zasobów w obrębie UnifiedNativeAdMapper konstruktor używa obiektu SampleNativeAd.

Ten fragment kodu pobiera dane o cenach zapośredniczonych reklam i używa ich do ustalania ceny dla twórcy map:

Java

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

W tym przykładzie reklama zapośredniczona przechowuje cenę jako element double, aAd Manager używa właściwości String dla tego samego zasobu. Za obsługę tego typu konwersji odpowiada twórca map.

Komponenty z obrazem mapy

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 adresów URL. Różnice w skali pikseli do dpi również mogą być różne.

Aby ułatwić Ci zarządzanie tymi szczegółami, pakiet SDK do reklam mobilnych Google udostępnia klasę NativeAd.Image. Podobnie jak w przypadku tworzenia podklasy UnifiedNativeAdMapper do mapowania zapośredniczonych reklam natywnych musisz też utworzyć podklasę NativeAd.Image podczas mapowania zasobów z obrazem.

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

SampleNativeAdMapper używa w tym wierszu swojej zmapowanej klasy obrazu do ustawienia komponentu z obrazem ikony twórcy map:

Java

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

Dodaj pola do pakietu dodatków

Niektóre pakiety SDK zapośredniczone zapewniają dodatkowe zasoby pozaAd Manager formatem reklamy natywnej. Klasa UnifiedNativeAdMapper zawiera metodę setExtras(), która służy do przekazywania tych zasobów wydawcom. SampleNativeAdMapper wykorzystuje go w przypadku zasobu „stopień wspaniałości” przykładowego 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

Zdarzenie niestandardowe odpowiada za udostępnienie ikony Informacja za pomocą metody setAdChoicesContent() w witrynie UnifiedNativeAdMapper. Oto fragment kodu z witryny SampleNativeAdMapper, który pokazuje, jak dodać ikonę Informacja:

Java

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

Zdarzenia wyświetlenia i kliknięcia

Pakiet SDK do reklam mobilnych Google i pakiet zapośredniczony muszą wiedzieć, kiedy nastąpi wyświetlenie lub kliknięcie, ale tylko jeden pakiet SDK będzie śledzić te zdarzenia. Zdarzenia niestandardowe można stosować na 2 sposoby w zależności od tego, czy zapośredniczony pakiet SDK samodzielnie obsługuje śledzenie wyświetleń i kliknięć.

Śledzenie kliknięć i wyświetleń za pomocą pakietu SDK do reklam mobilnych Google

Jeśli zapośredniczony pakiet SDK nie wykonuje własnego śledzenia wyświetleń i kliknięć, ale umożliwia rejestrowanie kliknięć i wyświetleń, pakiet ten może śledzić te zdarzenia i powiadamiać adapter. UnifiedNativeAdMapper interface Udostępnia 2 metody: recordImpression() oraz handleClick() za pomocą zdarzeń niestandardowych, które mogą wywoływać odpowiednią metodę w zapośredniczonym obiekcie reklamy natywnej:

Java

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

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

Ponieważ obiekt SampleNativeAdMapper odwołuje się do obiektu reklamy natywnej przykładowego pakietu SDK, może wywołać w tym obiekcie odpowiednią metodę, aby zgłosić kliknięcie lub wyświetlenie. Pamiętaj, że metoda handleClick() przyjmuje pojedynczy parametr: obiekt View odpowiadający komponentowi reklamy natywnej, który otrzymał kliknięcie.

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

Niektóre pakiety SDK zapośredniczone mogą preferować samodzielne śledzenie kliknięć i wyświetleń. W takim przypadku musisz zastąpić domyślne śledzenie kliknięć i wyświetleń, wywołując w konstruktorze UnifiedNativeAdMapper te 2 wywołania:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, są wymagane do raportowania zdarzeń 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 wyświetleń, co umożliwi śledzenie. Zdarzenie niestandardowe powinno zastąpić metodę trackViews() i użyć jej do przekazania widoku reklamy natywnej do zapośredniczonego pakietu SDK na potrzeby śledzenia. Przykładowy pakiet SDK z naszego przykładowego projektu ze zdarzeniami niestandardowymi (z którego pobrano fragmenty kodu z tego przewodnika) nie stosuje tego podejścia, ale gdyby tak się stało, 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 zajrzeć w clickableAssetViews, by sprawdzić, które widoki mają umożliwiać klikanie. Ta mapa jest kluczowa w nazwie zasobu w regionie NativeAdAssetNames. UnifiedNativeAdMapper udostępnia odpowiednią metodę untrackView(), którą zdarzenia niestandardowe mogą zastąpić zdarzenia niestandardowe, aby zwolnić odwołania do widoku i odłączyć go od obiektu reklamy natywnej.

Przekierowywanie zdarzeń zapośredniczenia do pakietu SDK do reklam mobilnych Google

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

Ważne jest, aby zdarzenie niestandardowe przekazywało jak najwięcej takich wywołań zwrotnych, aby aplikacja otrzymywała równoważne zdarzenia z pakietu SDK do reklam mobilnych Google. Oto przykład użycia wywołań zwrotnych:

Na tym kończy się implementacja zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny na GitHub.