Wymagania wstępne
Skonfiguruj zdarzenia niestandardowe.
Wysyłanie żądania reklamy natywnej
Gdy w łańcuchu zapośredniczenia kaskadowego zostanie osiągnięta kreacja z zdarzeniem niestandardowym,
w nazwie klasy podanej podczas tworzenia zdarzenia niestandardowego zostanie wywołana metoda loadNativeAd:adConfiguration:completionHandler:. W tym przypadku,
metoda znajduje się w klasie SampleCustomEvent, która następnie wywołuje
metodę loadNativeAd:adConfiguration:completionHandler: w klasie
SampleCustomEventNative.
Aby wysłać żądanie reklamy natywnej, utwórz lub zmodyfikuj klasę, która implementuje GADMediationAdapter i loadNativeAd:adConfiguration:completionHandler:. Jeśli klasa, która rozszerza GADMediationAdapter, już istnieje, zaimplementuj w niej loadNativeAd:adConfiguration:completionHandler:. Utwórz też nową klasę, aby zaimplementować GADMediationNativeAd.
W naszym przykładzie zdarzenia niestandardowego
SampleCustomEvent implementuje
interfejs GADMediationAdapter, a następnie przekazuje go do
SampleCustomEventNative.
Swift
import GoogleMobileAds class SampleCustomEvent: NSObject, MediationAdapter { fileprivate var nativeAd: SampleCustomEventNativeAd? func loadNativeAd( for adConfiguration: MediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeAdLoadCompletionHandler ) { self.nativeAd = SampleCustomEventNativeAd() self.nativeAd?.loadNativeAd( for: adConfiguration, completionHandler: completionHandler) } }
Objective-C
#import "SampleCustomEvent.h" @implementation SampleCustomEvent SampleCustomEventNativeAd *sampleNativeAd; - (void)loadNativeAdForAdConfiguration: (GADMediationNativeAdConfiguration *)adConfiguration completionHandler: (GADMediationNativeAdLoadCompletionHandler) completionHandler { sampleNative = [[SampleCustomEventNativeAd alloc] init]; [sampleNative loadNativeAdForAdConfiguration:adConfiguration completionHandler:completionHandler]; }
Klasa `SampleCustomEventNative` odpowiada za te zadania:
wczytywanie reklamy natywnej;
implementowanie protokołu
GADMediationNativeAd;otrzymywanie i zgłaszanie wywołań zwrotnych zdarzeń reklamowych do Google Mobile Ads SDK.
Opcjonalny parametr zdefiniowany w interfejsie Ad Managera jest uwzględniany w konfiguracji reklamy.
Dostęp do parametru można uzyskać za pomocą
adConfiguration.credentials.settings[@"parameter"]. Ten parametr jest zwykle identyfikatorem jednostki reklamowej, którego pakiet SDK sieci reklamowej wymaga podczas tworzenia instancji obiektu reklamy.
Swift
class SampleCustomEventNativeAd: NSObject, MediationNativeAd { /// The Sample Ad Network native ad. var nativeAd: SampleNativeAd? /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. var delegate: MediationNativeAdEventDelegate? /// Completion handler called after ad load var completionHandler: GADMediationNativeLoadCompletionHandler? func loadNativeAd( for adConfiguration: MediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeLoadCompletionHandler ) { let adLoader = SampleNativeAdLoader() let sampleRequest = SampleNativeAdRequest() // Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever // returns URLs for images (rather than the images themselves), your adapter // should download image assets on behalf of the publisher. This should be // done after receiving the native ad object from your network's SDK, and // before calling the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest.shouldDownloadImages = true sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any sampleRequest.shouldRequestMultipleImages = false let options = adConfiguration.options for loaderOptions: AdLoaderOptions in options { if let imageOptions = loaderOptions as? NativeAdImageAdLoaderOptions { sampleRequest.shouldRequestMultipleImages = imageOptions.shouldRequestMultipleImages // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading } else if let mediaOptions = loaderOptions as? NativeAdMediaAdLoaderOptions { switch mediaOptions.mediaAspectRatio { case MediaAspectRatio.landscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.landscape case MediaAspectRatio.portrait: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.portrait default: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any } } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. adLoader.delegate = self adLoader.adUnitID = adConfiguration.credentials.settings["parameter"] as? String self.completionHandler = completionHandler adLoader.fetchAd(sampleRequest) } }
Objective-C
#import "SampleCustomEventNativeAd.h" @interface SampleCustomEventNativeAd () <SampleNativeAdDelegate, GADMediationNativeAd> { /// The sample native ad. SampleNativeAd *_nativeAd; /// The completion handler to call when the ad loading succeeds or fails. GADMediationNativeLoadCompletionHandler _loadCompletionHandler; /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. id<GADMediationNativeAdEventDelegate> _adEventDelegate; } @end - (void)loadNativeAdForAdConfiguration: (GADMediationNativeAdConfiguration *)adConfiguration completionHandler:(GADMediationNativeLoadCompletionHandler) completionHandler { __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT; __block GADMediationNativeLoadCompletionHandler originalCompletionHandler = [completionHandler copy]; _loadCompletionHandler = ^id<GADMediationNativeAdEventDelegate>( _Nullable id<GADMediationNativeAd> ad, NSError *_Nullable error) { // Only allow completion handler to be called once. if (atomic_flag_test_and_set(&completionHandlerCalled)) { return nil; } id<GADMediationNativeAdEventDelegate> delegate = nil; if (originalCompletionHandler) { // Call original handler and hold on to its return value. delegate = originalCompletionHandler(ad, error); } // Release reference to handler. Objects retained by the handler will also // be released. originalCompletionHandler = nil; return delegate; }; SampleNativeAdLoader *adLoader = [[SampleNativeAdLoader alloc] init]; SampleNativeAdRequest *sampleRequest = [[SampleNativeAdRequest alloc] init]; // Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever returns // URLs for images (rather than the images themselves), your adapter should // download image assets on behalf of the publisher. This should be done after // receiving the native ad object from your network's SDK, and before calling // the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest.shouldDownloadImages = YES; sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny; sampleRequest.shouldRequestMultipleImages = NO; sampleRequest.testMode = adConfiguration.isTestRequest; for (GADAdLoaderOptions *loaderOptions in adConfiguration.options) { if ([loaderOptions isKindOfClass:[GADNativeAdImageAdLoaderOptions class]]) { GADNativeAdImageAdLoaderOptions *imageOptions = (GADNativeAdImageAdLoaderOptions *)loaderOptions; sampleRequest.shouldRequestMultipleImages = imageOptions.shouldRequestMultipleImages; // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading; } else if ([loaderOptions isKindOfClass:[GADNativeAdMediaAdLoaderOptions class]]) { GADNativeAdMediaAdLoaderOptions *mediaOptions = (GADNativeAdMediaAdLoaderOptions *)loaderOptions; switch (mediaOptions.mediaAspectRatio) { case GADMediaAspectRatioLandscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientationLandscape; break; case GADMediaAspectRatioPortrait: sampleRequest.preferredImageOrientation = NativeAdImageOrientationPortrait; break; default: sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny; break; } } else if ([loaderOptions isKindOfClass:[GADNativeAdViewAdOptions class]]) { _nativeAdViewAdOptions = (GADNativeAdViewAdOptions *)loaderOptions; } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. NSString *adUnit = adConfiguration.credentials.settings[@"parameter"]; adLoader.adUnitID = adUnit; adLoader.delegate = self; [adLoader fetchAd:sampleRequest]; }
Niezależnie od tego, czy reklama zostanie pobrana, czy wystąpi błąd, wywołasz GADMediationNativeAdLoadCompletionHandler. W przypadku powodzenia przekaż klasę, która implementuje GADMediationNativeAd, z wartością nil dla parametru błędu. W przypadku niepowodzenia przekaż napotkany błąd.
Zwykle te metody są implementowane w wywołaniach zwrotnych z pakietu SDK innej firmy, który implementuje Twój adapter. W tym przykładzie pakiet SDK ma klasę SampleNativeAdDelegate z odpowiednimi wywołaniami zwrotnymi:
Swift
func adLoader( _ adLoader: SampleNativeAdLoader, didReceive nativeAd: SampleNativeAd ) { extraAssets = [ SampleCustomEventConstantsSwift.awesomenessKey: nativeAd.degreeOfAwesomeness ?? "" ] if let image = nativeAd.image { images = [NativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [NativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] } if let mappedIcon = nativeAd.icon { icon = NativeAdImage(image: mappedIcon) } else { let iconURL = URL(fileURLWithPath: nativeAd.iconURL) icon = NativeAdImage(url: iconURL, scale: nativeAd.iconScale) } adChoicesView = SampleAdInfoView() self.nativeAd = nativeAd if let handler = completionHandler { delegate = handler(self, nil) } } func adLoader( _ adLoader: SampleNativeAdLoader, didFailToLoadAdWith errorCode: SampleErrorCode ) { let error = SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription( code: SampleCustomEventErrorCodeSwift .SampleCustomEventErrorAdLoadFailureCallback, description: "Sample SDK returned an ad load failure callback with error code: \(errorCode)" ) if let handler = completionHandler { delegate = handler(nil, error) } }
Objective-C
- (void)adLoader:(SampleNativeAdLoader *)adLoader didReceiveNativeAd:(SampleNativeAd *)nativeAd { if (nativeAd.image) { _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ]; } else { NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL]; _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL scale:nativeAd.imageScale] ]; } if (nativeAd.icon) { _icon = [[GADNativeAdImage alloc] initWithImage:nativeAd.icon]; } else { NSURL *iconURL = [[NSURL alloc] initFileURLWithPath:nativeAd.iconURL]; _icon = [[GADNativeAdImage alloc] initWithURL:iconURL scale:nativeAd.iconScale]; } // The sample SDK provides an AdChoices view (SampleAdInfoView). If your SDK // provides image and click through URLs for its AdChoices icon instead of an // actual UIView, the adapter is responsible for downloading the icon image // and creating the AdChoices icon view. _adChoicesView = [[SampleAdInfoView alloc] init]; _nativeAd = nativeAd; _adEventDelegate = _loadCompletionHandler(self, nil); } - (void)adLoader:(SampleNativeAdLoader *)adLoader didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode { NSError *error = SampleCustomEventErrorWithCodeAndDescription( SampleCustomEventErrorAdLoadFailureCallback, [NSString stringWithFormat:@"Sample SDK returned an ad load failure " @"callback with error code: %@", errorCode]); _adEventDelegate = _loadCompletionHandler(nil, error); }
Mapowanie reklam natywnych
Różne pakiety SDK mają własne unikalne formaty reklam natywnych. Jeden może zwracać obiekty zawierające np. pole „title”, a inny – „headline”. Ponadto metody używane do śledzenia wyświetleń i przetwarzania kliknięć mogą się różnić w zależności od pakietu SDK.
Aby rozwiązać te problemy, gdy zdarzenie niestandardowe otrzyma obiekt reklamy natywnej z zapośredniczonego pakietu SDK, powinno użyć klasy, która implementuje GADMediationNativeAd, np. SampleCustomEventNativeAd, aby „mapować” obiekt reklamy natywnej z zapośredniczonego pakietu SDK tak, aby pasował do interfejsu oczekiwanego przez Google Mobile Ads SDK.
Przyjrzyjmy się teraz szczegółom implementacji klasy SampleCustomEventNativeAd.
Przechowywanie mapowań
Oczekuje się, że klasa GADMediationNativeAd będzie implementować określone właściwości, które są mapowane na właściwości innych pakietów SDK:
Swift
var nativeAd: SampleNativeAd? var headline: String? { return nativeAd?.headline } var images: [NativeAdImage]? var body: String? { return nativeAd?.body } var icon: NativeAdImage? var callToAction: String? { return nativeAd?.callToAction } var starRating: NSDecimalNumber? { return nativeAd?.starRating } var store: String? { return nativeAd?.store } var price: String? { return nativeAd?.price } var advertiser: String? { return nativeAd?.advertiser } var extraAssets: [String: Any]? { return [ SampleCustomEventConstantsSwift.awesomenessKey: nativeAd?.degreeOfAwesomeness ?? "" ] } var adChoicesView: UIView? var mediaView: UIView? { return nativeAd?.mediaView }
Objective-C
/// Used to store the ad's images. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the images /// property. NSArray<GADNativeAdImage *> *_images; /// Used to store the ad's icon. In order to implement the GADMediationNativeAd /// protocol, we use this class to return the icon property. GADNativeAdImage *_icon; /// Used to store the ad's ad choices view. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the adChoicesView /// property. UIView *_adChoicesView; - (nullable NSString *)headline { return _nativeAd.headline; } - (nullable NSArray<GADNativeAdImage *> *)images { return _images; } - (nullable NSString *)body { return _nativeAd.body; } - (nullable GADNativeAdImage *)icon { return _icon; } - (nullable NSString *)callToAction { return _nativeAd.callToAction; } - (nullable NSDecimalNumber *)starRating { return _nativeAd.starRating; } - (nullable NSString *)store { return _nativeAd.store; } - (nullable NSString *)price { return _nativeAd.price; } - (nullable NSString *)advertiser { return _nativeAd.advertiser; } - (nullable NSDictionary<NSString *, id> *)extraAssets { return @{SampleCustomEventExtraKeyAwesomeness : _nativeAd.degreeOfAwesomeness}; } - (nullable UIView *)adChoicesView { return _adChoicesView; } - (nullable UIView *)mediaView { return _nativeAd.mediaView; } - (BOOL)hasVideoContent { return self.mediaView != nil; }
Niektóre zapośredniczone sieci mogą udostępniać dodatkowe zasoby poza tymi, które są zdefiniowane przez
Google Mobile Ads SDK. Protokół GADMediationNativeAd zawiera metodę
o nazwie extraAssets, której Google Mobile Ads SDK używa do pobierania tych „dodatkowych” zasobów z mapowania.
Mapowanie komponentów z obrazem
Mapowanie komponentów z obrazem jest bardziej skomplikowane niż mapowanie prostszych typów danych, takich jak NSString czy double. Obrazy mogą być pobierane automatycznie lub zwracane jako wartości URL. Ich gęstość pikseli też może się różnić.
Aby ułatwić zarządzanie tymi szczegółami, Google Mobile Ads SDK udostępnia klasę
GADNativeAdImage. Informacje o komponencie z obrazem (niezależnie od tego, czy są to rzeczywiste UIImage
obiekty, czy tylko wartości NSURL) należy zwracać do Google Mobile Ads SDK
za pomocą tej klasy.
Oto jak klasa mapowania obsługuje tworzenie klasy GADNativeAdImage do przechowywania obrazu ikony:
Swift
if let image = nativeAd.image { images = [NativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [NativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] }
Objective-C
if (nativeAd.image) { _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ]; } else { NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL]; _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL scale:nativeAd.imageScale] ]; }
Zdarzenia wyświetleń i kliknięć
Zarówno Google Mobile Ads SDK jak i zapośredniczony pakiet SDK muszą wiedzieć, kiedy nastąpi wyświetlenie lub kliknięcie, ale tylko jeden z nich musi śledzić te zdarzenia. Zdarzenia niestandardowe mogą korzystać z 2 różnych metod w zależności od tego, czy zapośredniczony pakiet SDK obsługuje śledzenie wyświetleń i kliknięć samodzielnie.
Śledzenie kliknięć i wyświetleń za pomocą Google Mobile Ads SDK
Jeśli zapośredniczony pakiet SDK nie śledzi wyświetleń i kliknięć, ale udostępnia metody rejestrowania kliknięć i wyświetleń, Google Mobile Ads SDK może śledzić te zdarzenia i powiadamiać adapter. Protokół GADMediationNativeAd zawiera 2 metody: didRecordImpression: i didRecordClickOnAssetWithName:view:viewController:, które zdarzenia niestandardowe mogą implementować, aby wywoływać odpowiednią metodę w zapośredniczonym obiekcie reklamy natywnej:
Swift
func didRecordImpression() { nativeAd?.recordImpression() } func didRecordClickOnAsset( withName assetName: GADUnifiedNativeAssetIdentifier, view: UIView, wController: UIViewController ) { nativeAd?.handleClick(on: view) }
Objective-C
- (void)didRecordImpression { if (self.nativeAd) { [self.nativeAd recordImpression]; } } - (void)didRecordClickOnAssetWithName:(GADUnifiedNativeAssetIdentifier)assetName view:(UIView *)view viewController:(UIViewController *)viewController { if (self.nativeAd) { [self.nativeAd handleClickOnView:view]; } }
Ponieważ klasa, która implementuje protokół GADMediationNativeAd, zawiera odniesienie do obiektu reklamy natywnej z pakietu SDK Sample, może wywołać odpowiednią metodę w tym obiekcie, aby zgłosić kliknięcie lub wyświetlenie. Pamiętaj, że metoda didRecordClickOnAssetWithName:view:viewController: przyjmuje tylko 1 parametr: obiekt View odpowiadający komponentowi reklamy natywnej, który został kliknięty.
Ś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 takim przypadku zaimplementuj metody handlesUserClicks i handlesUserImpressions zgodnie z fragmentem kodu poniżej. Zwracając wartość
YES, wskazujesz, że zdarzenie niestandardowe przejmuje odpowiedzialność za śledzenie
tych zdarzeń i będzie powiadamiać Google Mobile Ads SDK gdy te zdarzenia wystąpią.
Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, mogą używać komunikatu didRenderInView:, aby przekazywać widok reklamy natywnej do obiektu reklamy natywnej z zapośredniczonego pakietu SDK, co umożliwi zapośredniczonemu pakietowi SDK przeprowadzenie rzeczywistego śledzenia. Przykładowy pakiet SDK z naszego projektu zdarzenia niestandardowego (z którego pochodzą fragmenty kodu w tym przewodniku) nie korzysta z tej metody, ale jeśli tak by było, kod zdarzenia niestandardowego wywołałby metodę setNativeAdView:view: zgodnie z fragmentem kodu poniżej:
Swift
func handlesUserClicks() -> Bool { return true } func handlesUserImpressions() -> Bool { return true } func didRender( in view: UIView, clickableAssetViews: [GADNativeAssetIdentifier: UIView], nonclickableAssetViews: [GADNativeAssetIdentifier: UIView], viewController: UIViewController ) { // This method is called when the native ad view is rendered. Here you would pass the UIView // back to the mediated network's SDK. self.nativeAd?.setNativeAdView(view) }
Objective-C
- (BOOL)handlesUserClicks { return YES; } - (BOOL)handlesUserImpressions { return YES; } - (void)didRenderInView:(UIView *)view clickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *) clickableAssetViews nonclickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *) nonclickableAssetViews viewController:(UIViewController *)viewController { // This method is called when the native ad view is rendered. Here you would // pass the UIView back to the mediated network's SDK. Playing video using // SampleNativeAd's playVideo method [_nativeAd setNativeAdView:view]; }
Przekazywanie zdarzeń zapośredniczenia do Google Mobile Ads SDK
Gdy wywołasz
GADMediationNativeLoadCompletionHandler
z wczytaną reklamą, zwrócony obiekt delegata
może być używany przez adapter do przekazywania zdarzeń prezentacji z
pakietu SDK innej firmy do Google Mobile Ads SDK.GADMediationNativeAdEventDelegate
Ważne jest, aby zdarzenie niestandardowe przekazywało jak najwięcej tych wywołań zwrotnych, jak to możliwe, aby aplikacja otrzymywała te same zdarzenia z Google Mobile Ads SDK. Oto przykład użycia wywołań zwrotnych:
W ten sposób kończy się implementacja zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny w GitHub.