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

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

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

عند تحميل "إعلان مدمج مع المحتوى"، يتلقّى تطبيقك عنصرًا إعلانيًا يحتوي على مواد العرض، ويكون التطبيق مسؤولاً عن عرضها بدلاً من Google Mobile Ads SDK

بشكلٍ عام، يتألف عرض "الإعلانات المدمجة مع المحتوى" بنجاح من جزأين: تحميل إعلان باستخدام حزمة تطوير البرامج (SDK)، ثم عرض محتوى الإعلان في تطبيقك.

توضّح هذه الصفحة كيفية استخدام حزمة تطوير البرامج (SDK) لتحميل الإعلانات المدمجة مع المحتوى. ملاحظة: يمكنك الاطّلاع على مزيد من المعلومات عن "الإعلانات المدمجة مع المحتوى" في دليل الإعلانات المدمجة مع المحتوى.

يمكنك أيضًا الاطّلاع على بعض قصص نجاح العملاء: دراسة الحالة 1، دراسة الحالة 2.

المتطلبات الأساسية

قبل المتابعة، عليك إعداد Google Mobile Ads SDK.

الاختبار دائمًا باستخدام "الإعلانات التجريبية"

عند إنشاء تطبيقاتك واختبارها، تأكَّد من استخدام "الإعلانات التجريبية" بدلاً من الإعلانات الفعلية.

أسهل طريقة لتحميل "الإعلانات التجريبية" هي استخدام رقم تعريف الوحدة الإعلانية التجريبية المخصّص "للإعلانات المدمجة مع المحتوى" على Android:

ca-app-pub-3940256099942544/2247696110

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

للاطّلاع على تفاصيل Google Mobile Ads SDK "الإعلانات التجريبية"، يُرجى مراجعة مقالة تفعيل "الإعلانات التجريبية".

تحميل الإعلانات

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

إنشاء AdLoader

يوضّح الرمز التالي كيفية إنشاء AdLoader يمكنه تحميل "الإعلانات المدمجة مع المحتوى":

جافا

// It is recommended to call AdLoader.Builder on a background thread.
new Thread(
        () -> {
          AdLoader adLoader =
              new AdLoader.Builder(context, "AD_UNIT_ID")
                  .forNativeAd(
                      new NativeAd.OnNativeAdLoadedListener() {
                        @Override
                        // The native ad loaded successfully. You can show the ad.
                        public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {}
                      })
                  .withAdListener(
                      new AdListener() {
                        @Override
                        // The native ad load failed. Check the adError message for failure
                        // reasons.
                        public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
                      })
                  // Use the NativeAdOptions.Builder class to specify individual options
                  // settings.
                  .withNativeAdOptions(new NativeAdOptions.Builder().build())
                  .build();
        })
    .start();

Kotlin

// It is recommended to call AdLoader.Builder on a background thread.
CoroutineScope(Dispatchers.IO).launch {
  val adLoader =
    AdLoader.Builder(context, "AD_UNIT_ID")
      .forNativeAd { nativeAd ->
        // The native ad loaded successfully. You can show the ad.
      }
      .withAdListener(
        object : AdListener() {
          override fun onAdFailedToLoad(adError: LoadAdError) {
            // The native ad load failed. Check the adError message for failure reasons.
          }
        }
      )
      // Use the NativeAdOptions.Builder class to specify individual options settings.
      .withNativeAdOptions(NativeAdOptions.Builder().build())
      .build()
}

استبدِل AD_UNIT_ID برقم تعريف جهازك التجريبي.

طريقة forNativeAd() مسؤولة عن إعداد الـ AdLoader لشكل الـ NativeAd. عند تحميل إعلان بنجاح، يتم استدعاء طريقة onNativeAdLoaded() لكائن أداة الاستماع.

إعداد AdListener باستخدام AdLoader (اختياري)

عند إنشاء AdLoader، تضبط الدالة withAdListener عنصر AdListener لعامل التحميل. تأخذ الطريقة AdListener كمعلَمة وحيدة، وتتلقّى عمليات معاودة الاتصال من AdLoader عند وقوع أحداث دورة حياة الإعلان:

جافا

adLoaderBuilder.withAdListener(
    // Override AdListener callbacks here.
    new AdListener() {});

Kotlin

adLoaderBuilder.withAdListener(
  // Override AdListener callbacks here.
  object : AdListener() {}
)

طلب إدراج الإعلانات

بعد الانتهاء من إنشاء AdLoader، حان الوقت لاستخدامه لطلب الإعلانات. تتوفّر طريقتان لذلك: loadAd() وloadAds().

loadAd()

ترسِل هذه الطريقة طلبًا لعرض إعلان واحد.

جافا

adLoader.loadAd(new AdRequest.Builder().build());

Kotlin

adLoader.loadAd(AdRequest.Builder().build())

loadAds()

ترسِل هذه الطريقة طلبًا لعرض إعلانات متعدّدة (ما يصل إلى خمسة إعلانات):

جافا

// Load three native ads.
adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

// Load three native ads.
adLoader.loadAds(AdRequest.Builder().build(), 3)

