Quảng cáo gốc nâng cao

Hiển thị UnifiedNativeAd

Khi một quảng cáo gốc tải, SDK quảng cáo trên thiết bị di động của Google sẽ gọi trình nghe để có định dạng quảng cáo tương ứng. Sau đó, ứng dụng sẽ chịu trách nhiệm hiển thị quảng cáo, mặc dù ứng dụng không nhất thiết phải làm việc đó ngay lập tức. Để giúp hiển thị các định dạng quảng cáo do hệ thống xác định dễ dàng hơn, SDK sẽ cung cấp một số tài nguyên hữu ích như mô tả dưới đây.

Lớp UnifiedNativeAdView

Định dạng UnifiedNativeAd sẽ có lớp UnifiedNativeAdView tương ứng. Lớp này là một ViewGroup mà nhà xuất bản nên sử dụng làm lớp gốc cho UnifiedNativeAd. Một UnifiedNativeAdView sẽ tương ứng với một quảng cáo gốc hợp nhất. Mỗi chế độ xem dùng để hiển thị tài sản của quảng cáo đó (ví dụ: ImageView hiển thị tài sản ảnh chụp màn hình) phải là đối tượng con của đối tượng UnifiedNativeAdView .

Thứ bậc chế độ xem cho một quảng cáo gốc hợp nhất sử dụng LinearLayout để hiển thị lượt xem tài sản của quảng cáo có thể có dạng như sau:

<com.google.android.gms.ads.formats.UnifiedNativeAdView
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">
        <LinearLayout
        android:orientation="vertical"
        ... >
            <LinearLayout
            android:orientation="horizontal"
            ... >
              <ImageView
               android:id="@+id/ad_app_icon"
               ... />
              <TextView
                android:id="@+id/ad_headline"
                ... />
             </LinearLayout>

             // Other assets such as image or media view, call to action, etc follow.
             ...
        </LinearLayout>
    </com.google.android.gms.ads.formats.UnifiedNativeAdView>
    

Dưới đây là ví dụ về việc tạo UnifiedNativeAdView và điền chế độ xem đó bằng UnifiedNativeAd:

Java

    AdLoader.Builder builder = new AdLoader.Builder(this, "<your ad unit ID>")
        .forUnifiedNativeAd(new UnifiedNativeAd.OnUnifiedNativeAdLoadedListener() {
            @Override
            public void onUnifiedNativeAdLoaded(UnifiedNativeAd unifiedNativeAd) {
                // Assumes you have a placeholder FrameLayout in your View layout
                // (with id fl_adplaceholder) where the ad is to be placed.
                FrameLayout frameLayout =
                    findViewById(R.id.fl_adplaceholder);
                // Assumes that your ad layout is in a file call ad_unified.xml
                // in the res/layout folder
                UnifiedNativeAdView adView = (UnifiedNativeAdView) getLayoutInflater()
                    .inflate(R.layout.ad_unified, null);
                // This method sets the text, images and the native ad, etc into the ad
                // view.
                populateUnifiedNativeAdView(unifiedNativeAd, adView);
                frameLayout.removeAllViews();
                frameLayout.addView(adView);
            }
    });
    

Kotlin

    val builder = AdLoader.Builder(this, "<your ad unit ID>")
        .forUnifiedNativeAd { unifiedNativeAd ->
            // Assumes that your ad layout is in a file call ad_unified.xml
            // in the res/layout folder
            val adView = layoutInflater
                    .inflate(R.layout.ad_unified, null) as UnifiedNativeAdView
            // This method sets the text, images and the native ad, etc into the ad
            // view.
            populateUnifiedNativeAdView(unifiedNativeAd, adView)
            // Assumes you have a placeholder FrameLayout in your View layout
            // (with id ad_frame) where the ad is to be placed.
            ad_frame.removeAllViews()
            ad_frame.addView(adView)
        }
    

Các lớp chế độ xem quảng cáo cũng cung cấp phương thức giúp đăng ký chế độ xem được sử dụng cho từng tài sản riêng lẻ và một phương thức để đăng ký chính đối tượng NativeAd. Việc đăng ký các chế độ xem theo cách này cho phép SDK tự động xử lý các công việc, chẳng hạn như:

  • Ghi lại các lượt nhấp
  • Ghi lại các lượt hiển thị (khi pixel đầu tiên hiển thị trên màn hình)
  • Hiển thị lớp phủ Lựa chọn quảng cáo

Lớp phủ Lựa chọn quảng cáo

