Định dạng quảng cáo gốc tùy chỉnh

Định dạng quảng cáo gốc tuỳ chỉnh

Ngoài các định dạng quảng cáo gốc do hệ thống xác định, nhà xuất bản Ad Manager còn có thể tạo các định dạng quảng cáo gốc riêng bằng cách xác định các danh sách thành phần tuỳ chỉnh. Các định dạng này được gọi là định dạng quảng cáo gốc tuỳ chỉnh và có thể dùng với quảng cáo đặt trước. Điều này cho phép nhà xuất bản chuyển dữ liệu có cấu trúc tuỳ ý đến các ứng dụng của mình. Những quảng cáo này do đối tượng NativeCustomFormatAd biểu thị.

Tải các định dạng quảng cáo gốc tuỳ chỉnh

Hướng dẫn này giải thích cách tải và hiển thị các định dạng quảng cáo gốc tuỳ chỉnh.

Tạo Coroutine

Giống như quảng cáo gốc, các định dạng quảng cáo gốc tuỳ chỉnh được tải bằng cách sử dụng lớp AdLoader:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/6499/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

Phương thức forCustomFormatAd định cấu hình AdLoader để yêu cầu các định dạng quảng cáo gốc tuỳ chỉnh. Có 3 tham số được truyền vào phương thức này:

• Mã của định dạng quảng cáo gốc tuỳ chỉnh mà AdLoader sẽ yêu cầu. Mỗi định dạng quảng cáo gốc tuỳ chỉnh đều liên kết với một mã nhận dạng. Tham số này cho biết định dạng mà ứng dụng của bạn muốn AdLoader yêu cầu.
• Hệ thống sẽ gọi OnCustomFormatAdLoadedListener khi quảng cáo đã tải thành công.
• Hệ thống sẽ gọi OnCustomClickListener khi người dùng nhấn hoặc nhấp vào quảng cáo (không bắt buộc). Để biết thêm thông tin về trình nghe này, hãy xem phần "Xử lý lượt nhấp và lượt hiển thị" bên dưới.

Vì một đơn vị quảng cáo có thể được thiết lập để phân phát nhiều định dạng quảng cáo, nên forCustomFormatAd có thể được gọi nhiều lần với mã định dạng duy nhất để chuẩn bị trình tải quảng cáo cho nhiều định dạng quảng cáo gốc tuỳ chỉnh có thể có.

Lưu ý: Bạn có thể sử dụng đồng thời forNativeAd và forCustomFormatAd với một AdLoader nếu có một đơn vị quảng cáo được định cấu hình để phân phát nhiều định dạng quảng cáo.

Mã định dạng quảng cáo gốc tuỳ chỉnh

Bạn có thể tìm thấy mã định dạng dùng để xác định một định dạng quảng cáo gốc tùy chỉnh trong giao diện người dùng Ad Manager trong mục Gốc bên trong trình đơn thả xuống Phân phối:

Mỗi mã định dạng quảng cáo gốc tuỳ chỉnh sẽ xuất hiện bên cạnh tên của mã đó. Khi nhấp vào một trong các tên đó, bạn sẽ được chuyển đến màn hình hiển thị thông tin chi tiết về các trường của định dạng đó:

Tại đây, bạn có thể thêm, chỉnh sửa và xoá từng trường riêng lẻ. Hãy lưu ý Tên của từng tài sản. Tên là khoá dùng để lấy dữ liệu cho từng thành phần khi hiển thị định dạng quảng cáo gốc tuỳ chỉnh.

Hiển thị định dạng quảng cáo gốc tùy chỉnh

Các định dạng quảng cáo gốc tuỳ chỉnh khác với các định dạng do hệ thống xác định, ở chỗ nhà xuất bản có quyền xác định danh sách các thành phần riêng tạo nên một quảng cáo. Do đó, quy trình hiển thị định dạng quảng cáo gốc khác với định dạng do hệ thống xác định ở một số điểm sau:

1. Vì lớp NativeCustomFormatAd dùng để xử lý bất kỳ định dạng quảng cáo gốc tùy chỉnh nào mà bạn đã xác định trong Ad Manager, nên lớp đó sẽ không có tài sản nào có tên là "getters". Thay vào đó, lớp này cung cấp các phương thức như getText và getImage. Các phương thức này lấy tên của trường làm tham số.
2. Hệ thống không hỗ trợ bất kỳ lớp chế độ xem quảng cáo chuyên biệt nào như NativeAdView để sử dụng với NativeCustomFormatAd. Bạn có thể sử dụng bất kỳ bố cục nào phù hợp với trải nghiệm người dùng.
3. Do không có lớp ViewGroup chuyên biệt, nên bạn không cần đăng ký bất kỳ chế độ xem nào mà bạn dùng để hiển thị thành phần của quảng cáo. Việc này sẽ giúp giảm một vài dòng mã khi hiển thị quảng cáo, nhưng cũng có nghĩa là bạn sẽ phải làm nhiều việc hơn để xử lý các lượt nhấp sau đó.

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

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable;

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Video gốc cho các định dạng quảng cáo gốc tuỳ chỉnh

Khi tạo định dạng tuỳ chỉnh, bạn có thể biến định dạng đó thành định dạng đủ điều kiện xuất hiện dưới dạng video.

