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
interfaceOdbieranie 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.