SDK sẽ thêm lớp phủ Lựa chọn quảng cáo vào mỗi chế độ xem quảng cáo. Hãy để trống một khoảng ở góc bạn muốn đặt chế độ xem quảng cáo gốc để hệ thống tự động chèn biểu trưng Lựa chọn quảng cáo. Ngoài ra, bạn phải đảm bảo rằng người dùng dễ dàng nhìn thấy lớp phủ Lựa chọn quảng cáo, vì vậy, hãy chọn màu nền và hình ảnh phù hợp. Để biết thêm thông tin về hình thức hiển thị và chức năng của lớp phủ, hãy xem Mô tả về trường quảng cáo gốc nâng cao.

Thuộc tính quảng cáo

Bạn phải hiển thị một thuộc tính quảng cáo để cho người dùng biết họ đang thấy quảng cáo. Hãy xem nguyên tắc chính sách của chúng tôi để biết thêm thông tin.

Ví dụ về mã

Dưới đây là các bước cần thực hiện để hiển thị quảng cáo gốc hợp nhất:

  1. Tạo một bản sao của lớp UnifiedNativeAdView.
  2. Đối với mỗi tài sản quảng cáo sẽ hiển thị:
    1. Điền vào chế độ xem tài sản bằng tài sản trong đối tượng quảng cáo.
    2. Đăng ký chế độ xem tài sản bằng lớp ViewGroup.
  3. Đăng ký MediaView nếu bố cục quảng cáo gốc bao gồm tài sản nghe nhìn có dung lượng lớn.
  4. Đăng ký đối tượng quảng cáo bằng lớp ViewGroup.

Dưới đây là một hàm mẫu sẽ hiển thị UnifiedNativeAd:

Java

    private void displayUnifiedNativeAd(ViewGroup parent, UnifiedNativeAd ad) {

        // Inflate a layout and add it to the parent ViewGroup.
        LayoutInflater inflater = (LayoutInflater) parent.getContext()
                .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        UnifiedNativeAdView adView = (UnifiedNativeAdView) inflater
                .inflate(R.layout.my_ad_layout, parent);

        // Locate the view that will hold the headline, set its text, and call the
        // UnifiedNativeAdView's setHeadlineView method to register it.
        TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
        headlineView.setText(ad.getHeadline());
        adView.setHeadlineView(headlineView);

        ...
        // Repeat the above process for the other assets in the UnifiedNativeAd
        // using additional view objects (Buttons, ImageViews, etc).
        ...

        // If the app is using a MediaView, it should be
        // instantiated and passed to setMediaView. This view is a little different
        // in that the asset is populated automatically, so there's one less step.
        MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
        adView.setMediaView(mediaView);

        // Call the UnifiedNativeAdView's setNativeAd method to register the
        // NativeAdObject.
        adView.setNativeAd(ad);

        // Ensure that the parent view doesn't already contain an ad view.
        parent.removeAllViews();

        // Place the AdView into the parent.
        parent.addView(adView);
    }
    

Kotlin

    fun displayUnifiedNativeAd(parent: ViewGroup, ad: UnifiedNativeAd) {

        // Inflate a layout and add it to the parent ViewGroup.
        val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
                as LayoutInflater
        val adView = inflater.inflate(R.layout.my_ad_layout, parent) as UnifiedNativeAdView

        // Locate the view that will hold the headline, set its text, and use the
        // UnifiedNativeAdView's headlineView property to register it.
        val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
        headlineView.text = ad.headline
        adView.headlineView = headlineView

        ...
        // Repeat the above process for the other assets in the UnifiedNativeAd using
        // additional view objects (Buttons, ImageViews, etc).
        ...

        val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
        adView.mediaView = mediaView

        // Call the UnifiedNativeAdView's setNativeAd method to register the
        // NativeAdObject.
        adView.setNativeAd(ad)

        // Ensure that the parent view doesn't already contain an ad view.
        parent.removeAllViews()

        // Place the AdView into the parent.
        parent.addView(adView)
    }

Hãy xem xét các nhiệm vụ riêng lẻ:

Tăng cường bố cục

Java

    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    UnifiedNativeAdView adView = (UnifiedNativeAdView) inflater
            .inflate(R.layout.my_ad_layout, parent);
    

Kotlin

    val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
            as LayoutInflater
    val adView = inflater.inflate(R.layout.my_ad_layout, parent) as UnifiedNativeAdView
    

