Sử dụng đị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 danh sách các tài sản tuỳ chỉnh. Các định dạng này có tên là định dạng quảng cáo gốc tùy chỉnh và có thể sử dụng cù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 tùy ý đến các ứng dụng của mình. Các quảng cáo này được biểu thị bằng đối tượng NativeCustomFormatAd.

Lưu ý:Lớp NativeCustomFormatAd không hỗ trợ việc nhận đối tượng ResponseInfo hoặc gói extras.

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

Tài liệu 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 tùy chỉnh .

Tải quảng cáo gốc tuỳ chỉnh

Để tải quảng cáo gốc tuỳ chỉnh, hãy làm như sau:

1. Thêm loại NativeAdType.CUSTOM_NATIVE làm loại quảng cáo trong NativeAdRequest.

2. Đặt mã định dạng của quảng cáo gốc tuỳ chỉnh.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)
CustomNativeSnippets.kt

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });
CustomNativeSnippets.java

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 định dạng quảng cáo gốc tuỳ chỉnh trong Giao diện người dùng Ad Manager trong mục Quảng cáo gốc bên trong trình đơn thả xuống Phân phối:

Mã định dạng của mỗi đị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 về các trường của định dạng đó:

Từ đây, bạn có thể thêm, chỉnh sửa và xoá các 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 tài sả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 tuỳ chỉnh

Các định dạng quảng cáo gốc tùy chỉnh khác với các định dạng quảng cáo gốc do hệ thống xác định, trong đó nhà xuất bản có quyền xác định danh sách các tài sản riêng của họ sẽ tạo thành một quảng cáo. Do đó, quy trình hiển thị một đị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 theo một số cách:

1. Các tài sản văn bản và hình ảnh có sẵn thông qua các phương thức getter getText() và getImage() lấy tên trường làm tham số.
2. Vì không có lớp ViewGroup chuyên biệt để đăng ký với Google, nên bạn cần ghi lại số lượt hiển thị và số lượt nhấp theo cách thủ công.
3. Quảng cáo gốc tuỳ chỉnh có nội dung nghe nhìn null nếu quảng cáo không chứa thành phần video.

Ví dụ này cho bạn biết cách hiển thị CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}
CustomNativeSnippets.kt

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}
CustomNativeSnippets.java

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

Khi tạo định dạng tùy chỉnh, bạn có thể biến định dạng đó thành định dạng đủ điều kiện hiển thị video.

Trong quá trình triển khai ứng dụng, bạn có thể sử dụng CustomNativeAd.getMediaContent() để lấy nội dung nghe nhìn. Sau đó, hãy gọi setMediaContent() để đặt nội dung nghe nhìn trên trung tâm nghe nhìn. Nếu quảng cáo có nội dung nghe nhìn null, hãy lập kế hoạch thay thế để hiển thị quảng cáo không có 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:

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}
CustomNativeSnippets.kt

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}
CustomNativeSnippets.java

Xem Quảng cáo dạng video để 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.

Kết xuất biểu tượng Lựa chọn quảng cáo

Trong khuôn khổ Hỗ trợ Đạo luật Dịch vụ kỹ thuật số (DSA), quảng cáo đặt trước được phân phát ở Khu vực kinh tế Châu Âu (EEA) phải có biểu tượng Lựa chọn quảng cáo và một đường liên kết đến trang Thông tin về quảng cáo này của Google. Khi triển khai quảng cáo gốc tuỳ chỉnh, bạn có trách nhiệm kết xuất hình ảnh biểu tượng Lựa chọn quảng cáo. Bạn cần thực hiện các bước để kết xuất hình ảnh và thiết lập trình nghe lượt nhấp cho biểu tượng Lựa chọn quảng cáo khi cho thấy các thành phần quảng cáo chính.

Ví dụ sau đây giả định rằng bạn đã xác định một phần tử <ImageView /> trong hệ phân cấp view để chứa biểu trưng Lựa chọn quảng cáo.

**Quan trọng:** Đặt biểu tượng Lựa chọn quảng cáo có kích thước ít nhất là 15 pixel x 15 pixel.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

Các ví dụ sau đây kết xuất biểu tượng Lựa chọn quảng cáo và định cấu hình hành vi nhấp thích hợp.

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}
CustomNativeSnippets.kt

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}
CustomNativeSnippets.java

Lưu ý quan trọng: Nếu bạn sử dụng Kiểm soát việc tải hình ảnh xuống để chỉ yêu cầu URL hình ảnh, thì thành phần Lựa chọn quảng cáo sẽ tuân theo chế độ cài đặt này và chỉ trả về URL hình ảnh.

Ghi lại số lượt hiển thị và báo cáo số lượt nhấp

Ứng dụng của bạn 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 cho GMA Next-Gen SDK.

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

Để ghi lại một lượt hiển thị cho quảng cáo gốc tuỳ chỉnh, hãy gọi phương thức recordImpression() của quảng cáo:

Kotlin

// Record an impression.
customNativeAd.recordImpression()
CustomNativeSnippets.kt

Java

// Record an impression.
customNativeAd.recordImpression();
CustomNativeSnippets.java

Nếu ứng dụng của bạn vô tình gọi phương thức này hai lần cho cùng một quảng cáo, SDK sẽ tự động ngăn cả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 rằng một lượt nhấp đã xảy ra trên khung hiển thị thành phần, hãy gọi phương thức performClick() của quảng cáo. Cung cấp tên của thành phần đã được nhấp bằng cùng một chuỗi mà bạn đã xác định trong Giao diện người dùng Ad Manager.

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
CustomNativeSnippets.kt

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });
CustomNativeSnippets.java

Xin lưu ý rằng bạn không cần gọi phương thức này cho mọi khung hiển thị được liên kết với quảng cáo. Nếu bạn có một trường khác có tên là "Caption" (có nghĩa là trường này chỉ hiển thị mà 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 khung hiển thị của tài sản đó.

Phản hồi hành động nhấp tuỳ chỉnh

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

1. Gọi OnCustomClickListener nếu bạn đã cung cấp.
2. Đối với mỗi URL liên kết sâu của quảng cáo, hãy thử 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 của quảng cáo.

Để triển khai hành động nhấp tuỳ chỉnh, hãy cung cấp OnCustomClickListener:

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }
CustomNativeSnippets.kt

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });
CustomNativeSnippets.java

Lúc đầu, bạn có thể thấy lạ khi thấy có các trình xử lý lần nhấp tùy chỉnh. Rốt cuộc, ứng dụng của bạn vừa báo cho SDK biết rằng đã xảy ra một lượt nhấp, vậy tại sao SDK lại phải 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 điều 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 có thể tự động ping URL theo dõi của bên thứ ba đã được đặt cho mẫu quảng cáo và ngầm xử lý các nhiệm vụ khác mà không cần thêm bất kỳ mã nào.