Ta strona została przetłumaczona przez Cloud Translation API.

Zdarzenia niestandardowe reklam natywnych

Wymagania wstępne

Dokończ konfigurowanie zdarzeń niestandardowych.

Wysyłanie żądania reklamy natywnej

Gdy element zamówienia zdarzenia niestandardowego zostanie osiągnięty w łańcuchu zapośredniczenia kaskadowego, metoda loadNativeAd() jest wywoływana dla nazwy klasy podanej przez Ciebie podczas utworzenie niestandardowego . W tym przypadku ta metoda jest w komórce SampleCustomEvent, która następnie wywołuje metody loadNativeAd() w SampleNativeCustomEventLoader.

Aby poprosić o reklamę natywną, utwórz lub zmodyfikuj klasę rozszerzającą klasę Adapter, aby zaimplementować interfejs loadNativeAd(). Jeśli klasa rozszerzająca Adapter już istnieje, zaimplementuj w niej funkcję loadNativeAd(). Dodatkowo utwórz nową klasę do zaimplementowania UnifiedNativeAdMapper

W przykładzie zdarzenia niestandardowego: SampleCustomEvent rozszerza zajęcia Adapter, a następnie przekazuje dostęp 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();
  }
}

SampleNativeCustomEventLoader odpowiada za te zadania:

Wczytywanie reklamy natywnej.
Wdrażanie klasy UnifiedNativeAdMapper.
Odbieranie i zgłaszanie do pakietu SDK do reklam mobilnych Google wywołań zwrotnych zdarzeń reklamy.

Opcjonalny parametr zdefiniowany w interfejsie AdMob jest uwzględniany w konfiguracji reklamy. Dostęp do parametru można uzyskać za pomocą: adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) Ten parametr to zwykle identyfikator jednostki reklamowej, którego pakiet SDK sieci reklamowej wymaga podczas tworzenia 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 udało się pobrać reklamę, czy wystąpił błąd, wywołasz metodę onSuccess() lub onFailure(). Funkcja onSuccess() jest wywoływana przez przekazanie wystąpienia klasy, która implementuje funkcję MediationNativeAd.

Zwykle te metody są implementowane w ramach wywołań zwrotnych z zewnętrznego pakietu SDK, który jest używany przez Twój adapter. W tym przykładzie pakiet SDK Sample ma element 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

Każdy pakiet SDK ma własne unikalne formaty reklam natywnych. Jedna może wrócić obiekty zawierające „tytuł” a inne pole może mieć „headline”. Dodatkowo metody śledzenia wyświetleń i przetwarzania kliknięć mogą się różnić w zależności od pakietu SDK.

UnifiedNativeAdMapper jest odpowiedzialny za uzgadnianie tych różnic i dostosowywanie natywnego obiektu reklamy pośredniczącego pakietu SDK do wymagań interfejsu pakietu SDK do reklam mobilnych Google. Zdarzenia niestandardowe powinny rozszerzać tę klasę, aby tworzyć własne mapery dostosowane do ich pośredniczących pakietów SDK. Oto przykładowy kreator map reklam opracowany przez przykładowy projekt 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ę kodowi konstruktora.

Zachowaj odwołanie do obiektu zapośredniczonej reklamy natywnej

Konstruktor akceptuje parametr SampleNativeAd, czyli używaną klasę reklamy natywnej. przy użyciu przykładowego pakietu SDK do swoich reklam natywnych. Twórca map potrzebuje odniesienia do zapośredniczona, tak aby mogła przekazywać zdarzenia kliknięć i wyświetleń. SampleNativeAd to zapisane jako zmienna lokalna.

Ustawianie właściwości zmapowanego zasobu

Konstruktor używa obiektu SampleNativeAd do wypełniania zasobów w UnifiedNativeAdMapper

Ten fragment kodu pobiera dane o cenie reklamy pośredniej 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 zapośredniczona reklama przechowuje cenę jako double, a AdMob używa parametru String dla tego samego komponentu. Za obsługę tych typów konwersji odpowiada mapper.

Komponenty z obrazem mapy

Mapowanie komponentów z obrazem jest bardziej skomplikowane niż mapowanie typów danych, takich jak double lub String. Obrazy mogą być pobierane automatycznie lub zwracanych jako wartości adresów URL. Ich skale pikseli na dpi mogą się też różnić.

