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

اختيار النظام الأساسي: Android iOS Flutter Unity

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

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

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

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

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

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

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

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

أسهل طريقة لتحميل الإعلانات التجريبية هي استخدام معرّف وحدة الإعلانات التجريبية المخصّص للإعلانات المدمجة مع المحتوى على 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.
        }
    })
    .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 كمعلَمة منفردة، وتتلقّى عمليات ردّ الاتصال من 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()

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

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() في دالة الاستدعاء 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 callback، احرص على إيقاف أي إعلانات أصلية حالية سيتم إلغاء ربطها.

يجب أيضًا التحقّق مما إذا تم إيقاف النشاط، وفي حال حدوث ذلك، يجب استدعاء 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>

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

عرض إعلانك

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