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

اختيار النظام الأساسي: 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();
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 برقم تعريف جهازك الاختباري.

طريقة 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().

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() على "الإعلانات المدمجة مع المحتوى" التي تم تحميلها. يؤدي ذلك إلى إلغاء حجز الموارد المستخدَمة ويمنع تسرّب الذاكرة.

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

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

هناك عملية تحقّق أساسية أخرى وهي ما إذا تم إتلاف النشاط، وفي هذه الحالة، استدعِ 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

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

عرض إعلانك

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