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

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

بالإضافة إلى أشكال الإعلانات المدمجة مع المحتوى التي يحددها النظام، يتوفر للناشرين في "مدير الإعلانات" خيار إنشاء أشكال الإعلانات المدمجة مع المحتوى الخاصة بهم من خلال تحديد قوائم مخصصة بمواد العرض. تُعرف هذه الأشكال باسم أشكال الإعلانات المدمجة المخصّصة، ويمكن استخدامها مع الإعلانات المحجوزة. يتيح ذلك للناشرين تمرير بيانات منظَّمة عشوائية إلى تطبيقاتهم. ويمثل هذه الإعلانات العنصر 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.
    ...
}

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

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

في تنفيذ تطبيقك، يمكنك استخدام 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");

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

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

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

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

تقبل الطريقة forCustomFormatAd عنصر OnCustomClickListener. وفي حال تمرير كائن مستمع، تستدعي حزمة تطوير البرامج (SDK) طريقة onCustomClick الخاصة بها بدلاً من ذلك ولا تتخذ أي إجراء آخر. ومع ذلك، إذا ضبطت قيمة فارغة كمستمع، تعود حزمة تطوير البرامج (SDK) إلى عنوان URL لصفحة معيّنة في التطبيق و/أو عناوين 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 لتتبّع الجهات الخارجية التي تم إعدادها لتصميم الإعلان، على سبيل المثال، والتعامل مع مهام أخرى وراء الكواليس بدون أي رمز إضافي.