أشكال الإعلانات المدمجة المخصصة

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

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

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

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

إنشاء أداة تحميل الإعلانات

مثل الإعلانات المدمجة مع المحتوى، يتم تحميل أشكال الإعلانات المدمجة مع المحتوى باستخدام فئة 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()

تعمل طريقة forCustomFormatAd على إعداد AdLoader لطلب أشكال إعلانات مدمجة مخصّصة. هناك ثلاث معلمات تم تمريرها إلى الطريقة:

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

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

ملاحظة: يمكن استخدام forNativeAd وforCustomFormatAd في الوقت نفسه مع AdLoader واحدة إذا كانت لديك وحدة إعلانية تم إعدادها لعرض أشكال إعلانات متعددة.

رقم تعريف شكل الإعلان المدمج المخصص

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

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

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

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

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

1. بما أنّ الفئة NativeCustomFormatAd مخصّصة للتعامل مع أي من أشكال الإعلانات المدمجة مع المحتوى المخصّصة التي تحدّدها في "مدير الإعلانات"، فإنّها لا تحمل اسم "getters" لمواد العرض. بدلاً من ذلك، فإنها توفر طرقًا مثل getText وgetImage تأخذ اسم الحقل كمَعلمة.
2. ما مِن فئة مخصّصة لعرض الإعلانات مثل NativeAdView لاستخدامها مع NativeCustomFormatAd. لك حرية استخدام أي تخطيط مناسب لتجربة المستخدم لديك.
3. بما أنّه لا تتوفّر فئة ViewGroup مخصّصة، لن تحتاج إلى تسجيل أي من طرق العرض المستخدَمة لعرض مواد عرض الإعلان. يؤدي هذا الإجراء إلى حفظ بضعة أسطر من الرمز عند عرض الإعلان، ولكنّه يعني أيضًا أنّك ستحتاج إلى إجراء جهد إضافي للتعامل مع النقرات لاحقًا.

في ما يلي مثال على دالة تعرض 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.
    ...
}

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

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

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

ملاحظة مهمة: اضبط رمز "خيارات الإعلان" على 15 بكسل × 15 بكسل على الأقل.

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

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

Java

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

نقطة رئيسية: إذا كنت تستخدم عنصر التحكّم في تنزيل الصور لطلب عناوين URL للصور فقط، تلتزم مادة العرض في "خيارات الإعلان" بهذا الإعداد وستعرض عنوان URL للصورة فقط.

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

عند إنشاء تنسيق مخصص، يمكنك جعل التنسيق مؤهلاً للفيديو.

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

ملاحظة: على عكس الإعلانات المدمجة مع المحتوى التي تحتوي على صورة في عرض الوسائط عندما يكون الفيديو غير متاح، لا يكون عرض الوسائط للإعلان المدمج مع المحتوى بأي محتوى إذا كان لا يحتوي على فيديو.

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

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

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

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

النقرات ومرات الظهور المخصصة لشكل الإعلان المدمج مع المحتوى

باستخدام أشكال الإعلانات المدمجة مع المحتوى المخصّصة، يكون تطبيقك مسؤولاً عن تسجيل مرات الظهور وإعداد تقارير عن أحداث النقرات في "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة".

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

لتسجيل مرة ظهور لإعلان شكل مخصّص، استدعِ الطريقة recordImpression على NativeCustomFormatAd المقابلة:

myCustomFormatAd.recordImpression();

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

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

لإرسال تقرير إلى حزمة تطوير البرامج (SDK) عن حدوث نقرة في مشاهدة مادة عرض، يمكنك استدعاء طريقة performClick في NativeCustomFormatAd المقابلة وإدراج اسم مادة العرض التي تم النقر عليها. على سبيل المثال، إذا كانت لديك مادة عرض بالتنسيق المخصّص باسم "MainImage" وأردت الإبلاغ عن نقرة على ImageView المقابلة لمادة العرض هذه، سيظهر الرمز على النحو التالي:

myCustomFormatAd.performClick("MainImage");

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

الاستجابة لإجراءات النقرات المخصّصة

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

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

تقبل الطريقة forCustomFormatAd عنصر OnCustomClickListener. وفي حال تمرير كائن مستمع، ستستدعي حزمة SDK طريقة onCustomClick بدلاً من ذلك ولا تتخذ أي إجراء آخر. ومع ذلك، إذا ضبطت قيمة فارغة كمستمع، تعود حزمة SDK إلى الرابط لصفحة في التطبيق و/أو عناوين URL المقصودة المسجّلة بالإعلان.

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

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

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

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