تأخذ كلتا الطريقتَين كائنًا AdRequest كمعلَمة أولى. هذه هي فئة AdRequest نفسها التي تستخدمها إعلانات البانر والإعلانات البينية، ويمكنك استخدام طرق فئة AdRequest لإضافة معلومات الاستهداف، تمامًا كما تفعل مع أشكال الإعلانات الأخرى.

تحميل إعلانات متعدّدة (اختياري)

تأخذ طريقة loadAds() معلَمة إضافية: عدد الإعلانات التي يجب أن تحاول حزمة تطوير البرامج (SDK) تحميلها للطلب. يبلغ الحدّ الأقصى لهذا العدد خمسة، وليس من المضمون أن تعرض حزمة تطوير البرامج (SDK) العدد المطلوب من الإعلانات بالضبط.

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

لا تستخدِم طريقة loadAds() إذا كنت تستخدِم التوسّط، لأنّ طلبات عرض "الإعلانات المدمجة مع المحتوى" المتعدّدة لا تعمل مع أرقام تعريف الوحدات الإعلانية التي تم إعدادها للتوسّط.

عمليات معاودة الاتصال

بعد استدعاء loadAd()، يتم إجراء عملية معاودة اتصال واحدة بطرق المتتبِّع التي تم تحديدها سابقًا لعرض عنصر "الإعلان المدمج مع المحتوى" أو الإبلاغ عن خطأ.

بعد استدعاء loadAds()، يتم إجراء عمليات معاودة اتصال متعدّدة من هذا النوع (واحدة على الأقل، ولا يزيد عددها عن عدد الإعلانات المطلوبة). يجب أن تستدعي التطبيقات التي تطلب إعلانات متعدّدة AdLoader.isLoading() في عمليات معاودة الاتصال لتحديد ما إذا كانت عملية التحميل قد اكتملت.

في ما يلي مثال يوضّح كيفية التحقّق من isLoading() في عملية معاودة الاتصال onNativeAdLoaded():

جافا

adLoaderBuilder
    .forNativeAd(
        nativeAd -> {
          // This callback is invoked when a native ad is successfully loaded.
        })
    .build();

Kotlin

adLoaderBuilder
  .forNativeAd { nativeAd ->
    // This callback is invoked when a native ad is successfully loaded.
  }
  .build()

إلغاء حجز الموارد

احرِص على استخدام طريقة destroy() في "الإعلانات المدمجة مع المحتوى" التي تم تحميلها. يؤدي ذلك إلى إلغاء حجز الموارد المستخدَمة ويمنع تسرّب الذاكرة.

تأكَّد من إتلاف جميع مراجع NativeAd في طريقة onDestroy() لنشاطك.

في عملية معاودة الاتصال onNativeAdLoaded، احرِص على إتلاف أي "إعلانات مدمجة مع المحتوى" حالية سيتم إلغاء الإشارة إليها.

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

جافا

nativeAd.destroy();

Kotlin

nativeAd.destroy()

أفضل الممارسات

اتّبِع هذه القواعد عند تحميل الإعلانات.

  • يجب أن تخزّن التطبيقات التي تستخدِم "الإعلانات المدمجة مع المحتوى" في قائمة، قائمة الإعلانات مؤقتًا.

  • عند التخزين المؤقت للإعلانات، امحُ ذاكرة التخزين المؤقت وأعِد التحميل بعد ساعة واحدة.

  • لا تستدعِ loadAd() أو loadAds() على AdLoader إلى أن ينتهي تحميل الطلب الأول.

  • لا تخزِّن "الإعلانات المدمجة مع المحتوى" مؤقتًا إلا بالقدر اللازم. على سبيل المثال، عند التخزين المؤقت، لا تخزِّن مؤقتًا إلا الإعلانات التي تظهر على الشاشة على الفور. تستهلك "الإعلانات المدمجة مع المحتوى" استهلاكًا كبيرًا للذاكرة، ويؤدي تخزينها مؤقتًا بدون محوها إلى استخدام مفرط للذاكرة.

  • أتلِف "الإعلانات المدمجة مع المحتوى" عندما لا يعود هناك حاجة إليها.

تسريع الأجهزة للإعلانات الفيديو

لكي تظهر إعلانات الفيديو بنجاح في طرق عرض "الإعلانات المدمجة مع المحتوى"، يجب تفعيل ميزة "تسريع الأجهزة".

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

تفعيل ميزة "تسريع الأجهزة"

إذا كان تطبيقك لا يعمل بشكلٍ صحيح عند تفعيل ميزة "تسريع الأجهزة" على مستوى العالم، يمكنك التحكّم فيها للأنشطة الفردية أيضًا. لتفعيل ميزة "تسريع الأجهزة" أو إيقافها، استخدِم السمة android:hardwareAccelerated لعنصرَي <application> و<activity> في ملف AndroidManifest.xml. يُفعِّل المثال التالي ميزة "تسريع الأجهزة" للتطبيق بأكمله، ولكنّه يوقفها لنشاط واحد:

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

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

عرض إعلانك

بعد تحميل إعلان، ما عليك سوى عرضه للمستخدمين. انتقِل إلى دليل "الإعلانات المدمجة مع المحتوى (متقدم) guide" لمعرفة كيفية ذلك.