إعلان مدمج مع المحتوى (متقدم)

عرض إعلان مدمج مع المحتوى

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

نقطة رئيسية: راجِع سياسات وإرشادات الإعلانات المدمجة مع المحتوى للحصول على إرشادات حول كيفية عرض إعلاناتك المدمَجة مع المحتوى.

صف واحد (NativeAdView)

بالنسبة إلى تنسيق NativeAd، تتوفّر الفئة NativeAdView المقابلة. هذه الفئة هي ViewGroup التي يجب أن يستخدمها الناشرون كجذر للسمة NativeAd. يتوافق عنصر NativeAdView واحد مع إعلان واحد مدمج مع المحتوى. يجب أن تكون كل طريقة عرض تُستخدَم لعرض مواد عرض هذا الإعلان (ImageView التي تعرض مادة عرض لقطة الشاشة، على سبيل المثال) عنصرًا فرعيًا لكائن NativeAdView.

قد يبدو التدرّج الهرمي للإعلانات المدمجة مع المحتوى الذي يستخدم LinearLayout لعرض مرات مشاهدة مواد العرض على النحو التالي:

<com.google.android.gms.ads.nativead.NativeAdView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
    android:orientation="vertical"
    ... >
        <LinearLayout
        android:orientation="horizontal"
        ... >
          <ImageView
           android:id="@+id/ad_app_icon"
           ... />
          <TextView
            android:id="@+id/ad_headline"
            ... />
         </LinearLayout>


         // Other assets such as image or media view, call to action, etc follow.
         ...
    </LinearLayout>
</com.google.android.gms.ads.nativead.NativeAdView>

في ما يلي مثال يؤدي إلى إنشاء سمة NativeAdView وتعبئتها بـ NativeAd:

Java

AdLoader.Builder builder = new AdLoader.Builder(this, "AD_UNIT_ID")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Assumes you have a placeholder FrameLayout in your View layout
            // (with id fl_adplaceholder) where the ad is to be placed.
            FrameLayout frameLayout =
                findViewById(R.id.fl_adplaceholder);
            // Assumes that your ad layout is in a file call native_ad_layout.xml
            // in the res/layout folder
            NativeAdView adView = (NativeAdView) getLayoutInflater()
                .inflate(R.layout.native_ad_layout, null);
            // This method sets the text, images and the native ad, etc into the ad
            // view.
            populateNativeAdView(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "AD_UNIT_ID")
    .forNativeAd { nativeAd ->
        // Assumes that your ad layout is in a file call native_ad_layout.xml
        // in the res/layout folder
        val adView = layoutInflater
                .inflate(R.layout.native_ad_layout, null) as NativeAdView
        // This method sets the text, images and the native ad, etc into the ad
        // view.
        populateNativeAdView(nativeAd, adView)
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with id ad_frame) where the ad is to be placed.
        ad_frame.removeAllViews()
        ad_frame.addView(adView)
    }

تجدر الإشارة إلى أنّه يجب عرض جميع مواد العرض لإعلان مدمج مع المحتوى داخل تنسيق NativeAdView. تحاول حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" تسجيل تحذير عند عرض مواد العرض المدمجة مع المحتوى خارج تنسيق عرض الإعلان المدمج مع المحتوى.

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

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

تراكب "خيارات الإعلان"

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

ملاحظة: يتم عرض "خيارات الإعلان" للإعلانات المُباعة مباشرةً في المنطقة الاقتصادية الأوروبية فقط.

إحالة الإعلان للإعلانات الآلية المدمجة مع المحتوى

عند عرض إعلانات آلية مدمجة مع المحتوى، يجب عرض إحالة الإعلان للدلالة على أن المشاهدة هي إعلان. اطّلِع على مزيد من المعلومات في إرشادات السياسة.

مثال الرمز البرمجي

في ما يلي خطوات عرض إعلان مدمج مع المحتوى:

1. إنشاء مثيل لفئة NativeAdView
2. بالنسبة إلى كلّ مادة عرض إعلان يتمّ عرضها:
   1. تعبئة عرض مادة العرض بمادة العرض في عنصر الإعلان.
   2. سجِّل عرض مواد العرض مع الفئة ViewGroup.
3. سجِّل MediaView إذا كان تنسيق إعلانك المدمج مع المحتوى يتضمن مادة عرض وسائط كبيرة.
4. سجِّل عنصر الإعلان باستخدام الفئة ViewGroup.

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

