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

اختيار النظام الأساسي: Android iOS Flutter Unity Android (الإصدار القديم)

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

عند تحميل إعلان مدمج مع المحتوى، يتلقّى تطبيقك عنصر إعلان يتضمّن مواد العرض الخاصة به، ويكون التطبيق هو المسؤول عن عرضها، وليس Google Mobile Ads SDK (Legacy).

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

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

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

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

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

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

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

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

ca-app-pub-3940256099942544/2247696110

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

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

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

يتم تحميل "الإعلانات المدمجة مع المحتوى" باستخدام الفئة 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();
NativeAdSnippets.java

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()
}
NativeAdSnippets.kt

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

تحذير: لا ننصح بشدة بمحاولة تحميل إعلان جديد من خلال الطريقة onAdFailedToLoad(). إذا كان عليك تحميل إعلان من onAdFailedToLoad()، احرص على الحدّ من عدد محاولات إعادة تحميل الإعلان لتجنُّب طلبات عرض الإعلانات الفاشلة بشكل متواصل في حالات مثل محدودية الاتصال بالشبكة.

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

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

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

جافا

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

Kotlin

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

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

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

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

ملاحظة مهمة: لا تعمل طريقة loadAds() إلا مع "إعلانات Google". بالنسبة إلى الإعلانات المعروضة من خلال التوسّط، استخدِم loadAd() بدلاً من ذلك.

loadAd()

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

جافا

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

Kotlin

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

loadAds()

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

جافا

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

Kotlin

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

تستخدم كلتا الطريقتَين عنصر 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();
NativeAdSnippets.java

Kotlin

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

موارد الإصدار

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

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

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

في onNativeAdLoaded callback، احرص على إيقاف أي إعلانات مدمجة مع المحتوى حالية سيتم إلغاء ربطها.

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

جافا

nativeAd.destroy();
NativeAdSnippets.java

Kotlin

nativeAd.destroy()
NativeAdSnippets.kt

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

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

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

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

• لا تتصل بالرقم 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>
HardwareAccelerationSnippet.xml

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

عرض إعلانك

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