تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الإعلانات الأصلية

الإعلانات المدمجة مع المحتوى هي مواد عرض الإعلانات التي تُقدَّم للمستخدمين من خلال مكوِّنات واجهة المستخدم الأصلية على النظام الأساسي. ويتم عرضها باستخدام أنواع المشاهدات نفسها التي يتم من خلالها إنشاء تنسيقاتك، ويمكن تنسيقها لتتناسب مع التصميم المرئي لتجربة المستخدم في المكان الذي يعيش فيه. وهذا يعني أنه عند تحميل إعلان مدمج مع المحتوى، يتلقّى تطبيقك عنصرًا NativeAd يحتوي على مواد العرض الخاصة به، وأن التطبيق (بدلاً من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة) هو المسؤول عن عرضها.

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

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

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

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

التنفيذ

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

إنشاء AdAder

يوضّح الرمز التالي كيفية إنشاء 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()

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

تكون الطريقة الأولى أعلاه مسؤولة عن تحضير AdLoader للتنسيق NativeAd:

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

عندما يقدّم AdLoader طلب إعلان، تختار Google الإعلان الذي يحقق أعلى أرباح من الناشر ويعرضها.

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

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

بعد طلب إلى 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()

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

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

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

ca-app-pub-3940256099942544/2247696110

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

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

حالات طلب الإعلانات

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

تسريع الأجهزة لإعلانات الفيديو

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

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

تفعيل ميزة تسريع الأجهزة

إذا لم يكن تطبيقك يعمل بشكل صحيح مع تفعيل ميزة "تسريع الأجهزة" على مستوى العالم، يمكنك التحكُّم فيها للأنشطة الفردية أيضًا. لتفعيل ميزة تسريع الأجهزة أو إيقافها، يمكنك استخدام السمة 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>

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

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

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

placeholder1 l10n

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

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

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

التنفيذ

إنشاء AdAder

يوضّح الرمز التالي كيفية إنشاء 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()

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

تكون الطريقة الأولى أعلاه مسؤولة عن تحضير AdLoader للتنسيق NativeAd:

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

عندما يقدّم AdLoader طلب إعلان، تختار Google الإعلان الذي يحقق أعلى أرباح من الناشر ويعرضها.

إعداد 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)

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

إليك مثال يوضّح كيفية التحقق من 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)

إلغاء حجز الموارد

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

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

لغة 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()

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

ca-app-pub-3940256099942544/2247696110

حالات طلب الإعلانات

تسريع الأجهزة لإعلانات الفيديو

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

تفعيل ميزة تسريع الأجهزة

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