Java

private void displayNativeAd(ViewGroup parent, NativeAd ad) {

    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    NativeAdView adView = (NativeAdView) inflater
            .inflate(R.layout.ad_layout_file, parent);

    // Locate the view that will hold the headline, set its text, and call the
    // NativeAdView's setHeadlineView method to register it.
    TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
    headlineView.setText(ad.getHeadline());
    adView.setHeadlineView(headlineView);

    ...
    // Repeat the above process for the other assets in the NativeAd
    // using additional view objects (Buttons, ImageViews, etc).
    ...

    // If the app is using a MediaView, it should be
    // instantiated and passed to setMediaView. This view is a little different
    // in that the asset is populated automatically, so there's one less step.
    MediaView mediaView = (MediaView) adView.findViewById(R.id.ad_media);
    adView.setMediaView(mediaView);

    // Call the NativeAdView's setNativeAd method to register the
    // NativeAdObject.
    adView.setNativeAd(ad);

    // Ensure that the parent view doesn't already contain an ad view.
    parent.removeAllViews();

    // Place the AdView into the parent.
    parent.addView(adView);
}

Kotlin

fun displayNativeAd(parent: ViewGroup, ad: NativeAd) {

    // Inflate a layout and add it to the parent ViewGroup.
    val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
            as LayoutInflater
    val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView

    // Locate the view that will hold the headline, set its text, and use the
    // NativeAdView's headlineView property to register it.
    val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
    headlineView.text = ad.headline
    adView.headlineView = headlineView

    ...
    // Repeat the above process for the other assets in the NativeAd using
    // additional view objects (Buttons, ImageViews, etc).
    ...

    val mediaView = adView.findViewById<MediaView>(R.id.ad_media)
    adView.mediaView = mediaView

    // Call the NativeAdView's setNativeAd method to register the
    // NativeAdObject.
    adView.setNativeAd(ad)

    // Ensure that the parent view doesn't already contain an ad view.
    parent.removeAllViews()

    // Place the AdView into the parent.
    parent.addView(adView)
}

فيما يلي المهام الفردية:

1. تضخيم التصميم

   Java

   LayoutInflater inflater = (LayoutInflater) parent.getContext()
           .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
   NativeAdView adView = (NativeAdView) inflater
           .inflate(R.layout.ad_layout_file, parent);
   

   Kotlin

   val inflater = parent.getContext().getSystemService(Context.LAYOUT_INFLATER_SERVICE)
           as LayoutInflater
   val adView = inflater.inflate(R.layout.ad_layout_file, parent) as NativeAdView
   

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

2. تعبئة مشاهدات مواد العرض وتسجيلها

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

   Java

   TextView headlineView = adView.findViewById<TextView>(R.id.ad_headline);
   headlineView.setText(ad.getHeadline());
   adView.setHeadlineView(headlineView);
   

   Kotlin

   val headlineView = adView.findViewById<TextView>(R.id.ad_headline)
   headlineView.text = ad.headline
   adView.headlineView = headlineView
   

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

3. التعامل مع النقرات

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

   تعالج حزمة تطوير البرامج (SDK) النقرات على مواد عرض مشاهدة الإعلانات طالما تمت تعبئة مشاهدات مواد العرض وتسجيلها بالشكل الصحيح، كما هو موضَّح في القسم السابق.

   في ما يلي مثال يستخدم مستمع الإعلانات لمراقبة أحداث النقر:

   Java

   AdLoader adLoader = new AdLoader.Builder(context, "/6499/example/native")
       ...
       .withAdListener(new AdListener() {
           @Override
           public void onAdFailedToLoad(LoadAdError adError) {
               // Handle the failure by logging, altering the UI, and so on.
           }
           @Override
           public void onAdClicked() {
               // Log the click event or other custom behavior.
           }
       })
       .build();
   

   Kotlin

   val adLoader = AdLoader.Builder(this, "/6499/example/native")
       ...
       .withAdListener(object : AdListener() {
           override fun onAdFailedToLoad(adError: LoadAdError) {
               // Handle the failure by logging, altering the UI, and so on.
           }
       })
       .build()
   

