Điều kiện tiên quyết
Hoàn tất việc thiết lập sự kiện tuỳ chỉnh.
Yêu cầu quảng cáo gốc
Khi mục hàng sự kiện tuỳ chỉnh được tiếp cận trong chuỗi dàn xếp kiểu thác nước,
phương thức loadNativeAd:adConfiguration:completionHandler:
được gọi trên
tên lớp mà bạn đã cung cấp khi tạo một lớp tuỳ chỉnh
sự kiện. Trong trường hợp này,
phương thức đó nằm trong SampleCustomEvent
, sau đó phương thức này sẽ gọi
phương thức loadNativeAd:adConfiguration:completionHandler:
trong
SampleCustomEventNative
.
Để yêu cầu hiển thị một quảng cáo gốc, hãy tạo hoặc sửa đổi một lớp triển khai GADMediationAdapter
và loadNativeAd:adConfiguration:completionHandler:
. Nếu
đã tồn tại một lớp mở rộng GADMediationAdapter
, hãy triển khai
loadNativeAd:adConfiguration:completionHandler:
ở đó. Ngoài ra, hãy tạo một
lớp mới để triển khai GADMediationNativeAd
.
Trong ví dụ về sự kiện tùy chỉnh,
SampleCustomEvent
lượt triển khai
giao diện GADMediationAdapter
, sau đó uỷ quyền cho
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` chịu trách nhiệm thực hiện các tác vụ sau:
Tải quảng cáo gốc
Triển khai giao thức
GADMediationNativeAd
.Nhận và báo cáo lệnh gọi lại sự kiện quảng cáo cho SDK Quảng cáo của Google trên thiết bị di động
Thông số không bắt buộc được xác định trong giao diện người dùng Ad Manager là
được bao gồm trong cấu hình quảng cáo.
Bạn có thể truy cập thông số này thông qua
adConfiguration.credentials.settings[@"parameter"]
. Thông số này là
thường là giá trị nhận dạng đơn vị quảng cáo mà SDK mạng quảng cáo yêu cầu khi
tạo thực thể của một đối tượng quảng cáo.
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]; }
Cho dù quảng cáo được tìm nạp thành công hay gặp lỗi, bạn
sẽ gọi GADMediationNativeAdLoadCompletionHandler
. Nếu thành công,
truyền qua lớp triển khai GADMediationNativeAd
bằng giá trị nil
cho tham số lỗi; trong trường hợp không thành công, hãy chuyển lỗi mà bạn gặp phải
gặp phải.
Thông thường, các phương thức này được triển khai bên trong lệnh gọi lại từ
SDK của bên thứ ba mà bộ chuyển đổi của bạn triển khai. Trong ví dụ này, SDK mẫu có một SampleNativeAdDelegate
với các lệnh gọi lại phù hợp:
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); }
Liên kết quảng cáo gốc
Các SDK khác nhau có các định dạng riêng cho quảng cáo gốc. Khách hàng có thể quay lại đối tượng chứa "tiêu đề" trong khi một trường khác có thể có "dòng tiêu đề". Ngoài ra, các phương thức dùng để theo dõi lượt hiển thị và xử lý lượt nhấp có thể khác nhau giữa các SDK.
Để giải quyết những vấn đề này, khi một sự kiện tuỳ chỉnh nhận được đối tượng quảng cáo gốc từ
SDK đã dàn xếp của mình, thì SDK đó sẽ sử dụng một lớp triển khai GADMediationNativeAd
,
như SampleCustomEventNativeAd
cho "bản đồ" đối tượng quảng cáo gốc của SDK đã dàn xếp
để khớp với giao diện mà SDK quảng cáo trên thiết bị di động của Google dự kiến.
Giờ đây, chúng ta sẽ xem xét kỹ hơn chi tiết triển khai cho
SampleCustomEventNativeAd
.
Lưu trữ các liên kết
GADMediationNativeAd
được dự kiến sẽ triển khai một số thuộc tính
được liên kết từ các thuộc tính của SDK khác:
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; }
Một số mạng đã dàn xếp có thể cung cấp thêm tài sản ngoài những tài sản do
SDK quảng cáo trên thiết bị di động của Google. Giao thức GADMediationNativeAd
bao gồm một phương thức
có tên là extraAssets
mà SDK quảng cáo trên thiết bị di động của Google sử dụng để truy xuất bất kỳ
những "thông tin bổ sung" này khỏi trình liên kết.
Liên kết thành phần hình ảnh
Việc liên kết thành phần hình ảnh phức tạp hơn so với việc liên kết dữ liệu đơn giản hơn
như NSString
hoặc double
. Hình ảnh có thể được tải xuống tự động hoặc
được trả về dưới dạng giá trị URL. Mật độ pixel cũng có thể thay đổi.
Để giúp bạn quản lý các thông tin chi tiết này, SDK quảng cáo trên thiết bị di động của Google cung cấp
Lớp GADNativeAdImage
. Thông tin về thành phần hình ảnh (có phải là UIImage
thực tế hay không
hoặc chỉ có giá trị NSURL
) phải được trả về SDK quảng cáo trên thiết bị di động của Google
khi sử dụng lớp này.
Dưới đây là cách lớp trình liên kết xử lý việc tạo GADNativeAdImage
để giữ
hình ảnh biểu tượng:
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] ]; }
Sự kiện nhấp chuột và hiển thị
Cả SDK quảng cáo trên thiết bị di động của Google và SDK đã dàn xếp đều cần phải biết khi nào nhưng chỉ cần một SDK theo dõi các sự kiện này. Có mà sự kiện tùy chỉnh có thể sử dụng là hai phương pháp khác nhau, tùy thuộc vào việc SDK đã dàn xếp hỗ trợ tự theo dõi lượt hiển thị và lượt nhấp.
Theo dõi lượt nhấp và lượt hiển thị bằng SDK quảng cáo trên thiết bị di động của Google
Nếu SDK đã dàn xếp không tự theo dõi lượt hiển thị và lượt nhấp nhưng
cung cấp các phương pháp để ghi lại lượt nhấp và lượt hiển thị, SDK quảng cáo trên thiết bị di động của Google có thể
theo dõi những sự kiện này và thông báo cho bộ chuyển đổi. Giao thức GADMediationNativeAd
bao gồm 2 phương thức: didRecordImpression:
và
didRecordClickOnAssetWithName:view:viewController:
mà sự kiện tuỳ chỉnh có thể
triển khai để gọi phương thức tương ứng trên đối tượng quảng cáo gốc đã dàn xếp:
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]; } }
Bởi vì lớp triển khai GADMediationNativeAd
có tham chiếu đến đối tượng quảng cáo gốc của SDK mẫu, nó có thể gọi phương thức
phương pháp thích hợp trên đối tượng đó để báo cáo một lượt nhấp hoặc lượt hiển thị. Lưu ý rằng
Phương thức didRecordClickOnAssetWithName:view:viewController:
lấy một giá trị duy nhất
thông số: đối tượng View
tương ứng với thành phần quảng cáo gốc đã nhận
lượt nhấp.
Theo dõi lượt nhấp và lượt hiển thị bằng SDK đã dàn xếp
Một số SDK đã dàn xếp có thể muốn tự theo dõi lượt nhấp và lượt hiển thị. Ngang bằng
trong trường hợp đó, bạn nên triển khai handlesUserClicks
và
handlesUserImpressions
như minh hoạ trong đoạn mã dưới đây. Người trả lại
YES
, bạn cho biết rằng sự kiện tuỳ chỉnh chịu trách nhiệm theo dõi
những sự kiện này và sẽ thông báo cho SDK quảng cáo trên thiết bị di động của Google khi những sự kiện này xảy ra.
Các sự kiện tuỳ chỉnh ghi đè hoạt động theo dõi lượt nhấp và lượt hiển thị có thể sử dụng phương thức
didRenderInView:
thông báo để chuyển chế độ xem của quảng cáo gốc sang SDK đã dàn xếp
đối tượng quảng cáo gốc để cho phép SDK đã dàn xếp thực hiện theo dõi thực tế. Mẫu
SDK từ dự án mẫu sự kiện tùy chỉnh của chúng tôi (từ đó các đoạn mã của hướng dẫn này
đã được sử dụng) không sử dụng phương pháp này nhưng nếu có, mã sự kiện tùy chỉnh
sẽ gọi phương thức setNativeAdView:view:
như minh hoạ trong đoạn mã dưới đây:
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]; }
Chuyển tiếp các sự kiện dàn xếp đến SDK Quảng cáo của Google trên thiết bị di động
Sau khi bạn gọi điện
GADMediationNativeLoadCompletionHandler
với một quảng cáo đã tải, uỷ quyền GADMediationNativeAdEventDelegate
được trả về
sau đó đối tượng có thể được bộ chuyển đổi sử dụng để chuyển tiếp các sự kiện trình bày từ
SDK bên thứ ba sang SDK quảng cáo trên thiết bị di động của Google.
Sự kiện tuỳ chỉnh của bạn cần chuyển tiếp nhiều lệnh gọi lại trong số này nhất có thể có thể, để ứng dụng của bạn nhận được các sự kiện tương đương này từ SDK quảng cáo trên thiết bị di động. Dưới đây là ví dụ về cách sử dụng lệnh gọi lại:
Đến đây, bạn đã hoàn tất việc triển khai sự kiện tuỳ chỉnh cho quảng cáo gốc. Ví dụ đầy đủ có trên GitHub.