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

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

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

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

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

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

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

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

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

ca-app-pub-3940256099942544/2247696110

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

لمزيد من المعلومات عن آلية عمل الإعلانات التجريبية لحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة، اطّلِع على إعلانات تجريبية.

جارٍ تحميل الإعلانات

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

إنشاء أداة AdLoader

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

لغة Java

AdLoader adLoader = new AdLoader.Builder(context, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(NativeAd nativeAd) {
            // Show the ad.
        }
    })
    .withAdListener(new AdListener() {
        @Override
        public void onAdFailedToLoad(LoadAdError adError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(new NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { ad : NativeAd ->
        // Show the ad.
    }
    .withAdListener(object : AdListener() {
        override fun onAdFailedToLoad(adError: LoadAdError) {
            // Handle the failure by logging, altering the UI, and so on.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

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

إعداد Adالاستماعer باستخدام AdLoader (اختياري)

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

لغة Java

.withAdListener(new AdListener() {
    // AdListener callbacks can be overridden here.
})

Kotlin

.withAdListener(object : AdListener() {
    // AdListener callbacks can be overridden here.
})

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

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

loadAd()

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

لغة Java

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

Kotlin

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

loadAds()

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

لغة Java

adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

adLoader.loadAds(AdRequest.Builder().build(), 3)

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

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

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

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

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

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

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

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

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

لغة Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading()) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }
}).build();
adLoader.loadAds(new AdRequest.Builder().build(), 3);

Kotlin

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd {
        ...
        // some code that displays the ad.
        ...
        if (adLoader.isLoading) {
            // The AdLoader is still loading ads.
            // Expect more adLoaded or onAdFailedToLoad callbacks.
        } else {
            // The AdLoader has finished loading ads.
        }
    }.build()
adLoader.loadAds(AdRequest.Builder().build(), 3)

مراجع الإصدار

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

تأكّد من محو جميع المراجع البالغ عددها NativeAd باستخدام طريقة onDestroy() الخاصة بنشاطك.

في رد اتصال onNativeAdLoaded، تأكد من محو أي إعلانات مدمجة مع المحتوى سيتم إزالتها.

يمكنك أيضًا التحقّق من الأمر مرة أخرى من خلال تحديد ما إذا كان قد تم محو النشاط، وفي هذه الحالة، يمكنك الاتصال بـ "destroy()" على الإعلان المعروض والعودة على الفور:

لغة Java

final AdLoader adLoader = new AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
        .forNativeAd(new NativeAd.OnNativeAdLoadedListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed()` is a method on Activity.
        if (isDestroyed()) {
            nativeAd.destroy();
            return;
        }
        ...
    }
}).build();

Kotlin

lateinit var adLoader: AdLoader
...
adLoader = AdLoader.Builder(this, "ca-app-pub-3940256099942544/2247696110")
    .forNativeAd { nativeAd ->
        // If this callback occurs after the activity is destroyed, you
        // must call destroy and return or you may get a memory leak.
        // Note `isDestroyed` is a method on Activity.
        if (isDestroyed) {
            nativeAd.destroy()
            return@forNativeAd
        }
        ...
    }.build()

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

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

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

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

  • يجب عدم الاتصال بالرقم 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>

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

عرض إعلانك

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