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 wysłać żądanie reklamy natywnej, utwórz lub zmodyfikuj klasę, która rozszerza Adapter do zaimplementuj loadNativeAd(). Jeśli klasa, która rozszerza zakres Adapter, już istnieje, zaimplementuj w niej 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.

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 następujące zadania:

• Wczytuję reklamę natywną.

• Wdrażanie klasy UnifiedNativeAdMapper.

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

Opcjonalny parametr zdefiniowany w interfejsie Ad Managera to uwzględnionych w konfiguracji reklamy. Dostęp do parametru można uzyskać za pomocą: adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) Jest to zwykle identyfikator jednostki reklamowej wykorzystywany przez pakiet SDK sieci reklamowej wymagane przy tworzeniu wystąpienia obiektu reklamy.

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 została pobrana, czy też wystąpił błąd, wywoła albo onSuccess() lub onFailure() Funkcja onSuccess() jest wywoływana przez przekazanie instancji klasy, która implementuje MediationNativeAd

Te metody są zwykle implementowane wewnątrz wywołań zwrotnych z funkcji pakietu SDK innej firmy wdrożonego przez adapter. W tym przykładzie Przykładowy pakiet SDK zawiera SampleAdListener z odpowiednimi wywołaniami zwrotnymi:

@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 liczba kliknięć może być różna w zależności od pakietu SDK.

Za uzgodnienie tych różnic odpowiada UnifiedNativeAdMapper. dostosowania obiektu reklamy natywnej pakietu SDK zapośredniczonego do interfejsu, który powinien pakiet SDK do reklam mobilnych Google. Zdarzenia niestandardowe powinny rozszerzać tę klasę o możliwość tworzenia z własnymi twórcami map specyficznymi dla ich zapośredniczonego pakietu SDK. Oto przykładowy kreator map reklam opracowany przez przykładowy projekt zdarzenia niestandardowego:

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 pobiera dane o cenach zapośredniczonej reklamy i używa ich do określenia stawki cena:

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 Ad Manager używa zmiennej String w przypadku tego samego zasobu. Za obsługę tego typu konwersji odpowiada twórca map.

Komponenty z obrazem map

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. Skale piksel do dpi również mogą się różnić.

Aby pomóc Ci w zarządzaniu tymi informacjami, pakiet SDK do reklam mobilnych Google udostępnia NativeAd.Image zajęcia. 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:

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:

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 Ad Manager. UnifiedNativeAdMapper klasa zawiera metodę setExtras(), która służy do przekazywania tych zasobów do wydawców. SampleNativeAdMapper korzysta z tego na potrzeby przykładowego pakietu SDK „stopień wspaniałości” zasób:

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

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

AdChoices

Zdarzenie niestandardowe odpowiada za dodanie ikony Informacja za pomocą tagu Metoda setAdChoicesContent() na UnifiedNativeAdMapper. Oto fragment z: SampleNativeAdMapper pokazujący, jak dodać ikonę Informacja:

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

Zdarzenia dotyczące wyświetleń i kliknięć

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. OK to 2 różne metody stosowane przez zdarzenia niestandardowe w zależności od tego, 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 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 obejmuje 2 metody: recordImpression() i handleClick() tam zdarzeń niestandardowych, które można zaimplementować, aby wywoływać odpowiednią metodę w zapośredniczonych obiekt reklamy natywnej:

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

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

Ponieważ SampleNativeAdMapper zawiera odniesienie do kodu natywnego przykładowego pakietu SDK może wywołać odpowiednią metodę tego obiektu, by zgłosić kliknięcie lub wyświetlenie reklamy. 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ą zapośredniczonego pakietu SDK

Niektóre zapośredniczone pakiety SDK mogą preferować samodzielne śledzenie kliknięć i wyświetleń. W w takim przypadku musisz zastąpić domyślne śledzenie kliknięć i wyświetleń przez dwóch poniższych wywołań w konstruktorze UnifiedNativeAdMapper:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, muszą: raportują zdarzenia onAdClicked() i onAdImpression() firmie Google Mobile Pakiet SDK do wyświetlania reklam.

Aby śledzić wyświetlenia i kliknięcia, zapośredniczony pakiet SDK prawdopodobnie potrzebuje dostępu do widoków, aby włączyć śledzenie. Zdarzenie niestandardowe powinno zastąpić makro trackViews() i użyj jej, by przekazać widok reklamy natywnej do zapośredniczonych Pakiet SDK do śledzenia. Przykładowy pakiet SDK z naszego przykładowego projektu dotyczącego zdarzeń niestandardowych (z którego fragment kodu z tego przewodnika) nie stosuje tej metody, ale jeśli tak, kod zdarzenia niestandardowego będzie wyglądał mniej więcej tak:

@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 z kluczem o nazwie zasobu w NativeAdAssetNames. UnifiedNativeAdMapper udostępnia odpowiednią metodę untrackView(), którą zdarzenia niestandardowe mogą zastąpić aby usunąć wszelkie odwołania do widoku danych i usunąć jego powiązanie z reklamą natywną obiektu.

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

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

Ważne jest, aby zdarzenie niestandardowe przekazuje jak najwięcej z tych wywołań zwrotnych by aplikacja otrzymywała te same zdarzenia z Google Pakiet SDK do reklam mobilnych. 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