Trong ví dụ này, chúng tôi sẽ tăng cường sử dụng bố cục XML có chứa các chế độ xem để hiển thị quảng cáo gốc hợp nhất và sau đó xác định vị trí một mục tham chiếu đến UnifiedNativeAdView. Xin lưu ý rằng bạn cũng có thể sử dụng lại UnifiedNativeAdView hiện có nếu chế độ xem đó có trong mảnh hoặc hoạt động của bạn, hay thậm chí là tự động tạo một bản sao mà không cần sử dụng tệp bố cục.

Điền và đăng ký chế độ xem tài sản

Mã mẫu này sẽ xác định vị trí chế độ xem dùng để hiển thị dòng tiêu đề, đặt văn bản của dòng tiêu đề đó bằng cách sử dụng tài sản chuỗi do đối tượng quảng cáo cung cấp và đăng ký tài sản đó bằng đối tượng UnifiedNativeAdView:

Java

    TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
    headlineView.setText(ad.getHeadline());
    adView.setHeadlineView(headlineView);
    

Kotlin

    val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
    headlineView.text = ad.headline
    adView.headlineView = headlineView
    

Quy trình này bao gồm việc xác định vị trí chế độ xem, đặt giá trị chế độ xem cũng như đăng ký chế độ xem đó bằng lớp chế độ xem quảng cáo. Quy trình này sẽ lặp lại cho từng tài sản của đối tượng quảng cáo gốc mà ứng dụng sẽ hiển thị.

Xử lý lượt nhấp

SDK sẽ xử lý các lượt nhấp vào tài sản chế độ xem quảng cáo, miễn là bạn điền và đăng ký chính xác chế độ xem tài sản như đã nêu ở mục trước đó.

Dưới đây là một ví dụ về cách sử dụng trình nghe quảng cáo để quan sát các sự kiện lượt nhấp:

Java

    AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
        ...
        .withAdListener(new AdListener() {
            @Override
            public void onAdFailedToLoad(int errorCode) {
                // Handle the failure by logging, altering the UI, and so on.
            }
            @Override
            public void onAdClicked() {
                // Log the click event or other custom behavior.
            }
        })
        .build();
    

Kotlin

    val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        ...
        .withAdListener(object : AdListener() {
            override fun onAdFailedToLoad(errorCode: Int) {
                // Handle the failure by logging, altering the UI, and so on.
            }
        })
        .build()
    

Đăng ký MediaView

MediaView là một View đặc biệt được thiết kế để hiển thị tài sản nghe nhìn chính (có thể là video hoặc hình ảnh).

MediaView có thể được xác định trong bố cục XML hoặc được tạo tự động. Bạn phải đặt chế độ xem này bên trong thứ bậc chế độ xem của NativeAdView, giống như mọi chế độ xem tài sản khác. Các ứng dụng sử dụng MediaView phải đăng ký tài sản này với NativeAdView như sau:

Java

    MediaView mediaView = adView.findViewById(R.id.ad_media);
    adView.setMediaView(mediaView);
    

Kotlin

    adView.mediaView = adView.findViewById<MediaView>(R.id.ad_media)
    

Tương tự như với tất cả các chế độ xem tài sản, bạn phải điền nội dung vào chế độ xem nghe nhìn. Bạn có thể thực hiện việc này bằng cách sử dụng thuộc tính mediaContent. Thuộc tính mediaContent của UnifiedNativeAd có chứa nội dung nghe nhìn mà hệ thống có thể chuyển đến MediaView.

Dưới đây là đoạn mã cài đặt nội dung nghe nhìn cho chế độ xem nghe nhìn:

Java

    mediaView.setMediaContent(nativeAd.getMediaContent());
    

Kotlin

    mediaView.mediaContent = nativeAd.mediaContent
    

Đặt ImageScaleType

Lớp MediaView có thuộc tính ImageScaleType khi hiển thị hình ảnh. Nếu bạn muốn thay đổi cách chuyển tỉ lệ hình ảnh trong MediaView, thì hãy đặt ImageView.ScaleType tương ứng bằng cách sử dụng phương thức setImageScaleType() của MediaView.

Ví dụ: để điền vào MediaView khi hiển thị hình ảnh (quảng cáo không có video):

Java

    mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);
    

Kotlin

    mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP
    

Mẫu GitHub

Kho lưu trữ GitHub của chúng tôi cung cấp đầy đủ hướng dẫn về cách triển khai Quảng cáo gốc nâng cao bằng cả ngôn ngữ lập trình Java và Kotlin.

Tải ví dụ về quảng cáo gốc nâng cao xuống

MediaContent

