Tài liệu hướng dẫn này dành cho các nhà xuất bản muốn sử dụng tính năng Dàn xếp AdMob để tải và hiển thị quảng cáo gốc trên một mạng không nằm trong danh sách các mạng quảng cáo được hỗ trợ của AdMob. (Bạn có thể xem Sự kiện tùy chỉnh để biết cách sử dụng tính năng Dàn xếp AdMob để tải và hiển thị quảng cáo biểu ngữ hoặc quảng cáo xen kẽ.) Sự kiện tùy chỉnh là các lớp có chứa bộ chuyển đổi dàn xếp có khả năng yêu cầu quảng cáo từ một mạng khác. Khi bạn thêm tên của một trong các lớp này vào tùy chọn cài đặt dàn xếp cho một đơn vị quảng cáo, SDK quảng cáo trên thiết bị di động của Google có thể tạo bản sao và sử dụng bản sao đó để truy xuất quảng cáo. Các lớp sự kiện gốc tùy chỉnh phải có khả năng thực hiện những việc sau:
- Yêu cầu quảng cáo gốc từ mạng đã dàn xếp.
- Chuyển tiếp các sự kiện từ SDK của mạng đã dàn xếp đến SDK quảng cáo trên thiết bị di động của Google.
- Sử dụng
UnifiedNativeAdMapper
để liên kết các quảng cáo gốc đã dàn xếp tới giao diện quảng cáo gốc của AdMob.
Bạn có thể tham khảo thông tin về mỗi việc kể trên ở bên dưới. Bạn cũng có thể tìm thấy toàn bộ nguồn cho một dự án sự kiện tùy chỉnh mẫu trong kho lưu trữ GitHub.
Điều kiện tiên quyết
Để triển khai sự kiện tùy chỉnh AdMob, trước tiên bạn phải
tích hợp SDK quảng cáo trên thiết bị di động
vào dự án Trước hết, bạn nên đọc hướng dẫn về cách
tạo AdRequest
và cách hoạt động của tính năng dàn xếp.
SDK mẫu
Đoạn mã trong tài liệu hướng dẫn này được lấy từ dự án sự kiện tùy chỉnh mẫu có chứa một "SDK mẫu". Trong ví dụ này, chúng tôi sử dụng SDK mô phỏng này để minh họa cách tạo một sự kiện tùy chỉnh để dàn xếp SDK của một mạng quảng cáo khác.
SDK mẫu này có các lớp tương tự như các lớp trong SDK sản xuất
của mạng quảng cáo. Trong đó có các đối tượng yêu cầu (chẳng hạn như SampleNativeAdRequest
),
trình tải quảng cáo (chẳng hạn như SampleNativeAdLoader
), cũng như các lớp, hằng số và giao diện
khác dùng để mô phỏng SDK của một mạng thực. Tuy nhiên,
quảng cáo mà SDK này tạo ra chỉ là quảng cáo mô phỏng và không tạo ra thêm lưu lượng truy cập mạng.
Yêu cầu quảng cáo gốc
Phương thức requestNativeAd()
Các lớp sự kiện tùy chỉnh phải triển khai giao diện
CustomEventNative
.
Giao diện này bao gồm một phương thức mà SDK quảng cáo trên thiết bị di động của Google sử dụng để yêu cầu quảng cáo gốc từ
sự kiện tùy chỉnh:
Java
void requestNativeAd(Context context, CustomEventNativeListener listener, String serverParameter, NativeMediationAdRequest mediationAdRequest, Bundle customEventExtras);
Kotlin
override fun requestNativeAd(context: Context, listener: CustomEventNativeListener, serverParameter: String, mediationAdRequest: NativeMediationAdRequest, customEventExtras: Bundle?)
Khi phương thức này được gọi, sự kiện tùy chỉnh sẽ thực hiện một yêu cầu không đồng bộ
đối với quảng cáo gốc từ mạng đã dàn xếp. Các thông số sau
của requestNativeAd()
có chứa thông tin mà sự kiện tùy chỉnh đó có thể sử dụng
khi đưa ra yêu cầu:
serverParameter
– Khi thêm một sự kiện tùy chỉnh vào cấu hình dàn xếp của một đơn vị quảng cáo, nhà xuất bản có thể nhập một giá trị chuỗi sẽ được chuyển kèm theo mỗi yêu cầu. Thông số này sẽ bao gồm giá trị đó (thường là một mã đơn vị quảng cáo khác, do một mạng đã dàn xếp tạo ra).mediationAdRequest
– Một đối tượngNativeMediationAdRequest
chứa các thuộc tính dành cho một yêu cầu (chẳng hạn như các định dạng quảng cáo gốc được yêu cầu).NativeMediationAdRequest
là một lớp con củaMediationAdRequest
, vì vậy, lớp này cũng bao gồm các thuộc tính dành cho thông tin nhắm mục tiêu khác mà nhà xuất bản cung cấp tại thời điểm yêu cầu.customEventExtras
– MộtBundle
chứa mọi thông tin bổ sung có liên quan đến yêu cầu do nhà xuất bản cung cấp. Khi tạo yêu cầu quảng cáo, nhà xuất bản có thể sử dụng phương thứcaddNetworkExtrasBundle()
để bao gồm thông tin cho các bộ chuyển đổi dàn xếp và các sự kiện tùy chỉnh cụ thể. Bạn có thể tìm thấy mọi phần phụ mà nhà xuất bản thêm vào một lớp sự kiện tùy chỉnh nhất định trong thông số này.
Ngoài các thông số chứa thông tin về yêu cầu, bạn có thể thấy 2 thông số khác:
context
– Một đối tượngContext
có thể được sử dụng nếu sự kiện tùy chỉnh yêu cầu đối tượng đó.listener
– Một đối tượngCustomEventNativeListener
mà sự kiện tùy chỉnh sẽ sử dụng để chuyển tiếp các sự kiện.
Đối tượng trình nghe này có vai trò đặc biệt quan trọng khi được dùng để báo cáo các sự kiện cho SDK quảng cáo trên thiết bị di động của Google. Hướng dẫn này trình bày cách báo cáo các sự kiện đó trong bài viết Chuyển tiếp sự kiện đến SDK quảng cáo trên thiết bị di động.
Dưới đây là đoạn mã lấy từ dự án sự kiện tùy chỉnh
mẫu của chúng tôi.
Đoạn mã này cho biết một phương thức requestNativeAd()
mà chúng tôi đã triển khai:
SampleCustomEvent (phần trích dẫn)
Java
@Override public void requestNativeAd(Context context, CustomEventNativeListener customEventNativeListener, String serverParameter, NativeMediationAdRequest nativeMediationAdRequest, Bundle extras) { // Create one of the Sample SDK's ad loaders from which to request ads. SampleNativeAdLoader loader = new SampleNativeAdLoader(context); loader.setAdUnit(serverParameter); // Create a native request to give to the SampleNativeAdLoader. SampleNativeAdRequest request = new SampleNativeAdRequest(); NativeAdOptions options = nativeMediationAdRequest.getNativeAdOptions(); if (options != null) { // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should // send just the URLs for the images. request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets()); // If your network does not support any of the following options, please make sure // that it is documented in your adapter's documentation. request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages()); switch (options.getImageOrientation()) { case NativeAdOptions.ORIENTATION_LANDSCAPE: request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE); break; case NativeAdOptions.ORIENTATION_PORTRAIT: request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT); break; case NativeAdOptions.ORIENTATION_ANY: default: request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_ANY); } } if (!nativeMediationAdRequest.isUnifiedNativeAdRequested()) { Log.e(TAG, "Failed to load ad. Request must be for unified native ads."); customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST); return; } loader.setNativeAdListener( new SampleCustomNativeEventForwarder(customEventNativeListener, options)); // Begin a request. loader.fetchAd(request); }
Kotlin
override fun requestNativeAd(context: Context, customEventNativeListener: CustomEventNativeListener, serverParameter: String, nativeMediationAdRequest: NativeMediationAdRequest, extras: Bundle) { // Create one of the Sample SDK's ad loaders from which to request ads. val loader = SampleNativeAdLoader(context) loader.setAdUnit(serverParameter) // Create a native request to give to the SampleNativeAdLoader. val request = SampleNativeAdRequest() val options = nativeMediationAdRequest.nativeAdOptions if (options != null) { // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should // send just the URLs for the images. request.shouldDownloadImages = !options.shouldReturnUrlsForImageAssets() // If your network does not support any of the following options, please make sure // that it is documented in your adapter's documentation. request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages()) when (options.imageOrientation) { NativeAdOptions.ORIENTATION_LANDSCAPE -> request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE) NativeAdOptions.ORIENTATION_PORTRAIT -> request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT) NativeAdOptions.ORIENTATION_ANY -> request.setPreferredImageOrientation( SampleNativeAdRequest.IMAGE_ORIENTATION_ANY) else -> request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY) } } if (!nativeMediationAdRequest.isUnifiedNativeAdRequested) { Log.e(TAG, "Failed to load ad. Request must be for unified native ads.") customEventNativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST) return } loader.setNativeAdListener( SampleCustomNativeEventForwarder(customEventNativeListener, options)) // Begin a request. loader.fetchAd(request) }
Đây là một sự kiện tùy chỉnh mẫu thực hiện việc dàn xếp với một mạng quảng cáo ảo
thông qua SDK mẫu mô phỏng. Sự kiện tùy chỉnh này sử dụng thông tin có
trong các thông số của requestNativeAd()
để tạo SampleNativeAdRequest
(một lớp do SDK mẫu cung cấp), sau đó sử dụng lớp này để yêu cầu một quảng cáo
từ SampleNativeAdLoader
của SDK mẫu. Sự kiện này cũng tạo một
SampleCustomEventNativeForwarder
để xử lý việc chuyển tiếp các sự kiện trở về
SDK quảng cáo trên thiết bị di động của Google.
NativeAdOptions
Khi đưa ra yêu cầu cho quảng cáo gốc, nhà xuất bản sử dụng đối tượng NativeAdOptions
để chỉ định các tùy chọn của họ cho yêu cầu đó, chẳng hạn như cách mà hệ thống trả về tài sản
hình ảnh. Sự kiện tùy chỉnh cần xem xét và tuân thủ
các tùy chọn đó. Các sự kiện tùy chỉnh có thể truy xuất
đối tượng NativeAdOptions
của một yêu cầu bằng
phương thức getNativeAdOptions()
mà đối tượng NativeMediationAdRequest
cung cấp:
Java
NativeAdOptions options = mediationAdRequest.getNativeAdOptions();
Kotlin
val options = mediationAdRequest.nativeAdOptions
Sau khi truy xuất NativeAdOptions
, các sự kiện tùy chỉnh có thể đọc
thuộc tính của đối tượng đó và thực hiện hành động tương ứng. Ví dụ: nếu giá trị
shouldReturnUrlsForImageAssets
là false trong NativeAdOptions
(giá trị mặc định), sự kiện tùy chỉnh phải trả về tài sản
hình ảnh thực tế thay vì chỉ trả về các URL. Trong trường hợp này, nếu SDK được
dàn xếp chỉ cung cấp URL cho hình ảnh, thì sự kiện tùy chỉnh phải
sử dụng các URL đó để tải tệp hình ảnh xuống và cung cấp dữ liệu của tệp hình ảnh
cho nhà xuất bản trong quảng cáo gốc được liên kết.
Chuyển tiếp sự kiện đến SDK quảng cáo trên thiết bị di động
Một số trường hợp có thể xảy ra khi sự kiện tùy chỉnh cố tải quảng cáo gốc
từ mạng đã dàn xếp, . SDK có thể trả về thành công một quảng cáo gốc,
SDK có thể trả về một quảng cáo bị lỗi hoặc có thể chỉ báo cáo rằng
hiện không thể trả về quảng cáo. Tương tự, khi người dùng nhấn vào một quảng cáo,
SDK đã dàn xếp có thể mở một lớp phủ hoặc hoàn toàn rời khỏi ứng dụng để bắt đầu
một trình duyệt bên ngoài. Điều quan trọng là SDK quảng cáo trên thiết bị di động của Google
phải nhận biết được các sự kiện này, vì vậy SDK này cung cấp một đối tượng CustomEventNativeListener
dưới dạng thông số cho phương thức requestNativeAd()
.
Một vai trò của sự kiện tùy chỉnh là xử lý các sự kiện từ SDK đã dàn xếp
và liên kết các sự kiện đó với các lệnh gọi lại CustomEventNativeListener
thích hợp.
Sự kiện tùy chỉnh của bạn cần nhận biết được các lệnh gọi lại
CustomEventNativeListener
sau đây:
onAdLoaded()
— Phương thức này sẽ được gọi khi sự kiện tùy chỉnh tải thành công một quảng cáo gốc. Phương thức này cần phải có mộtUnifiedNativeAdMapper
để liên kết quảng cáo gốc của SDK mạng quảng cáo với một đối tượng mà SDK quảng cáo trên thiết bị di động của Google hiểu được. Bài viết về Liên kết quảng cáo gốc trình bày cách tạoUnifiedNativeAdMapper
.onAdFailedToLoad()
– Khi đã cố gắng mà vẫn không thể tải quảng cáo gốc, thì sự kiện tùy chỉnh sẽ sử dụng phương thức này để báo cáo lỗi. Sự kiện này sẽ lấy một thông số là số nguyên. Bạn nên đặt thông số này thành một trong các hằng số lỗi sau:onAdLeftApplication()
– Gọi phương thức này khi SDK đã dàn xếp khiến người dùng rời khỏi ứng dụng của nhà xuất bản (thường là để mở một trình duyệt bên ngoài).onAdOpened()
– Nếu quảng cáo gốc mở bất kỳ lớp phủ hoặc hoạt động riêng biệt nào che phủ giao diện để phản hồi hành động nhấn của người dùng, thì phương thức này sẽ được gọi. Điều này bao gồm việc mở một trình duyệt bên ngoài. Trong trường hợp đó, sự kiện tùy chỉnh của bạn nên gọionAdOpened
ngay trước khi gọionAdLeftApplication
.onAdClosed()
– Nếu lớp phủ hoặc hoạt động riêng biệt che phủ giao diện bị đóng, thì phương thức này sẽ được gọi, biểu thị rằng hệ thống đang chuyển lại quyền kiểm soát cho ứng dụng chứa quảng cáo gốc.
Trình nghe này cũng cung cấp các phương thức để báo cáo các lượt nhấp và lượt hiển thị từ các sự kiện tùy chỉnh. Các sự kiện này chọn theo dõi các lượt nhấp hoặc lượt hiển thị cho chính các sự kiện đó (hãy tham khảo bài viết Ghi đè bản ghi lượt hiển thị và xử lý lượt nhấp mặc định để biết thông tin chi tiết). Một phương thức dùng để báo cáo lượt nhấp cho SDK quảng cáo trên thiết bị di động của Google và một phương thức dùng để báo cáo lượt hiển thị:
onAdClicked()
– Phương thức này sẽ được gọi khi người dùng nhấp vào quảng cáo gốc.onAdImpression()
– Tương tự, phương thức này sẽ được gọi khi một lượt hiển thị được SDK đã dàn xếp ghi lại cho quảng cáo.
Bạn có thể thực hiện một số cách để đảm bảo các sự kiện được chuyển tiếp chính xác, nhưng một trong những cách đơn giản nhất là tạo một lớp riêng hoạt động như trình chuyển tiếp. Dưới đây là một ví dụ từ dự án mẫu sự kiện tùy chỉnh của chúng tôi:
SampleCustomNativeEventForwarder
Java
public class SampleCustomNativeEventForwarder extends SampleNativeAdListener { private CustomEventNativeListener nativeListener; private NativeAdOptions nativeAdOptions; public SampleCustomNativeEventForwarder( CustomEventNativeListener listener, NativeAdOptions options) { this.nativeListener = listener; this.nativeAdOptions = options; } @Override public void onNativeAdFetched(SampleNativeAd ad) { SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad, nativeAdOptions); nativeListener.onAdLoaded(mapper); } @Override public void onAdFetchFailed(SampleErrorCode errorCode) { switch (errorCode) { case UNKNOWN: nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR); break; case BAD_REQUEST: nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST); break; case NETWORK_ERROR: nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR); break; case NO_INVENTORY: nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL); break; } } }
Kotlin
class SampleCustomNativeEventForwarder( private val nativeListener: CustomEventNativeListener, private val nativeAdOptions: NativeAdOptions) : SampleNativeAdListener() { fun onNativeAdFetched(ad: SampleNativeAd) { val mapper = SampleUnifiedNativeAdMapper(ad, nativeAdOptions) nativeListener.onAdLoaded(mapper) } fun onAdFetchFailed(errorCode: SampleErrorCode) { when (errorCode) { UNKNOWN -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INTERNAL_ERROR) BAD_REQUEST -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_INVALID_REQUEST) NETWORK_ERROR -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NETWORK_ERROR) NO_INVENTORY -> nativeListener.onAdFailedToLoad(AdRequest.ERROR_CODE_NO_FILL) } } }
Xin lưu ý rằng lớp này sẽ triển khai giao diện SampleNativeAdListener
của SDK mẫu.
Trong SampleCustomEvent (phần trích dẫn),
một bản sao của lớp trình chuyển tiếp này đã được cấp cho SampleNativeAdLoader
trong phương thức setNativeAdListener()
của lớp đó:
Java
loader.setNativeAdListener(new SampleCustomNativeEventForwarder(customEventNativeListener, options));
Kotlin
loader.setNativeAdListener(SampleCustomNativeEventForwarder(customEventNativeListener, options))
Điều này đảm bảo rằng SDK mẫu sẽ gọi các phương thức trình nghe
(onNativeAdFetched()
, onAdFetchFailed()
và các phương thức khác) của đối tượng SampleCustomNativeEventForwarder
khi SDK đó có một sự kiện cần báo cáo. Sau đó, trình chuyển tiếp
sẽ gọi phương thức thích hợp trên CustomEventNativeListener
của SDK quảng cáo trên thiết bị di động của Google để chuyển tiếp sự kiện. Tóm lại,
SDK quảng cáo trên thiết bị di động của Google nghe theo trình chuyển tiếp, còn trình chuyển tiếp nghe theo
SDK đã dàn xếp.
Phương thức onAdFetchFailed()
ở trên là một ví dụ hay về cách hoạt động của
SDK. Khi không tải được quảng cáo, SDK mẫu sẽ gọi
phương thức onAdFetchFailed()
của trình chuyển tiếp và cấp cho phương thức đó một mã lỗi. Trình chuyển tiếp
sẽ kiểm tra mã lỗi và gọi phương thức onAdFailedToLoad()
của CustomEventNativeListener
kèm theo một trong các mã lỗi mà
SDK quảng cáo trên thiết bị di động của Google sử dụng. Bằng cách này, sự kiện SDK mẫu sẽ được chuyển thành
sự kiện SDK quảng cáo trên thiết bị di động của Google.
Liên kết quảng cáo gốc
Nhiều SDK có cá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. Vai trò của
UnifiedNativeAdMapper
là giảm thiểu 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 tùy 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 tùy chỉnh mẫu của chúng tôi:
SampleUnifiedNativeAdMapper
Java
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); } }
Kotlin
class SampleUnifiedNativeAdMapper(private val sampleAd: SampleNativeAd) : UnifiedNativeAdMapper() { init { headline = sampleAd.headline body = sampleAd.body callToAction = sampleAd.callToAction starRating = sampleAd.starRating store = sampleAd.storeName icon = SampleNativeMappedImage(sampleAd.icon, sampleAd.iconUri, SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE) advertiser = sampleAd.advertiser val imagesList = ArrayList<NativeAd.Image>() imagesList.add(SampleNativeMappedImage(sampleAd.image, sampleAd.imageUri, SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)) images = imagesList if (sampleAd.price != null) { val formatter = NumberFormat.getCurrencyInstance() val priceString = formatter.format(sampleAd.price) price = priceString } val extras = Bundle() extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness) this.extras = extras overrideClickHandling = false overrideImpressionRecording = false adChoicesContent = sampleAd.informationIcon } override fun recordImpression() { sampleAd.recordImpression() } override fun handleClick(view: View?) { sampleAd.handleClick(view) } }
Hãy cùng xem phương thức hàm tạo và một số công việc mà phương thức này đang thực hiện:
Duy trì mục tham chiếu đến đối tượng quảng cáo gốc đã dàn xếp
Hàm dựng chấp nhận các thông số SampleNativeAd
và NativeAdOptions
.
SampleNativeAd
là 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ị.
NativeAdOptions
chứa tùy chọn của nhà xuất bản về quảng cáo gốc. Cả hai
thông số đều đượ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 dựng sử dụng đối tượng SampleNativeAd
để điền tài sản vào
UnifiedNativeAdMapper
. Ví dụ: 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); }
Kotlin
if (sampleAd.price != null) { val formatter = NumberFormat.getCurrencyInstance() val priceString = formatter.format(sampleAd.price) price = priceString }
Trong trường hợp 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 tài sả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 tài sản hình ảnh
Việc liên kết các tài sản hình ảnh phức tạp hơn so với các loại dữ liệu đơn giản (như
double
hoặc String
). Hình ảnh có thể được tải xuống tự động hoặc chỉ
đượ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
nhà phát triển sự kiện tùy chỉnh quản lý các thông tin 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ư cách mà nhà phát triển sử dụng để
tạo một lớp con của UnifiedNativeAdMapper
để liên kết quảng cáo gốc đã dàn xếp,
nhà phát triển cũng nên tạo một lớp con của NativeAd.Image
để liên kết
các tài sản hình ảnh của quảng cáo đó.
Dưới đây là mã cho lớp SampleNativeMappedImage
của sự kiện tùy 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; } }
Kotlin
class SampleNativeMappedImage(private val drawable: Drawable, private val imageUri: Uri, private val scale: Double) : NativeAd.Image() { override fun getDrawable(): Drawable { return drawable } override fun getUri(): Uri { return imageUri } override fun getScale(): Double { return scale } }
SampleUnifiedNativeAdMapper
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));
Kotlin
icon = SampleNativeMappedImage(sampleAd.appIcon, sampleAd.appIconUri, SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)
Thêm các trường khác vào Gói phần phụ
Một số SDK đã dàn xếp có thể cung cấp thêm tài sản khác ngoài những tài sản trong
định dạng quảng cáo gốc AdMob. Lớp
UnifiedNativeAdMapper
bao gồm phương thức
setExtras()
.
Đây là phương thức dùng để chuyển các tài sản này đến cho nhà xuất bản. SampleUnifiedNativeAdMapper
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);
Kotlin
val extras = Bundle() extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, sampleAd.degreeOfAwesomeness) this.extras = extras
Các 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 UnifiedNativeAd
.
Lựa chọn quảng cáo
Sự kiện tùy 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 thông qua
phương thức setAdChoicesContent()
trên UnifiedNativeAdMapper
.
Đây là đoạn mã từ SampleUnifiedNativeAdMapper
,
cho biết cách cung cấp biểu tượng Lựa chọn quảng cáo:
Java
public SampleUnifiedNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
Kotlin
init { ... adChoicesContent = sampleAd.informationIcon }
Sự kiện lượt nhấp và lượt 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 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 tùy chỉnh có thể sử dụng 2 phương pháp tiếp cận khác nhau, tùy 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.
Xử lý các lượt nhấp và lượt hiển thị bằng handleClick và recordImpression
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 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. UnifiedNativeAdMapper
bao gồm 2 phương thức là recordImpression()
và handleClick()
. Các sự kiện tùy chỉnh có thể triển khai các 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.
Dưới đây là cách SampleUnifiedNativeAdMapper
xử lý vấn đề này:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
Kotlin
override fun recordImpression() { sampleAd.recordImpression() } override fun 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 SampleUnifiedNativeAdMapper
chỉ cần 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()
chỉ có một thông số duy nhất. Thông số này là đối tượng
View
tương ứng với tài sản quảng cáo gốc đã nhận được lượt nhấp.
Ghi đè bản ghi lượt hiển thị và hoạt động xử lý lượt nhấp mặc định
Một số SDK đã dàn xếp có thể muốn tự theo dõi số 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);
Kotlin
setOverrideClickHandling(true) setOverrideImpressionRecording(true)
Như đã nêu trong bài viết Chuyển tiếp sự kiện đến
SDK quảng cáo trên thiết bị di động,
bạn cần có các sự kiện tùy chỉnh tự theo dõi lượt nhấp và lượt hiển thị
để báo cáo các sự kiện này cho SDK quảng cáo trên thiết bị di động của Google thông qua các phương thức
onAdClicked()
và
onAdImpression()
.)
Bạn cũng nên ghi đè phương thức trackViews()
và sử dụng phương thức này để
chuyển chế độ xem của quảng cáo gốc sang SDK đã dàn xếp để theo dõi.
SDK mẫu từ dự án mẫu sự kiện tùy 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 tùy chỉnh sẽ trông như sau:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
Kotlin
override fun trackViews(containerView: View?, clickableAssetViews: Map<String, View>?, nonClickableAssetViews: Map<String, View>?) { sampleAd.setNativeAdViewForTracking(containerView) }
Nếu SDK đã dàn xếp hỗ trợ tính năng theo dõi các tài sản riêng lẻ, thì SDK này có thể tìm bên trong
clickableAssetViews
để xem 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 tài sản trong
UnifiedNativeAdAssetNames
.
UnifiedNativeAdMapper
cung cấp phương thức
untrackView()
tương ứng mà các sự kiện tùy chỉnh có thể ghi đè cho mục đích ngược lại (hủy
mọi mục tham chiếu đến chế độ xem và tách phương thức này khỏi đối tượng quảng cáo gốc).
Sử dụng sự kiện tùy chỉnh
Để sử dụng sự kiện tùy chỉnh, bạn cần phải thêm sự kiện đó vào cấu hình dàn xếp cho một đơn vị quảng cáo. Bạn có thể thực hiện việc này trong Giao diện người dùng AdMob. (Hãy đọc bài viết hướng dẫn chi tiết về cách Tạo sự kiện tùy chỉnh để biết cách chỉnh sửa cấu hình dàn xếp của một đơn vị quảng cáo).
Khi thêm sự kiện tùy chỉnh này vào cấu hình dàn xếp của một đơn vị quảng cáo, bạn sẽ phải cung cấp 3 thông tin sau:
Class Name
– Đây là tên lớp của sự kiện tùy chỉnh đã bao gồm tên gói đầy đủ.Label
– Đây là nhãn mà bạn muốn giao diện của AdMob sử dụng để đại diện cho sự kiện tùy chỉnh khi sự kiện này hiển thị các nguồn dàn xếp của đơn vị quảng cáo. Chỉ bạn mới có thể sử dụng nhãn này vì nhãn chỉ xuất hiện trên giao diện người dùng AdMob.Parameter
– Đây là giá trị chuỗi được chuyển đến sự kiện tùy chỉnh bất cứ khi nào bạn tạo các yêu cầu cho đơn vị quảng cáo này. Thông thường, giá trị này được đặt thành mã đơn vị quảng cáo từ mạng đã dàn xếp.
Dưới đây là ảnh chụp màn hình về một mục sự kiện tùy chỉnh mẫu:

Vậy là xong! Bây giờ, bạn đã có mọi thông tin cần thiết để tạo sự kiện tùy chỉnh Android riêng cho AdMob.