Sự kiện tùy chỉnh gốc

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ượng NativeMediationAdRequest 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ủa MediationAdRequest, 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ột Bundle 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ức addNetworkExtrasBundle() để 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ượng Context 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ượng CustomEventNativeListener 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ột UnifiedNativeAdMapper để 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ạo UnifiedNativeAdMapper.

• 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:

  • ERROR_CODE_INTERNAL_ERROR
  • ERROR_CODE_INVALID_REQUEST
  • ERROR_CODE_NETWORK_ERROR
  • ERROR_CODE_NO_FILL

• 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ọi onAdOpened ngay trước khi gọi onAdLeftApplication.

• 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.