Lớp MediaContent chứa dữ liệu có liên quan đến nội dung nghe nhìn của quảng cáo gốc và hiển thị dữ liệu này bằng cách sử dụng lớp MediaView. Khi bạn đặt thuộc tính MediaView mediaContent bằng bản sao MediaContent:

  • Nếu quảng cáo có chứa tài sản video, thì video đó sẽ được lưu vào bộ đệm và bắt đầu phát bên trong MediaView. Bạn có thể biết liệu quảng cáo có chứa tài sản video hay không bằng cách chọn hasVideoContent().
  • Nếu quảng cáo không chứa tài sản video, thì hệ thống sẽ tải tài sản mainImage xuống và đặt bên trong MediaView.

Đăng ký đối tượng quảng cáo gốc

Trong bước cuối cùng này, hệ thống sẽ đăng ký đối tượng quảng cáo gốc với chế độ xem chịu trách nhiệm hiển thị đối tượng đó:

Java

    adView.setNativeAd(ad);
    

Kotlin

    adView.setNativeAd(ad)
    

Video gốc

Ngoài hình ảnh, văn bản và chữ số, một số quảng cáo gốc còn chứa tài sản video. Không phải quảng cáo nào cũng chứa tài sản video và các ứng dụng cũng không bắt buộc phải hiển thị tài sản đó.

Để đơn giản hóa cấu hình và chế độ hiển thị video, SDK quảng cáo trên thiết bị di động cung cấp các lớp có liên quan đến video sau đây:

VideoOptions

Lớp VideoOptions cho phép các ứng dụng định cấu hình cách hoạt động của tài sản video gốc. Bạn phải gán các đối tượng VideoOptions vào đối tượng NativeAdOptions mà bạn đã sử dụng khi tạo AdLoader:

Java

    VideoOptions videoOptions = new VideoOptions.Builder()
            .setStartMuted(false)
            .build();

    NativeAdOptions adOptions = new NativeAdOptions.Builder()
            .setVideoOptions(videoOptions)
            .build();

    AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
            .forUnifiedNativeAd( ... )
            .withNativeAdOptions(adOptions)
            .build();
    

Kotlin

    val videoOptions = VideoOptions.Builder()
            .setStartMuted(false)
            .build()

    val adOptions = NativeAdOptions.Builder()
            .setVideoOptions(videoOptions)
            .build()
    val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
            .forUnifiedNativeAd( ... )
            .withNativeAdOptions(adOptions)
            .build()
    

Lớp VideoOptions.Builder hiện đang cung cấp phương thức setStartMuted(). Phương thức này cho SDK biết liệu tài sản video có nên bắt đầu ở trạng thái tắt tiếng hay không. Giá trị mặc định là true.

VideoController

Bạn có thể sử dụng lớp VideoController để lấy thông tin về tài sản video. Các ứng dụng có thể tham chiếu đến đơn vị kiểm soát từ đối tượng UnifiedNativeAd bằng cách gọi phương thức getVideoController() :

Java

    VideoController vc = nativeAd.getVideoController();
    

Kotlin

    val vc = myNativeAd.videoController
    

Phương thức này luôn trả về một đối tượng VideoController ngay cả khi quảng cáo không chứa tài sản video.

VideoController cung cấp phương thức hasVideoContent(). Phương thức này sẽ trả về giá trị true nếu quảng cáo có chứa tài sản video và trả về giá trị false nếu quảng cáo không chứa tài sản video.

Ứng dụng cũng có thể sử dụng lớp VideoController.VideoLifecycleCallbacks để nhận thông báo khi sự kiện xảy ra trong thời gian hoạt động của tài sản video:

Java

    VideoController vc = nativeAd.getVideoController();

    vc.setVideoLifecycleCallbacks(new VideoController.VideoLifecycleCallbacks() {
        public void onVideoEnd() {
            // Here apps can take action knowing video playback is finished.
            // It's always a good idea to wait for playback to complete before
            // replacing or refreshing a native ad, for example.
            super.onVideoEnd();
        }
    });
    

Kotlin

    val vc = nativeAd.videoController

    vc.setVideoLifecycleCallbacks(object : VideoController.VideoLifecycleCallbacks() {
        override fun onVideoEnd() {
            // Here apps can take action knowing video playback is finished.
            // It's always a good idea to wait for playback to complete before
            // replacing or refreshing a native ad, for example.
            super.onVideoEnd()
        }
    })
    

Hủy quảng cáo

Sau khi hoàn thành việc hiển thị quảng cáo gốc, bạn nên hủy quảng cáo đó để quảng cáo được thu dọn đúng cách.

Java

    nativeAd.destroy();
    

Kotlin

    nativeAd.destroy()