استفاده از قالب‌های آگهی بومی سفارشی

علاوه‌بر قالب‌های بومی تعریف‌شده توسط سیستم، ناشران Ad Manager این گزینه را دارند که با تعریف فهرست‌های سفارشی دارایی‌ها، قالب‌های آگهی بومی خودشان را ایجاد کنند. به این‌ها قالب‌های آگهی بومی سفارشی گفته می‌شود و می‌توان از آن‌ها با آگهی‌های رزروشده استفاده کرد. این کار به ناشران امکان می‌دهد داده‌های ساختاریافته دلخواه را به برنامه‌هایشان منتقل کنند. این آگهی‌ها با شیء NativeCustomFormatAd نشان داده می‌شوند.

بار کردن قالب‌های آگهی بومی سفارشی

این راهنما نحوه بار کردن و نمایش دادن قالب‌های آگهی بومی سفارشی را توضیح می‌دهد.

بار کردن آگهی بومی سفارشی

برای بار کردن آگهی بومی سفارشی، کارهای زیر را انجام دهید:

  1. نوع NativeAdType.CUSTOM_NATIVE را به‌عنوان نوع آگهی در NativeAdRequest اضافه کنید.

  2. شناسه قالب آگهی بومی سفارشی را تنظیم کنید.

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) {}
  },
)

جاوا

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) {}
    });

شناسه قالب آگهی بومی سفارشی

شناسه قالبی که برای شناسایی قالب آگهی بومی سفارشی استفاده می‌شود را می‌توانید در واسط کاربری Ad Manager در بخش بومی در منو کرکره‌ای تحویل پیدا کنید:

هر شناسه قالب آگهی بومی سفارشی در کنار نام آن نشان داده می‌شود. با کلیک کردن روی یکی از نام‌ها، به صفحه جزئیات می‌روید که اطلاعاتی درباره فیلدهای قالب نشان می‌دهد:

از اینجا می‌توانید فیلدهای تکی را اضافه، ویرایش، و حذف کنید. نام هریک از دارایی‌ها را یادداشت کنید. نام کلیدی است که برای دریافت داده‌های هر دارایی هنگام نمایش قالب آگهی بومی سفارشی شما استفاده می‌شود.

نمایش قالب‌های آگهی بومی سفارشی

قالب‌های آگهی بومی سفارشی با قالب‌های تعریف‌شده توسط سیستم تفاوت دارند زیرا ناشران می‌توانند فهرست دارایی‌های خود را که آگهی را تشکیل می‌دهند تعریف کنند. بنابراین، فرایند نمایش آن از چند جهت با قالب‌های تعریف‌شده توسط سیستم متفاوت است:

  1. دارایی‌های نوشتاری و تصویری ازطریق گیرنده‌های getText() و getImage() که نام فیلد را به‌عنوان پارامتر می‌گیرند دردسترس هستند.
  2. چون کلاس ViewGroup اختصاصی برای ثبت‌نام با Google وجود ندارد، باید ظهورها و کلیک‌ها را به‌صورت دستی ثبت کنید.
  3. اگر آگهی دارایی ویدیویی نداشته باشد، آگهی بومی سفارشی دارای محتوای رسانه‌ای null است.

این مثال به شما نشان می‌دهد که چگونه یک 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()
}

جاوا

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();
  }
}

ویدیو بومی برای قالب‌های آگهی بومی سفارشی

هنگام ایجاد قالب سفارشی، می‌توانید قالب را برای ویدیو واجدشرایط کنید.

در پیاده‌سازی برنامه‌تان، می‌توانید از CustomNativeAd.getMediaContent() برای دریافت محتوای رسانه‌ای استفاده کنید. سپس setMediaContent() را فراخوانی کنید تا محتوای رسانه را در نمای رسانه تنظیم کنید. اگر آگهی دارای محتوای رسانه‌ای null است، برنامه‌های جایگزینی برای نمایش آگهی بدون ویدیو ایجاد کنید.

مثال زیر بررسی می‌کند که آیا آگهی محتوای ویدیویی دارد یا نه، و اگر ویدیو دردسترس نباشد، تصویری را به‌جای آن نمایش می‌دهد:

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()
}

جاوا

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();
}

برای اطلاعات بیشتر درباره نحوه سفارشی‌سازی تجربه ویدیو آگهی بومی سفارشی، آگهی‌های ویدیویی را ببینید.

