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

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

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

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

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

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

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

• أكمِل دليل البدء.

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

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

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

ca-app-pub-3940256099942544/2247696110

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

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

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

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

إنشاء AdLoader

ملاحظة مهمة: عليك إجراء جميع طلبات البيانات إلى حزمة SDK لعرض الإعلانات للأجهزة الجوّالة في سلسلة المهام الرئيسية.

يوضّح الرمز البرمجي التالي كيفية إنشاء 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.
        }
    })
    .withNativeAdOptions(NativeAdOptions.Builder()
            // Methods in the NativeAdOptions.Builder class can be
            // used here to specify individual options settings.
            .build())
    .build()

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

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

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

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

لغة Java

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

Kotlin

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

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

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

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

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

loadAd()

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

لغة Java

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

Kotlin

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

loadAds()

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

لغة Java

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

Kotlin

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

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

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

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

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

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

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

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

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

في ما يلي مثال يوضّح كيفية التحقّق من isLoading() في callback 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() في الإعلانات المدمجة مع المحتوى المحمَّلة. يؤدي ذلك إلى تحرير موارد المستخدَمة ومنع تسرّب الذاكرة.

نقطة رئيسية: يجب استدعاء 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>

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

عرض إعلانك

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