Điều kiện tiên quyết
Hoàn tất quy trình thiết lập sự kiện tuỳ chỉnh.
Yêu cầu hiển thị quảng cáo gốc
Khi đạt đến mục hàng sự kiện tuỳ chỉnh trong chuỗi dàn xếp kiểu thác nước, phương thức loadNativeAd()
sẽ được gọi theo tên lớp mà bạn đã cung cấp khi tạo một sự kiện tuỳ chỉnh. Trong trường hợp này, phương thức đó nằm trong SampleCustomEvent
, sau đó gọi phương thức loadNativeAd()
trong SampleNativeCustomEventLoader
.
Để 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 mở rộng Adapter
để triển khai loadNativeAd()
. Nếu đã có một lớp mở rộng Adapter
, hãy triển khai loadNativeAd()
ở đó. Ngoài ra, hãy tạo một lớp mới để triển khai UnifiedNativeAdMapper
.
Trong ví dụ về sự kiện tuỳ chỉnh, SampleCustomEvent
mở rộng lớp Adapter
rồi uỷ quyền cho 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
chịu trách nhiệm thực hiện những việc sau:
Đang tải quảng cáo gốc.
Triển khai lớp
UnifiedNativeAdMapper
.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 trên thiết bị di động của Google.
Thông số không bắt buộc được xác định trong giao diện người dùng AdMob sẽ được đưa vào cấu hình quảng cáo. Bạn có thể truy cập vào thông số này qua adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD)
.
Thông số này thường là giá trị nhận dạng đơn vị quảng cáo mà SDK mạng quảng cáo cần có khi tạo bản sao cho một đối tượng quảng cáo.
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); } }
Tuỳ thuộc vào việc quảng cáo được tìm nạp thành công hay gặp lỗi, bạn sẽ gọi onSuccess()
hoặc onFailure()
.
onSuccess()
được gọi bằng cách truyền vào một thực thể của lớp triển khai MediationNativeAd
.
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 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 SampleAdListener
với các lệnh gọi lại phù hợp:
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)); }
Liên kết quảng cáo gốc
Các SDK khác nhau đều có định dạng riêng cho quảng cáo gốc. Ví dụ: một SDK có thể trả về các đối tượng chứa trường "tiêu đề" trong khi một SDK khác có thể có trường "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.
UnifiedNativeAdMapper
chịu trách nhiệm điều chỉnh những sự khác biệt này và điều chỉnh đối tượng quảng cáo gốc của SDK đã dàn xếp cho phù hợp với giao diện mà SDK quảng cáo trên thiết bị di động của Google yêu cầu. Các sự kiện tuỳ chỉnh nên mở rộng lớp này để tạo các trình liên kết riêng cho SDK đã dàn xếp của các sự kiện đó. Dưới đây là một trình liên kết quảng cáo mẫu từ dự án sự kiện tuỳ chỉnh mẫu của chúng tôi:
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. } }
Bây giờ, chúng ta sẽ xem xét kỹ hơn mã hàm khởi tạo.
Duy trì mục tham chiếu đến đối tượng quảng cáo gốc đã dàn xếp
Hàm khởi tạo chấp nhận tham số SampleNativeAd
, lớp quảng cáo gốc mà SDK mẫu sử dụng cho quảng cáo gốc. Trình liên kết cần tham chiếu đến quảng cáo đã dàn xếp để có thể chuyển sự kiện lượt nhấp và lượt hiển thị. SampleNativeAd
được lưu trữ dưới dạng biến cục bộ.
Đặt thuộc tính tài sản được liên kết
Hàm khởi tạo sử dụng đối tượng SampleNativeAd
để điền nội dung vào các thành phần trong UnifiedNativeAdMapper
.
Đoạn mã này lấy dữ liệu về giá của quảng cáo đã dàn xếp và sử dụng dữ liệu đó để đặt giá cho trình liên kết:
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
Trong ví dụ này, quảng cáo đã dàn xếp lưu trữ giá dưới dạng double
, trong khi AdMob sử dụng String
cho cùng một thành phần. Trình liên kết chịu trách nhiệm xử lý các loại lượt chuyển đổi này.
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 các loại dữ liệu như double
hoặc String
. Hình ảnh có thể được tải xuống tự động hoặc được trả về dưới dạng giá trị URL. Tỷ lệ pixel:dpi của hình ảnh 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 NativeAd.Image
. Tương tự như việc tạo lớp con của UnifiedNativeAdMapper
để liên kết đến quảng cáo gốc đã dàn xếp, bạn cũng nên tạo một lớp con của NativeAd.Image
khi liên kết các thành phần hình ảnh.
Dưới đây là ví dụ về lớp SampleNativeMappedImage
của sự kiện tuỳ chỉnh:
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
sử dụng lớp hình ảnh đã liên kết trong dòng này để đặt tài sản hình ảnh biểu tượng của trình liên kết:
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
Thêm trường vào Gói bổ sung
Một số SDK trung gian cung cấp thêm thành phần ngoài những thành phần trong định dạng quảng cáo gốc AdMob. Lớp UnifiedNativeAdMapper
bao gồm phương thức setExtras()
dùng để chuyển các thành phần này đến nhà xuất bản. SampleNativeAdMapper
sử dụng phương thức này cho tài sản "mức độ tuyệt vời" của SDK mẫu:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
Nhà xuất bản có thể truy xuất dữ liệu này bằng cách sử dụng phương thức getExtras()
của lớp NativeAd
.
Lựa chọn quảng cáo
Sự kiện tuỳ chỉnh chịu trách nhiệm cung cấp biểu tượng Lựa chọn quảng cáo bằng cách sử dụng phương thức setAdChoicesContent()
trên UnifiedNativeAdMapper
. Dưới đây là đoạn mã từ SampleNativeAdMapper
cho biết cách cung cấp biểu tượng Lựa chọn quảng cáo:
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
Sự kiện lượt hiển thị và sự kiện nhấp chuột
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 thời điểm xảy ra lượt hiển thị hoặc lượt nhấp, nhưng chỉ cần một SDK theo dõi các sự kiện này. Các sự kiện tuỳ chỉnh có thể sử dụng 2 phương pháp tiếp cận khác nhau, tuỳ thuộc vào việc SDK đã dàn xếp có hỗ trợ tính năng theo dõi lượt hiển thị và lượt nhấp hay không.
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 theo dõi lượt hiển thị và lượt nhấp nhưng có cung cấp các phương thức để ghi lại lượt nhấp và lượt hiển thị, thì SDK quảng cáo trên thiết bị di động của Google có thể theo dõi các sự kiện này và thông báo cho bộ chuyển đổi. Lớp UnifiedNativeAdMapper
bao gồm 2 phương thức: recordImpression()
và handleClick()
. Các sự kiện tuỳ chỉnh có thể triển khai 2 phương thức này để gọi phương thức tương ứng trên đối tượng quảng cáo gốc đã dàn xếp:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
Do tham chiếu đến đối tượng quảng cáo gốc của SDK mẫu, nên SampleNativeAdMapper
có thể gọi phương thức 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ị. Xin lưu ý rằng phương thức handleClick()
sẽ nhận một thông số duy nhất: đối tượng View
tương ứng với thành phần quảng cáo gốc đã nhận được 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ị. Trong trường hợp đó, bạn nên ghi đè thông tin theo dõi lượt nhấp và lượt hiển thị mặc định bằng cách thực hiện hai lệnh gọi sau trong hàm dựng của UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
Bạn cần có 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ị để báo cáo các sự kiện onAdClicked()
và onAdImpression()
cho SDK quảng cáo trên thiết bị di động của Google.
Để theo dõi lượt hiển thị và lượt nhấp, SDK đã dàn xếp có thể cần quyền truy cập vào các chế độ xem để bật tính năng theo dõi. Sự kiện tuỳ chỉnh phải ghi đè phương thức trackViews()
và sử dụng phương thức này để truyền chế độ xem của quảng cáo gốc đến SDK đã dàn xếp để theo dõi. SDK mẫu từ dự án mẫu sự kiện tuỳ chỉnh của chúng tôi (dự án chứa đoạn mã trong hướng dẫn này) không sử dụng phương pháp này; nhưng nếu có, mã sự kiện tuỳ chỉnh sẽ có dạng như sau:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
Nếu SDK đã dàn xếp hỗ trợ việc theo dõi từng thành phần, thì SDK này có thể tìm bên trong clickableAssetViews
để biết chế độ xem nào nên cho phép nhấp vào. Phần quan trọng trong quá trình liên kết này là tên thành phần trong NativeAdAssetNames
. UnifiedNativeAdMapper
cung cấp phương thức untrackView()
tương ứng mà các sự kiện tuỳ chỉnh có thể ghi đè để huỷ mọi mục tham chiếu đến chế độ xem và tách chế độ xem đó khỏi đối tượng quảng cáo gốc.
Chuyển tiếp sự kiện dàn xếp đến SDK quảng cáo trên thiết bị di động của Google
Bạn có thể tìm thấy tất cả lệnh gọi lại mà tính năng dàn xếp hỗ trợ trong tài liệu về MediationNativeAdCallback
.
Điều quan trọng là sự kiện tuỳ chỉnh của bạn phải chuyển tiếp càng nhiều lệnh gọi lại này càng tốt để ứng dụng của bạn có thể 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 của Google. 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. Bạn có thể xem toàn bộ ví dụ trên GitHub.