Trong khi triển khai ứng dụng, bạn có thể dùng NativeCustomFormatAd.getMediaContent() để lấy nội dung nghe nhìn. Sau đó, hãy gọi setMediaContent() để đặt nội dung nghe nhìn trên chế độ xem nội dung nghe nhìn thành chế độ xem nội dung nghe nhìn. Nếu quảng cáo không có nội dung video, hãy lập kế hoạch thay thế để hiển thị quảng cáo không có video.

Lưu ý: Không giống như quảng cáo gốc chứa hình ảnh trong chế độ xem nội dung nghe nhìn khi không có video, chế độ xem nội dung nghe nhìn của quảng cáo gốc tuỳ chỉnh lại không có nội dung nếu không chứa video.

Ví dụ bên dưới sẽ kiểm tra xem quảng cáo có nội dung video hay không và hiển thị một hình ảnh ở vị trí của video nếu không có video:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

Xem MediaContent để biết thêm thông tin về cách bạn có thể tuỳ chỉnh trải nghiệm video của quảng cáo gốc tuỳ chỉnh.

Hãy tải ví dụ về Hiển thị tuỳ chỉnh Ad Manager xuống để xem ví dụ về cách hoạt động của video gốc trong thực tế.

Số lượt nhấp và số lượt hiển thị định dạng quảng cáo gốc tuỳ chỉnh

Với các định dạng quảng cáo gốc tuỳ chỉnh, ứng dụng của bạn sẽ chịu trách nhiệm ghi lại số lượt hiển thị và báo cáo các sự kiện nhấp chuột cho SDK quảng cáo trên thiết bị di động của Google.

Ghi lại số lượt hiển thị

Để ghi lại một lượt hiển thị cho quảng cáo có định dạng tuỳ chỉnh, hãy gọi phương thức recordImpression trên NativeCustomFormatAd tương ứng:

myCustomFormatAd.recordImpression();

Nếu ứng dụng của bạn vô tình gọi phương thức này 2 lần cho cùng một quảng cáo, thì SDK sẽ tự động ngăn chặn việc ghi lại lượt hiển thị trùng lặp cho một yêu cầu.

Báo cáo số lượt nhấp

Để báo cáo cho SDK biết rằng một lượt nhấp đã xảy ra trên một chế độ xem thành phần, hãy gọi phương thức performClick trên NativeCustomFormatAd tương ứng và chuyển tên của thành phần đã được nhấp vào. Ví dụ: nếu bạn có một thành phần trong định dạng tuỳ chỉnh có tên là "MainImage" và muốn báo cáo một lượt nhấp vào ImageView tương ứng với thành phần đó, thì mã của bạn sẽ trông giống như sau:

myCustomFormatAd.performClick("MainImage");

Xin lưu ý rằng bạn không cần phải gọi phương thức này cho mỗi chế độ xem được liên kết với quảng cáo của mình. Nếu bạn có một trường khác có tên "Caption" mà bạn chỉ hiển thị nhưng không cho người dùng nhấp hay nhấn vào, thì ứng dụng của bạn không cần gọi performClick cho chế độ xem của tài sản đó.

Phản hồi các thao tác nhấp tuỳ chỉnh

Khi người dùng nhấp vào một quảng cáo có định dạng tuỳ chỉnh, SDK có thể phản hồi theo 3 cách theo thứ tự sau:

1. Gọi OnCustomClickListener từ AdLoader nếu có.
2. Đối với mỗi URL liên kết sâu của quảng cáo, hãy cố gắng tìm trình phân giải nội dung và bắt đầu phân giải nội dung đầu tiên.
3. Mở một trình duyệt rồi chuyển đến URL đích truyền thống của quảng cáo đó.

Phương thức forCustomFormatAd chấp nhận một OnCustomClickListener. Nếu bạn chuyển đối tượng trình nghe vào, SDK sẽ gọi phương thức onCustomClick và không thực hiện thêm hành động nào. Tuy nhiên, nếu bạn chuyển một giá trị rỗng dưới dạng trình nghe, SDK sẽ quay về đường liên kết sâu và/hoặc URL đích đã đăng ký với quảng cáo.

Trình nghe lượt nhấp tuỳ chỉnh cho phép ứng dụng của bạn quyết định hành động tốt nhất cần thực hiện để phản hồi một lượt nhấp, cho dù hành động đó là cập nhật giao diện người dùng, chạy một hoạt động mới hay chỉ ghi nhật ký lượt nhấp đó. Dưới đây là một ví dụ chỉ ghi lại rằng một lượt nhấp đã diễn ra:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/6499/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

Lúc đầu, bạn có thể thấy lạ khi thấy có các trình nghe lượt nhấp tuỳ chỉnh. Suy cho cùng thì ứng dụng của bạn chỉ thông báo với SDK rằng một lượt nhấp đã xảy ra, vậy tại sao SDK nên quay lại và báo cáo điều đó cho ứng dụng?

Luồng thông tin này rất hữu ích vì một vài lý do, nhưng quan trọng nhất là cho phép SDK giữ quyền kiểm soát hoạt động phản hồi đối với lượt nhấp. Ví dụ: SDK này có thể tự động ping các URL theo dõi của bên thứ ba đã được đặt cho mẫu quảng cáo và xử lý ngầm các nhiệm vụ khác mà không cần thêm mã.