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

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

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

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

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

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

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

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

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

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

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

ca-app-pub-3940256099942544/2247696110

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

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

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

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

إنشاء أداة تحميل إعلانات

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

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();

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()

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

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

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

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

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

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

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

loadAd()

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

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

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

loadAds()

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

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

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

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

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

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

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

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

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

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

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

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

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);

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() على الإعلان المعروض والعودة فورًا:

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();

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>

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

عرض إعلانك

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