Zdarzenia niestandardowe reklam natywnych

Wymagania wstępne

Dokończ konfigurację zdarzeń niestandardowych.

Wysyłanie żądania reklamy natywnej

Gdy w łańcuchu mediacji kaskadowej zostanie osiągnięty element zamówienia zdarzenia niestandardowego, w przypadku nazwy klasy podanej podczas tworzenia zdarzenia niestandardowego zostanie wywołana metoda loadNativeAd(). W tym przypadku metoda znajduje się w SampleCustomEvent, która następnie wywołuje metodę loadNativeAd() w SampleNativeCustomEventLoader.

Aby poprosić o reklamę natywną, utwórz lub zmodyfikuj klasę, która rozszerza Adapter, aby zaimplementować loadNativeAd(). Jeśli klasa rozszerzająca Adapter już istnieje, zaimplementuj w niej loadNativeAd(). Utwórz też nową klasę, aby zaimplementować UnifiedNativeAdMapper.

W naszym przykładzie zdarzenia niestandardowego klasa SampleCustomEvent rozszerza klasę Adapter, a następnie przekazuje wywołanie do klasy 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.

  • Implementowanie klasy UnifiedNativeAdMapper.

  • Otrzymywanie i zgłaszanie wywołań zwrotnych zdarzeń związanych z reklamami do pakietu SDK do reklam mobilnych Google.

Parametr opcjonalny zdefiniowany w interfejsie AdMob jest uwzględniany w konfiguracji reklamy. Dostęp do parametru można uzyskać za pomocą funkcji 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 funkcję onSuccess() lub onFailure(). onSuccess() jest wywoływana przez przekazanie instancji klasy, która implementuje MediationNativeAd.

Zazwyczaj te metody są wdrażane w wywołaniach zwrotnych z pakietu SDK firmy zewnętrznej, który implementuje Twój adapter. W tym przykładzie pakiet SDK zawiera 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));
}

Reklamy natywne w Mapach

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

UnifiedNativeAdMapper odpowiada za wyrównanie tych różnic i dostosowanie obiektu reklamy natywnej pakietu SDK do mediacji do interfejsu oczekiwanego przez pakiet SDK do reklam mobilnych Google. Zdarzenia niestandardowe powinny rozszerzać tę klasę, aby tworzyć własne mapowania dostosowane do ich SDK do mediacji. Oto przykładowy moduł mapowania 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.
  }
}

Przyjrzyjmy się teraz bliżej kodowi konstruktora.

Zachowaj odwołanie do obiektu reklamy natywnej z zapośredniczeniem

Konstruktor akceptuje parametr SampleNativeAd, czyli klasę reklam natywnych używaną przez przykładowy pakiet SDK w przypadku reklam natywnych. Moduł mapujący potrzebuje odniesienia do reklamy wyświetlanej przez zapośredniczoną sieć reklamową, aby mógł przekazywać zdarzenia kliknięcia i wyświetlenia. SampleNativeAd jest przechowywana jako zmienna lokalna.

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

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

Ten fragment kodu pobiera dane o cenie reklamy wyświetlanej w ramach zapośredniczenia i używa ich do ustawienia ceny w funkcji mapującej:

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 double, a AdMob używa String w przypadku tego samego komponentu. Za obsługę tych typów konwersji odpowiada mapowanie.

Komponenty z obrazem mapy

Mapowanie zasobów graficznych jest bardziej skomplikowane niż mapowanie typów danych, takich jak double czy String. Obrazy mogą być pobierane automatycznie lub zwracane jako wartości URL. Skala pikseli do DPI może się różnić.

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 w celu mapowania natywnej reklamy z mediacją, podczas mapowania komponentów obrazu należy utworzyć podklasę 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;
  }
}

W tym wierszu funkcja SampleNativeAdMapper używa zamapowanej klasy obrazu, aby ustawić komponent obrazu ikony narzędzia do mapowania:

Java

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

Dodawanie pól do pakietu dodatków

Niektóre pakiety SDK do mediacji udostępniają dodatkowe komponenty poza tymi, które są dostępne w formacie reklamy natywnej AdMob. Klasa UnifiedNativeAdMapper zawiera metodę setExtras(), która służy do przekazywania tych komponentów wydawcom. SampleNativeAdMapper używa tego w przypadku zasobu „stopień niesamowitości” w przykładowym pakiecie SDK:

Java

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

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

AdChoices

Za wyświetlanie ikony Informacja za pomocą metody setAdChoicesContent() w obiekcie UnifiedNativeAdMapper odpowiada zdarzenie niestandardowe. Oto fragment kodu SampleNativeAdMapper pokazujący, jak podać ikonę informacji:

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 SDK do zapośredniczonych reklam muszą wiedzieć, kiedy następuje wyświetlenie lub kliknięcie, ale tylko jeden z nich musi śledzić te zdarzenia. Zdarzenia niestandardowe mogą korzystać z 2 różnych podejść w zależności od tego, czy SDK do mediacji obsługuje samodzielne ś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 śledzi wyświetleń i kliknięć, ale udostępnia metody rejestrowania kliknięć i wyświetleń, pakiet SDK do reklam mobilnych Google 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 wyświetlanej przez zapośredniczenie:

Java

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

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

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

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

Niektóre SDK do mediacji mogą samodzielnie śledzić kliknięcia i wyświetlenia. W takim przypadku musisz zastąpić domyślne śledzenie kliknięć i wyświetleń, wykonując w konstruktorze elementu UnifiedNativeAdMapper te 2 wywołania:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

Aby śledzić wyświetlenia i kliknięcia, pakiet SDK do mediacji prawdopodobnie potrzebuje dostępu do widoków, aby włączyć śledzenie. Zdarzenie niestandardowe powinno zastąpić metodę trackViews() i użyć jej do przekazania widoku reklamy natywnej do pakietu SDK do mediacji w celu śledzenia. Przykładowy pakiet SDK z naszego projektu z przykładem zdarzenia niestandardowego (z którego pochodzą fragmenty kodu w tym przewodniku) nie korzysta z tego podejścia, ale gdyby 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 SDK do mediacji obsługuje śledzenie poszczególnych komponentów, może sprawdzić w clickableAssetViews, które widoki powinny być klikalne. Kluczem w tej mapie jest nazwa komponentu w NativeAdAssetNames. Klasa UnifiedNativeAdMapperoferuje odpowiednią metodę untrackView(), którą zdarzenia niestandardowe mogą zastąpić, aby zwolnić wszystkie odwołania do widoku i odłączyć go od obiektu reklamy natywnej.

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

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

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

W ten sposób zakończysz wdrażanie zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny w GitHub.