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

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

عند تحميل إعلان مُدمَج مع المحتوى، تستدعي "حزمة تطوير البرامج (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>
         <!--Add remaining assets such as the image and media view.-->
    </LinearLayout>
</com.google.android.gms.ads.nativead.NativeAdView>

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

Java

AdLoader.Builder builder = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .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 assets into the ad view.
            populateNativeAdView(nativeAd, adView);
            frameLayout.removeAllViews();
            frameLayout.addView(adView);
        }
});

Kotlin

val builder = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // Assumes you have a placeholder FrameLayout in your View layout
        // (with ID fl_adplaceholder) where the ad is to be placed.
        val 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
        val adView = layoutInflater
                .inflate(R.layout.native_ad_layout, null) as NativeAdView
        // This method sets the assets into the ad view.
        populateNativeAdView(nativeAd, adView)
        frameLayout.removeAllViews()
        frameLayout.addView(adView)
    }

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

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

• تسجيل النقرات
• تسجيل مرّات الظهور عند ظهور أول بكسل على الشاشة
• عرض تراكب AdChoices

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

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

تحديد مصدر الإعلان

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

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

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

1. أنشئ مثيلاً للفئة NativeAdView.

2. لكلّ مادة عرض إعلان يتم عرضها:

   1. املأ عرض مادة العرض بمادة العرض في عنصر الإعلان.
   2. سجِّل عرض مادة العرض باستخدام فئة NativeAdView.

3. سجِّل العلامة MediaView إذا كان تنسيق الإعلان المدمج مع المحتوى يتضمّن مادة عرض وسائط كبيرة.

4. سجِّل عنصر الإعلان في الفئة NativeAdView.

في ما يلي مثال على دالة تعرِض 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 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 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) النقرات على مواد عرض مشاهدة الإعلان طالما أنّك تعاملت بشكل صحيح. وتعبئة مشاهدات مواد العرض وتسجيلها، كما هو موضّح في القسم السابق.

   للاستماع إلى النقرات، يجب تنفيذ رد اتصال SDK لإعلانات Google على الأجهزة الجوّالة:

   Java

   AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
       // ...
       .withAdListener(new AdListener() {
           @Override
           public void onAdFailedToLoad(LoadAdError adError) {
               // Handle the failure by logging.
           }
           @Override
           public void onAdClicked() {
               // Log the click event or other custom behavior.
           }
       })
       .build();
   

   Kotlin

   val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
       // ...
       .withAdListener(object : AdListener() {
           override fun onAdFailedToLoad(adError: LoadAdError) {
               // Handle the failure.
           }
           override fun onAdClicked() {
               // Log the click event or other custom behavior.
           }
       })
       .build()
   

4. تسجيل MediaView

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

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

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

   Java

    // Populate and register the media asset view.
    nativeAdView.setMediaView(nativeAdBinding.adMedia);
   

   Kotlin

    // Populate and register the media asset view.
    nativeAdView.mediaView = nativeAdBinding.adMedia
   

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

Kotlin

nativeAd.destroy()

أمثلة على GitHub

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

Java Kotlin

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

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

• خصوصية المستخدم

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