Wymagania wstępne
Dokończ konfigurowanie zdarzeń niestandardowych.
Żądanie reklamy natywnej
Gdy w łańcuchu zapośredniczenia kaskadowego osiągniesz element linii kodu reklamowego zdarzenia niestandardowego, metoda loadNativeAd:adConfiguration:completionHandler:
zostanie wywołana w nazwie klasy podanej podczas tworzenia zdarzenia niestandardowego. W tym przypadku metoda znajduje się w klasie SampleCustomEvent
, która wywołuje metodę loadNativeAd:adConfiguration:completionHandler:
w klasie SampleCustomEventNative
.
Aby poprosić o reklamę natywną, utwórz lub zmodyfikuj klasę, która implementuje interfejsy GADMediationAdapter
i loadNativeAd:adConfiguration:completionHandler:
. Jeśli klasa rozszerzająca klasę GADMediationAdapter
już istnieje, zaimplementuj w niej funkcję loadNativeAd:adConfiguration:completionHandler:
. Dodatkowo utwórz nowe zajęcia, aby zaimplementować GADMediationNativeAd
.
W naszym przykładzie zdarzenia niestandardowego funkcja SampleCustomEvent
implementuje interfejs GADMediationAdapter
, a potem przekazuje sterowanie do funkcji SampleCustomEventNative
.
Swift
import GoogleMobileAds class SampleCustomEvent: NSObject, GADMediationAdapter { fileprivate var nativeAd: SampleCustomEventNativeAd? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, 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]; }
SampleCustomEventNative odpowiada za te czynności:
Wczytywanie reklamy natywnej
Zaimplementuj protokół
GADMediationNativeAd
.Odbieranie i zgłaszanie wywołań zwrotnych zdarzeń reklamy do pakietu SDK do reklam mobilnych Google
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 to zwykle identyfikator jednostki reklamowej, którego pakiet SDK sieci reklamowej wymaga do utworzenia obiektu reklamy.
Swift
class SampleCustomEventNativeAd: NSObject, GADMediationNativeAd { /// 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: GADMediationNativeAdEventDelegate? /// Completion handler called after ad load var completionHandler: GADMediationNativeLoadCompletionHandler? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeLoadCompletionHandler ) { let adLoader = SampleNativeAdLoader() let sampleRequest = SampleNativeAdRequest() // The 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: GADAdLoaderOptions in options { if let imageOptions = loaderOptions as? GADNativeAdImageAdLoaderOptions { 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? GADNativeAdMediaAdLoaderOptions { switch mediaOptions.mediaAspectRatio { case GADMediaAspectRatio.landscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.landscape case GADMediaAspectRatio.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]; // The 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]; }
Bez względu na to, czy pobieranie reklamy się powiedzie, czy wystąpi błąd, wywołasz funkcję GADMediationNativeAdLoadCompletionHandler
. W przypadku powodzenia prześlij klasę implementującą GADMediationNativeAd
z wartością nil
dla parametru błędu. W przypadku niepowodzenia prześlij wygenerowany błąd.
Zwykle te metody są implementowane w ramach wywołań zwrotnych z zewnętrznego pakietu SDK, który jest używany przez adapter. W tym przykładzie pakiet SDK Sample ma element 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 = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] } if let mappedIcon = nativeAd.icon { icon = GADNativeAdImage(image: mappedIcon) } else { let iconURL = URL(fileURLWithPath: nativeAd.iconURL) icon = GADNativeAdImage(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); }
Reklamy natywne na mapach
Różne pakiety SDK mają własne formaty reklam natywnych. Jeden z nich może zwracać obiekty zawierające pole „title”, a drugi – pole „headline”. Dodatkowo metody ś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 pakietu SDK z pośrednictwem, powinno użyć klasy, która implementuje interfejs GADMediationNativeAd
, np. SampleCustomEventNativeAd
, aby „zmapować” obiekt reklamy natywnej z pakietu SDK z pośrednictwem, tak aby pasował do interfejsu wymaganego przez pakiet SDK do reklam mobilnych Google.
Przyjrzyjmy się teraz szczegółom implementacji w przypadku SampleCustomEventNativeAd
.
Przechowywanie mapowań
GADMediationNativeAd
powinien implementować określone właściwości mapowane z innych pakietów SDK:
Swift
var nativeAd: SampleNativeAd? var headline: String? { return nativeAd?.headline } var images: [GADNativeAdImage]? var body: String? { return nativeAd?.body } var icon: GADNativeAdImage? 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 sieci pośredniczące mogą udostępniać dodatkowe komponenty poza tymi zdefiniowanymi przez pakiet SDK do reklam mobilnych Google. Protokół GADMediationNativeAd
zawiera metodę extraAssets
, której pakiet SDK do reklam mobilnych Google używa do pobierania z mappera dowolnych „dodatkowych” zasobów.
Komponenty z obrazem mapy
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 adresów URL. Różnicować się może też gęstość pikseli.
Aby ułatwić zarządzanie tymi informacjami, pakiet SDK do reklam mobilnych Google udostępnia klasę GADNativeAdImage
. Informacje o komponencie z obrazem (czy są to obiekty UIImage
czy tylko wartości NSURL
) powinny zostać zwrócone do pakietu SDK do reklam mobilnych Google za pomocą tej klasy.
Oto jak klasa mapper tworzy obiekt GADNativeAdImage
, aby przechowywać obraz ikony:
Swift
if let image = nativeAd.image { images = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(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świetlenia i kliknięcia
Zarówno pakiet SDK do reklam mobilnych Google, jak i pakiet SDK pośredniczący muszą wiedzieć, kiedy wystąpiło wyświetlenie lub kliknięcie, ale tylko 1 pakiet SDK musi śledzić te zdarzenia. 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 śledzi wyświetleń ani 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. Protokół GADMediationNativeAd
zawiera 2 metody: didRecordImpression:
i didRecordClickOnAssetWithName:view:viewController:
, które zdarzenia niestandardowe mogą implementować, aby wywołać odpowiednią metodę w pośredniczonym obiekcie natywnej reklamy:
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 implementująca protokół GADMediationNativeAd
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 didRecordClickOnAssetWithName:view:viewController:
przyjmuje 1 parametry: obiekt View
odpowiadający natywnemu komponentowi reklamy, który otrzymał 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 takim przypadku należy zaimplementować metody handlesUserClicks
i handlesUserImpressions
, jak pokazano w fragmentie kodu poniżej. Zwracając wartośćYES
, wskazujesz, że zdarzenie niestandardowe przejmuje odpowiedzialność za śledzenie tych zdarzeń i będzie powiadamiać pakiet SDK do reklam mobilnych Google o ich wystąpieniu.
Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, mogą używać wiadomości didRenderInView:
, aby przekazać widok reklamy natywnej do obiektu reklamy natywnej w pakiecie SDK zapośredniczenia. Pozwoli to pakietowi SDK zapośredniczenia przeprowadzić rzeczywiste śledzenie. Przykładowy pakiet SDK z naszego przykładowego projektu 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 wywołałby metodę setNativeAdView:view:
, jak pokazano w tym fragmencie kodu:
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 pakietu SDK do reklam mobilnych Google
Po wywołaniu metody GADMediationNativeLoadCompletionHandler
z załadowaną reklamą adapter może użyć zwróconego obiektu GADMediationNativeAdEventDelegate
, aby przekazywać zdarzenia prezentacji z zewnętrznego pakietu SDK do pakietu SDK do reklam mobilnych Google.
Ważne jest, aby zdarzenie niestandardowe przekazywało jak najwięcej wywołań zwrotnych, aby aplikacja otrzymywała zdarzenia o takim samym znaczeniu z pakietu SDK do reklam mobilnych Google. Oto przykład użycia wywołań zwrotnych:
To kończy implementację zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny na GitHub.