4. تسجيل منصة MediaView

   يلزمك استخدام مادة عرض MediaView بدلاً من مادة عرض ImageView إذا كنت تريد تضمين مادة عرض صورة رئيسية في تنسيق إعلانك المدمج مع المحتوى.

   MediaView هي مادة عرض خاصة من النوع View مصمَّمة لعرض مادة عرض الوسائط الرئيسية، سواء كانت فيديو أو صورًا.

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

   Java

   MediaView mediaView = adView.findViewById(R.id.ad_media);
   adView.setMediaView(mediaView);
   

   Kotlin

   adView.mediaView = adView.findViewById<MediaView>(R.id.ad_media)
   

   كما هو الحال مع جميع مشاهدات مواد العرض، يجب تعبئة محتوى عرض الوسائط. يتم ذلك باستخدام الإجراء getMediaContent() لاسترداد محتوى الوسائط الذي يمكن تمريره إلى MediaView. إليك مقتطف رمز يُعيِّن محتوى الوسائط لعرض الوسائط:

   Java

   mediaView.setMediaContent(nativeAd.getMediaContent());
   

   Kotlin

   mediaView.mediaContent = nativeAd.mediaContent
   

   ImageScaleType

   تحتوي الفئة MediaView على السمة ImageScaleType عند عرض الصور. إذا كنت تريد تغيير حجم صورة ما في MediaView، يجب ضبط ImageView.ScaleType المقابل على طريقة setImageScaleType() من MediaView:

   Java

   mediaView.setImageScaleType(ImageView.ScaleType.CENTER_CROP);
   

   Kotlin

   mediaView.imageScaleType = ImageView.ScaleType.CENTER_CROP
   

   MediaContent

   وتحتوي الفئة MediaContent على البيانات ذات الصلة بمحتوى الوسائط للإعلان المدمج مع المحتوى، والذي يتم عرضه باستخدام الفئة MediaView. عند ضبط السمة mediaContent MediaView باستخدام مثيل MediaContent:

   • إذا كانت مادة عرض الفيديو متوفرة، يتم تخزينها مؤقتًا ويبدأ تشغيلها داخل MediaView. يمكنك معرفة ما إذا كانت مادة عرض الفيديو متوفرة من خلال الاطّلاع على hasVideoContent().

   • وإذا لم يكن الإعلان يتضمّن مادة عرض فيديو، يتم تنزيل مادة عرض mainImage ووضعها داخل MediaView بدلاً من ذلك.

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

5. تسجيل عنصر الإعلان المدمج مع المحتوى

   تسجِّل هذه الخطوة الأخيرة كائن الإعلان المدمج مع المحتوى في طريقة العرض المسؤولة عن عرضه:

   Java

   adView.setNativeAd(ad);
   

   Kotlin

   adView.setNativeAd(ad)
   

إتلاف الإعلان

عند الانتهاء من عرض إعلانك المدمج مع المحتوى، يجب إتلافه حتى يتم تجميع محتوى غير صحيح على هذا الإعلان.

Java

nativeAd.destroy();
        .inflate(R.layout.ad_layout_file, parent);

Kotlin

nativeAd.destroy()

اختبار رمز الإعلان المدمج مع المحتوى

الإعلانات المُباعة مباشرةً

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

/6499/example/native

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

• العنوان (نصي)
• الصورة الرئيسية (صورة)
• الشرح (نص)

رقم تعريف نموذج الإعلان المدمج المخصص هو 10063170.

إعلانات إعادة التعبئة المدمجة مع المحتوى

تقتصر إعادة تعبئة Ad Exchange حاليًا على مجموعة محدّدة من الناشرين. لاختبار سلوك إعلانات إعادة التعبئة المدمجة مع المحتوى، استخدِم الوحدة الإعلانية التالية في "مدير الإعلانات":

/6499/example/native-backfill

تعرض هذه الصفحة نماذج إعلانات لتثبيت التطبيقات والمحتوى التي تتضمّن الإعلان المركّب على "خيارات الإعلان".

لا تنسَ تعديل الرمز للإشارة إلى أرقام تعريف النماذج والوحدات الإعلانية الفعلية قبل النشر.

أمثلة على GitHub

مثال على التنفيذ الكامل للإعلانات المدمجة مع المحتوى:

Java Kotlin

الخطوات التالية

يمكنك الاطّلاع على المواضيع التالية:

• خصوصية المستخدم
• الإعداد المحسَّن لحزمة تطوير البرامج (SDK) وتحميل الإعلانات (إصدار تجريبي)