پرداز زدن نماد AdChoices

به‌عنوان بخشی از پشتیبانی از «قانون خدمات دیجیتال» (DSA)، آگهی‌های رزرو ارائه‌شده در «منطقه اقتصادی اروپا» (EEA) به نماد AdChoices و پیوندی به صفحه «درباره این آگهی» Google نیاز دارند. هنگام پیاده‌سازی آگهی‌های بومی سفارشی، شما مسئول رندر کردن نماد AdChoices هستید. توصیه می‌کنیم هنگام ارائه دارایی‌های آگهی اصلی، اقداماتی را برای ارائه و تنظیم شنونده کلیک برای نماد AdChoices انجام دهید.

نمونه زیر فرض می‌کند که عنصر <ImageView /> را در سلسله‌مراتب نمای خود برای نگهداری نشان‌واره AdChoices تعریف کرده‌اید.

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

مثال‌های زیر نماد AdChoices را ارائه می‌دهد و رفتار کلیک مناسب را پیکربندی می‌کند.

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
  }
}

جاوا

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);
    }
  }
}

ثبت ظهورها و گزارش کلیک‌ها

برنامه شما مسئول ثبت ظهورها و گزارش رویدادهای کلیک به GMA Next-Gen SDK است.

ظهورهای ضبط

برای ثبت ظهور برای آگهی بومی سفارشی، روش recordImpression() آگهی را فراخوانی کنید:

Kotlin

// Record an impression.
customNativeAd.recordImpression()

جاوا

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

اگر برنامه شما به‌طور تصادفی این روش را دو بار برای یک آگهی فراخوانی کند، کیت توسعه نرم‌افزار به‌طور خودکار از ثبت ظهور تکراری برای یک درخواست جلوگیری می‌کند.

کلیک‌های گزارش تخلف

برای گزارش به کیت توسعه نرم‌افزار مبنی بر اینکه کلیکی روی نمای دارایی رخ داده است، روش performClick() آگهی را فراخوانی کنید. نام دارایی‌ای را که روی آن کلیک شده است بااستفاده از همان رشته‌ای که در واسط کاربر Ad Manager تعریف کرده‌اید ارائه دهید.

Kotlin

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

جاوا

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

توجه داشته باشید که لازم نیست این روش را برای هر نمای مرتبط با آگهی‌تان فراخوانی کنید. اگر فیلد دیگری به‌نام «زیرنویس» داشتید که قرار بود نمایش داده شود اما کاربر روی آن کلیک یا تک‌ضرب نمی‌زد، برنامه‌تان نیازی نداشت برای نمای آن دارایی performClick را فراخوانی کند.

پاسخ دادن به کنش‌های کلیک سفارشی

وقتی روی آگهی با قالب سفارشی کلیک می‌شود، سه پاسخ احتمالی از کیت توسعه نرم‌افزار وجود دارد که به‌ترتیب زیر امتحان می‌شوند:

  1. اگر OnCustomClickListener ارائه شده است، آن را فراخوانی کنید.
  2. برای هریک از نشانی‌های وب پیوند عمیق آگهی، سعی کنید یک حل‌کننده محتوا پیدا کنید و اولین موردی را که حل می‌شود شروع کنید.
  3. مرورگری را باز کنید و به نشانی وب مقصد آگهی بروید.

برای پیاده‌سازی کنش کلیک سفارشی، OnCustomClickListener را ارائه دهید:

Kotlin

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

جاوا

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

در ابتدا، ممکن است وجود شنوندگان کلیک سفارشی عجیب به‌نظر برسد. به‌هرحال، برنامه شما به‌تازگی به کیت توسعه نرم‌افزار گفته است که کلیکی اتفاق افتاده است، پس چرا کیت توسعه نرم‌افزار باید برگردد و آن را به برنامه گزارش دهد؟

این جریان اطلاعات به چند دلیل مفید است، اما مهم‌ترین دلیل این است که به کیت توسعه نرم‌افزار اجازه می‌دهد کنترل پاسخ به کلیک را حفظ کند. برای مثال، می‌تواند به‌طور خودکار به نشانی‌های وب ردگیری طرف سوم که برای طرح آگهی تنظیم شده‌اند پینگ کند و کارهای دیگر را بدون هیچ کد اضافی در پشت صحنه انجام دهد.