Aby ułatwić zarządzanie tymi informacjami, pakiet SDK do reklam mobilnych Google udostępnia klasę NativeAd.Image. Zasadniczo w taki sam sposób, w jaki musisz utworzyć podklasę UnifiedNativeAdMapper, aby zmapować zapośredniczoną reklamę natywną, musisz też utworzyć podklasa klasy NativeAd.Image podczas mapowania komponentó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, aby ustawić zasób graficzny 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 zapośredniczone pakiety SDK dostarczają dodatkowe zasoby poza tymi w Format reklamy natywnej AdMob. UnifiedNativeAdMapper klasa zawiera metodę setExtras(), która służy do przekazywania tych zasobów do wydawców. SampleNativeAdMapper wykorzystuje to w przykładowym pakiecie SDK „stopień wspaniałości” zasób:

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 dodanie ikony Informacja za pomocą tagu Metoda setAdChoicesContent() na UnifiedNativeAdMapper. Oto fragment artykułu SampleNativeAdMapper, który pokazuje, jak podać ikonę AdChoices:

Java

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

Zdarzenia wyświetlenia i kliknięcia

Zarówno pakiet SDK do reklam mobilnych Google, jak i pakiet zapośredniczony SDK muszą wiedzieć, kiedy wyświetlenie lub kliknięcie, ale tylko jeden pakiet SDK potrzebuje do ich śledzenia. Zdarzenia niestandardowe mogą korzystać z 2 różnych podejść, w zależności od tego, czy pośredniczący pakiet SDK obsługuje samodzielnie ś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 prowadzi własnego śledzenia wyświetleń i kliknięć, udostępnia metody rejestrowania kliknięć i wyświetleń, pakiet SDK do reklam mobilnych Google śledzić te zdarzenia i powiadomić adapter. Klasa UnifiedNativeAdMapper zawiera 2 metody: recordImpression() i handleClick(), które mogą implementować zdarzenia niestandardowe, aby wywołać odpowiednią metodę w obiekcie reklamy natywnej z użyciem pośrednictwa:

Java

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

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

Ponieważ obiekt SampleNativeAdMapper zawiera odwołanie do natywnego obiektu Sample SDK, może wywołać odpowiednią metodę tego obiektu, aby zgłosić kliknięcie lub wyświetlenie. Pamiętaj, że metoda handleClick() pobiera pojedynczy parametr: obiekt View odpowiadający zasobowi reklamy natywnej, który uzyskało kliknięcie.

Śledzenie kliknięć i wyświetleń za pomocą SDK z zapośredniczeniem

Niektóre pośredniczące biblioteki SDK mogą samodzielnie śledzić kliknięcia i wyświetlenia. W w takim przypadku musisz zastąpić domyślne śledzenie kliknięć i wyświetleń przez dwóch poniższych wywołań w konstruktorze UnifiedNativeAdMapper:

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, pośredniczący pakiet SDK musi mieć dostęp do widoków, które umożliwiają śledzenie. Zdarzenie niestandardowe powinno zastąpić metodę trackViews() i wykorzystać ją do przekazania widoku reklamy natywnej do pośredniczącego pakietu SDK w celu śledzenia. Przykładowy pakiet SDK z naszego przykładowego projektu dotyczącego zdarzeń niestandardowych (z którego pochodzą fragmenty kodu w tym przewodniku) nie korzysta z tego podejścia. Gdyby jednak tak było, kod zdarzenia niestandardowego wyglądałby mniej więcej 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ć do środka clickableAssetViews, aby sprawdzić, które widoki powinny być klikalne. Ta mapa jest powiązana z nazwą zasobu w elementach NativeAdAssetNames. Obiekt UnifiedNativeAdMapper udostępnia odpowiednią metodę untrackView(), którą zdarzenia niestandardowe mogą zastąpić, aby zwolnić wszystkie odwołania do widoku i odłączyć go od natywnego obiektu reklamy.

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

Wszystkie funkcje wywołania zwrotnego obsługiwane przez pośredniczenie znajdziesz w dokumentacji MediationNativeAdCallback.

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

Spowoduje to zakończenie implementacji zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny na GitHub