استخدام أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

اختيار النظام الأساسي: Android جديد Android iOS

بالإضافة إلى أشكال الإعلانات المدمجة مع المحتوى التي يحدّدها النظام، يمكن للناشرين على "إدارة إعلانات Google" إنشاء أشكال "إعلانات مدمجة مع المحتوى" من خلال تحديد قوائم مخصّصة لمواد العرض. ويُطلق عليها اسم أشكال الإعلانات المدمجة مع المحتوى المخصصة، ويمكن استخدامها مع الإعلانات المحجوزة. ويتيح ذلك للناشرين تمرير بيانات منظَّمة عشوائية إلى تطبيقاتهم. ويتم تمثيل هذه الإعلانات من خلال العنصر NativeCustomFormatAd.

تحميل أشكال الإعلانات المدمجة مع المحتوى المخصصة

يوضّح هذا الدليل كيفية تحميل أشكال الإعلانات المدمجة مع المحتوى المخصصة وعرضها.

تحميل إعلان مدمج مع المحتوى مخصص

على غرار "الإعلانات المدمجة مع المحتوى"، يتم تحميل أشكال "الإعلانات المخصصة المدمجة مع المحتوى" باستخدام الصف AdLoader:

جافا

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        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
          }
        })
    .forCustomFormatAd("12406343",
        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
          }
        })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
  .forCustomFormatAd(
    "12387226",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .forCustomFormatAd(
    "12406343",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .build()

تضبط طريقة forCustomFormatAd الصف AdLoader لطلب أشكال الإعلانات المدمجة مع المحتوى المخصصة. يمكنك استدعاء الطريقة عدة مرات لمعرّفات أشكال مخصّصة مختلفة. تقبل الطريقة المعلمات التالية:

  • معرّف شكل الإعلان المدمج مع المحتوى المخصّص الذي يجب أن يطلبه AdLoader. يرتبط كل شكل من أشكال الإعلانات المدمجة مع المحتوى المخصّصة بمعرّف. تشير هذه المعلمة إلى الشكل الذي يريد تطبيقك أن يطلبه AdLoader.
  • An OnCustomFormatAdLoadedListener يتم استدعاؤه عند تحميل إعلان بنجاح.
  • اختياري OnCustomClickListener يتم استدعاؤه عندما ينقر المستخدم على الإعلان أو يضغط عليه. لمزيد من المعلومات عن هذا المتتبِّع، يُرجى الاطّلاع على قسم "التعامل مع النقرات ومرّات الظهور".

بما أنّه يمكن إعداد وحدة إعلانية واحدة لعرض أكثر من شكل واحد من تنسيق التصميم، يمكن استدعاء forCustomFormatAd عدة مرات باستخدام معرّفات أشكال فريدة من أجل إعداد أداة تحميل الإعلانات لأكثر من شكل واحد من أشكال "الإعلانات المخصصة المدمجة مع المحتوى".

معرّف شكل الإعلان المدمج مع المحتوى المخصّص

يمكن العثور على معرّف الشكل المستخدَم لتحديد شكل "الإعلان المخصص المدمج مع المحتوى" في واجهة مستخدم "إدارة إعلانات Google" ضِمن قسم الإعلانات المدمجة مع المحتوى في القائمة المنسدلة العرض:

يظهر معرّف كل شكل من أشكال الإعلانات المخصصة المدمجة مع المحتوى بجانب اسمه. يؤدي النقر على أحد الأسماء إلى نقلك إلى شاشة تفاصيل تعرض معلومات عن حقول الشكل:

من هنا، يمكن إضافة حقول فردية وتعديلها وإزالتها. يُرجى ملاحظة اسم كل مادة من مواد العرض. الاسم هو المفتاح المستخدَم للحصول على بيانات كل مادة عرض عند عرض شكل إعلانك المخصص المدمج مع المحتوى.

عرض أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

تختلف أشكال الإعلانات المدمجة مع المحتوى المخصّصة عن الأشكال التي يحدّدها النظام في أنّ الناشرين لديهم القدرة على تحديد قائمة مواد العرض الخاصة بهم التي تشكّل إعلانًا. لذلك، تختلف عملية عرض أحد هذه الأشكال عن الأشكال التي يحدّدها النظام في بعض الجوانب:

  1. تتوفّر مواد عرض النصوص والصور من خلال أدوات إرجاع القيمة getText() وgetImage() التي تأخذ اسم الحقل كمعلَمة.
  2. بما أنّه لا يوجد صف ViewGroup مخصّص للتسجيل في Google، عليك تسجيل مرّات الظهور والنقرات يدويًا.
  3. يحتوي "الإعلان المخصص المدمج مع المحتوى" على محتوى وسائط null إذا لم يكن الإعلان يحتوي على مادة عرض فيديو.

في ما يلي مثال على دالة تعرض NativeCustomFormatAd:

جافا

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

فيديو مدمج مع المحتوى لأشكال الإعلانات المخصصة المدمجة مع المحتوى

عند إنشاء شكل مخصّص، يمكنك جعل الشكل مؤهلاً لعرض الفيديو.

في عملية تنفيذ تطبيقك، يمكنك استخدام NativeCustomFormatAd.getMediaContent() للحصول على محتوى الوسائط. بعد ذلك، استدعِ setMediaContent() لضبط محتوى الوسائط على طريقة عرض الوسائط. إذا كان الإعلان يحتوي على محتوى وسائط null، ضَع خططًا بديلة لعرض الإعلان بدون فيديو.

يتحقّق المثال التالي مما إذا كان الإعلان يحتوي على محتوى فيديو، ويعرض صورة بدلاً منه إذا لم يتوفّر فيديو:

جافا

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

نزِّل مثال العرض المخصّص في "إدارة إعلانات Google" للحصول على مثال عملي على الفيديو المدمج مع المحتوى قيد التشغيل.

راجِع الإعلانات على الفيديو لمزيد من المعلومات حول كيفية تخصيص تجربة الفيديو في "إعلان مخصص مدمج مع المحتوى".

عرض رمز "خيارات الإعلان"

كجزء من دعم قانون الخدمات الرقمية، تتطلّب الإعلانات المحجوزة المعروضة في المنطقة الاقتصادية الأوروبية رمز "خيارات الإعلان" ورابطًا إلى صفحة "تفاصيل عن الإعلان" من Google. عند تنفيذ "الإعلانات المخصصة المدمجة مع المحتوى"، تكون مسؤولاً عن عرض رمز "خيارات الإعلان". ننصحك باتّخاذ خطوات لعرض رمز "خيارات الإعلان" وضبط مستمع النقرات له عند عرض مواد العرض الرئيسية للإعلان.

يفترض المثال التالي أنّك حدّدت عنصر <ImageView /> في هيكلية طرق العرض لعرض شعار "خيارات الإعلان".

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

تعرض الأمثلة التالية رمز "خيارات الإعلان" وتضبط سلوك النقر المناسب.

جافا

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

تسجيل مرّات الظهور والإبلاغ عن النقرات

تطبيقك هو المسؤول عن تسجيل مرّات الظهور والإبلاغ عن أحداث النقرات إلى Google Mobile Ads SDK.

تسجيل مرّات الظهور

لتسجيل مرّة ظهور لإعلان مخصص مدمج مع المحتوى، استدعِ طريقة recordImpression() للإعلان:

myCustomFormatAd.recordImpression();

إذا استدعى تطبيقك الطريقة مرّتين عن طريق الخطأ للإعلان نفسه، تمنع حزمة SDK تلقائيًا تسجيل مرّة ظهور مكرّرة لطلب واحد.

الإبلاغ عن النقرات

لإبلاغ حزمة SDK عن حدوث نقرة على طريقة عرض مادة عرض، استدعِ طريقة performClick() للإعلان. قدِّم اسم مادة العرض التي تم النقر عليها باستخدام السلسلة نفسها التي حدّدتها في واجهة مستخدم "إدارة إعلانات Google".

myCustomFormatAd.performClick("MainImage");

يُرجى العِلم أنّه ليس عليك استدعاء هذه الطريقة لكل طريقة عرض مرتبطة بإعلانك. إذا كان لديك حقل آخر باسم "الشرح" كان من المفترض عرضه ولكن لم ينقر عليه المستخدم أو يضغط عليه، لن يحتاج تطبيقك إلى استدعاء performClick لطريقة عرض مادة العرض هذه.

الردّ على إجراءات النقر المخصّصة

عند النقر على إعلان بتنسيق مخصّص، هناك ثلاثة ردود محتمَلة من حزمة SDK، يتم تجربتها بهذا الترتيب:

  1. استدعِ OnCustomClickListener إذا تم تقديم مستمع.
  2. بالنسبة إلى كل عناوين URL للروابط العميقة في الإعلان، حاوِل العثور على أداة حلّ محتوى وبدء أول عنوان URL يتم حلّه.
  3. افتح متصفّحًا وانتقِل إلى عنوان URL المقصود للإعلان.

لتنفيذ إجراء نقر مخصّص، قدِّم OnCustomClickListener:

جافا

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/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, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

في البداية، قد يبدو غريبًا وجود مستمعين للنقرات المخصّصة. بعد كل شيء، أبلغ تطبيقك حزمة SDK بحدوث نقرة، فلماذا يجب أن تعود حزمة SDK وتُبلغ التطبيق بذلك؟

يكون تدفق المعلومات هذا مفيدًا لعدة أسباب، ولكن الأهم من ذلك أنّه يسمح لحزمة SDK بالتحكّم في الردّ على النقرة. يمكنها تلقائيًا إرسال إشعارات إلى عناوين URL لتتبُّع الجهات الخارجية التي تم ضبطها لتصميم الإعلان، على سبيل المثال، والتعامل مع المهام الأخرى وراء الكواليس، بدون أي رمز إضافي.