Đ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()
được gọi trên tên lớp mà bạn đã cung cấp khi
tạo một nhóm quảng cáo 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()
trong SampleNativeCustomEventLoader
.
Để yêu cầu một quảng cáo gốc, hãy tạo hoặc sửa đổi lớp mở rộng Adapter
thành
triển khai loadNativeAd()
. Nếu đã tồn tại một lớp mở rộng Adapter
,
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
, sau đó 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 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.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
yêu cầu khi tạo thực thể 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 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 SampleAdListener
với các lệnh gọi lại có liên quan:
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 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 pháp được dùng để theo dõi số lượt hiển thị và xử lý số 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 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. Sự kiện tuỳ chỉnh nên mở rộng lớp này để tạo
người lập bản đồ của riêng họ dành riêng cho SDK đã dàn xếp của họ. Dưới đây là trình liên kết quảng cáo mẫu từ
dự án sự kiện tùy chỉnh mẫu:
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ẽ tìm hiểu kỹ hơn về mã hàm khởi tạo.
Giữ 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 được sử dụng
bởi SDK mẫu cho quảng cáo gốc. Người lập bản đồ cần tham chiếu đến
quảng cáo dàn xếp để có thể chuyển sự kiện nhấp chuột và hiển thị. SampleNativeAd
là
được lưu trữ dưới dạng biến cục bộ.
Đặt các thuộc tính thành phần được liên kết
Hàm khởi tạo sử dụng đối tượng SampleNativeAd
để điền thành phần vào
UnifiedNativeAdMapper
.
Đoạn mã này nhận dữ liệu về giá của quảng cáo đã dàn xếp và sử dụng dữ liệu đó để đặt giá:
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
Ad Manager sử dụng String
cho cùng một tài sản. Chiến lược phát hành đĩa đơn
trình liên kết chịu trách nhiệm xử lý các loại 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, chẳng hạn 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 đến 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
. Theo cách tương tự như việc bạn cần tạo một lớp con
UnifiedNativeAdMapper
để liên kết một 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 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 để thiết lập giá trị
thành phầ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 phần phụ
Một số SDK đã dàn xếp cung cấp thêm tài sản ngoài những tài sản trong
Định dạng quảng cáo gốc Ad Manager. UnifiedNativeAdMapper
bao gồm phương thức setExtras()
dùng để chuyển các nội dung này đến
các nhà xuất bản. SampleNativeAdMapper
sử dụng phương thức này cho SDK mẫu
"mức độ tuyệt vời" thành phần:
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 bằng cách sử dụng lớp NativeAd
getExtras()
.
Lựa chọn quảng cáo
Sự kiện tuỳ chỉnh của bạn 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
. Đây là một đoạn trích từ
SampleNativeAdMapper
cho thấy 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 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. Chiến lược phát hành đĩa đơn
Lớp UnifiedNativeAdMapper
bao gồm 2 phương thức:
recordImpression()
và handleClick()
rằng
mà các sự kiện tùy chỉnh có thể triển khai để gọi phương thức tương ứng trên trang chủ
đối tượng quảng cáo gốc:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
Vì SampleNativeAdMapper
tham chiếu đến SDK gốc của SDK mẫu
đối tượng quảng cáo, Google Ads 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ị. Lưu ý rằng phương thức handleClick()
sẽ lấy một giá trị
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 nhấp chuột.
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 ghi đè theo dõi lần nhấp và lần hiển thị mặc định bằng cách
thực hiện hai lệnh gọi sau trong hàm khởi tạo của
UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
Bạn bắt buộc phải 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 Google Mobile
SDK quảng cáo.
Để 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
chế độ xem để bật tính năng theo dõi. Sự kiện tuỳ chỉnh sẽ ghi đè
trackViews()
và sử dụng phương thức đó để chuyển chế độ xem của quảng cáo gốc đến trình dàn xếp
SDK cần theo dõi. SDK mẫu từ dự án mẫu sự kiện tuỳ chỉnh của chúng tôi (từ đó
đ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
đúng như vậy, 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ợ theo dõi từng thành phần, thì SDK này có thể tìm bên trong
clickableAssetViews
để xem chế độ xem nào có thể nhấp được. Bản đồ này
có khoá là tên nội dung trong NativeAdAssetNames
. UnifiedNativeAdMapper
cung cấp một phương thức untrackView()
tương ứng mà các sự kiện tuỳ chỉnh có thể ghi đè
để giải phóng mọi tham chiếu đến chế độ xem và tách chế độ xem đó khỏi quảng cáo gốc
.
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
Bạn có thể tìm thấy tất cả cá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
.
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 thành 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.