حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" في وضع الصيانة للحصول على آخر التحديثات والميزات، عليك migrate وإعداد "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة".

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

ضبط الميزات المتقدّمة

اختيار النظام الأساسي: Android iOS Android (قديم)

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

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

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

عناصر التحكّم في مواد العرض

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

عناصر التحكّم المفضّلة في نسبة العرض إلى الارتفاع للوسائط

تتيح لك عناصر التحكّم في نسبة العرض إلى الارتفاع للوسائط تحديد نسبة العرض إلى الارتفاع المفضّلة لمواد الإعلان الإبداعية.

استدعِ NativeAdOptions.Builder.setMediaAspectRatio() باستخدام قيمة NativeAdOptions.MediaAspectRatio.

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

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

جافا

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder()
        .setMediaAspectRatio(NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
        .build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build();NativeAdOptionsSnippets.java

Kotlin

val nativeAdOptions =
  NativeAdOptions.Builder()
    .setMediaAspectRatio(NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
    .build()

val loader = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build()NativeAdOptionsSnippets.kt

استبدِل AD_UNIT_ID برقم تعريف وحدتك الإعلانية.

التحكّم في تنزيل الصور

يتيح لك عنصر التحكّم في تنزيل الصور تحديد ما إذا كانت حزمة تطوير البرامج (SDK) ستعرض مواد عرض الصور أو معرّفات الموارد المنتظمة (URI) فقط.

يمكنك الاتصال بالرقم NativeAdOptions.Builder.setReturnUrlsForImageAssets() باستخدام قيمة boolean.

تكون عناصر التحكّم في تنزيل الصور غير مفعّلة تلقائيًا.
عند إيقاف هذا الخيار، يملأ Google Mobile Ads SDK (Legacy) كلاً من الصورة ومعرّف الموارد المنتظم (URI) نيابةً عنك.
عند تفعيل هذه الميزة، تملأ حزمة تطوير البرامج (SDK) معرّف الموارد المنتظم (URI) فقط، ما يتيح لك تنزيل الصور الفعلية وفقًا لتقديرك.

يوجّه المثال التالي حزمة تطوير البرامج (SDK) إلى عرض معرّف الموارد المنتظم (URI) فقط.

جافا

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder().setReturnUrlsForImageAssets(true).build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID")
        .withNativeAdOptions(nativeAdOptions)
        .forNativeAd(
            nativeAd -> {
              List<Uri> imageUris = new ArrayList<>();
              for (Image image : nativeAd.getImages()) {
                imageUris.add(image.getUri());
              }
            })
        .build();NativeAdOptionsSnippets.java

Kotlin

val nativeAdOptions = NativeAdOptions.Builder().setReturnUrlsForImageAssets(true).build()

val loader =
  AdLoader.Builder(context, "AD_UNIT_ID")
    .withNativeAdOptions(nativeAdOptions)
    .forNativeAd { nativeAd ->
      val imageUris = nativeAd.images.mapNotNull { it.uri }
    }
    .build()NativeAdOptionsSnippets.kt

عناصر التحكّم في حمولة الصور

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

يمكنك الاتصال بالرقم NativeAdOptions.Builder.setRequestMultipleImages() باستخدام قيمة boolean.

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

يوجّه المثال التالي حزمة تطوير البرامج (SDK) لعرض مواد عرض صور متعددة.

جافا

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder().setRequestMultipleImages(true).build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build();NativeAdOptionsSnippets.java

Kotlin

val nativeAdOptions = NativeAdOptions.Builder().setRequestMultipleImages(true).build()

val loader = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build()NativeAdOptionsSnippets.kt

مواضع "خيارات الإعلان"

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

عناصر التحكّم في موضع AdChoices

تتيح لك عناصر التحكّم في موضع AdChoices اختيار الزاوية التي تريد عرض رمز "خيارات الإعلان" فيها.

استدعِ NativeAdOptions.Builder.setAdChoicesPlacement() باستخدام قيمة NativeAdOption.AdChoicesPlacement.

في حال عدم ضبطه، يتم ضبط موضع رمز "خيارات الإعلان" على أعلى يسار الصفحة.
في حال ضبط هذا الخيار، يتم وضع AdChoices في الموضع المخصّص حسب الطلب.

يوضّح المثال التالي كيفية ضبط موضع مخصّص لصورة AdChoices.

جافا

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder()
        .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
        .build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build();NativeAdOptionsSnippets.java

Kotlin

val nativeAdOptions =
  NativeAdOptions.Builder()
    .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
    .build()

val loader = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build()NativeAdOptionsSnippets.kt

عرض مخصّص لـ AdChoices

تتيح لك ميزة العرض المخصّص لـ "خيارات الإعلان" وضع رمز "خيارات الإعلان" في موقع مخصّص. يختلف ذلك عن عناصر التحكّم في موضع AdChoices التي تسمح فقط بتحديد إحدى الزوايا الأربع.

استدعِ NativeAdView.setAdChoicesView() باستخدام قيمة AdChoicesView.

يوضّح المثال التالي كيفية ضبط عرض مخصّص لرمز "خيارات الإعلان"، مع عرض رمز "خيارات الإعلان" داخل AdChoicesView.

جافا

NativeAdView nativeAdView = new NativeAdView(context);
AdChoicesView adChoicesView = new AdChoicesView(context);
nativeAdView.setAdChoicesView(adChoicesView);NativeAdOptionsSnippets.java

Kotlin

val nativeAdView = NativeAdView(context)
val adChoicesView = AdChoicesView(context)
nativeAdView.adChoicesView = adChoicesViewNativeAdOptionsSnippets.kt

عناصر التحكُّم في الفيديو

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

بدء سلوك كتم الصوت

يتيح لك سلوك "بدء التشغيل مع كتم الصوت" إيقاف الصوت الأولي للفيديو أو تفعيله.

يمكنك الاتصال بالرقم VideoOptions.Builder.setStartMuted() باستخدام قيمة boolean.

يتم تفعيل سلوك "بدء الاجتماع بكتم الصوت" تلقائيًا.
عند إيقاف هذا الخيار، يطلب تطبيقك بدء الفيديو بالصوت.
عند تفعيل هذا الخيار، يطلب تطبيقك أن يبدأ الفيديو بدون صوت.

يوضّح المثال التالي كيفية بدء الفيديو مع تفعيل الصوت.

جافا

VideoOptions videoOptions = new VideoOptions.Builder().setStartMuted(false).build();

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder().setVideoOptions(videoOptions).build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build();NativeAdOptionsSnippets.java

Kotlin

val videoOptions = VideoOptions.Builder().setStartMuted(false).build()

val nativeAdOptions = NativeAdOptions.Builder().setVideoOptions(videoOptions).build()

val loader = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build()NativeAdOptionsSnippets.kt

عناصر التحكّم المخصّصة في التشغيل

يتيح لك ذلك طلب عناصر تحكّم مخصّصة في إدخال الفيديو لتشغيل الفيديو أو إيقافه مؤقتًا أو كتم صوته.

يمكنك الاتصال بالرقم VideoOptions.Builder.setCustomControlsRequested() باستخدام قيمة boolean.

تكون عناصر التحكّم المخصّصة في التشغيل غير مفعّلة تلقائيًا.
وعند إيقافها، سيعرض الفيديو عناصر التحكّم في الإدخال التي تعرضها حزمة تطوير البرامج (SDK).

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

VideoController.

يوضّح المثال التالي كيفية طلب فيديو يتضمّن عناصر تحكّم مخصّصة في التشغيل.

جافا

VideoOptions videoOptions = new VideoOptions.Builder().setCustomControlsRequested(true).build();

NativeAdOptions nativeAdOptions =
    new NativeAdOptions.Builder().setVideoOptions(videoOptions).build();

AdLoader loader =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build();NativeAdOptionsSnippets.java

Kotlin

val videoOptions = VideoOptions.Builder().setCustomControlsRequested(true).build()

val nativeAdOptions = NativeAdOptions.Builder().setVideoOptions(videoOptions).build()

val loader = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(nativeAdOptions).build()NativeAdOptionsSnippets.kt

التحقّق من تفعيل عناصر التحكّم المخصّصة

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

جافا

MediaContent mediaContent = nativeAd.getMediaContent();
if (mediaContent != null) {
  VideoController videoController = mediaContent.getVideoController();
  boolean canShowCustomControls = videoController.isCustomControlsEnabled();
}NativeAdOptionsSnippets.java

Kotlin

val mediaContent = nativeAd.mediaContent
if (mediaContent != null) {
  val videoController = mediaContent.videoController
  val canShowCustomControls = videoController.isCustomControlsEnabled
}NativeAdOptionsSnippets.kt

عرض عناصر تحكّم مخصّصة في الفيديو

يمكنك عرض عناصر تحكّم مخصّصة في الفيديو باتّباع أفضل الممارسات التالية:

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

إيماءات النقر المخصّصة

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

يمكنك استدعاء NativeAdOptions.Builder.enableCustomClickGestureDirection() باستخدام NativeAdOptions.SwipeGestureDirection وboolean للإشارة إلى ما إذا كان سيتم السماح بالنقرات كعمليات نقر.

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

ينفّذ المثال التالي إيماءة تمرير سريع مخصّصة إلى اليمين ويحافظ على سلوك النقر العادي.

جافا

NativeAdOptions adOptions =
    new NativeAdOptions.Builder()
        .enableCustomClickGestureDirection(
            NativeAdOptions.SWIPE_GESTURE_DIRECTION_RIGHT, /* tapsAllowed= */ true)
        .build();

// ca-app-pub-3940256099942544/2247696110 is a sample ad unit ID that has custom click
// gestures enabled.
AdLoader.Builder builder =
    new AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(adOptions);NativeAdOptionsSnippets.java

Kotlin

val adOptions =
  NativeAdOptions.Builder()
    .enableCustomClickGestureDirection(NativeAdOptions.SWIPE_GESTURE_DIRECTION_RIGHT, true)
    .build()

val builder = AdLoader.Builder(context, "AD_UNIT_ID").withNativeAdOptions(adOptions)NativeAdOptionsSnippets.kt

الاستماع إلى أحداث إيماءات التمرير السريع

عند تسجيل نقرة من خلال إيماءة التمرير السريع، تستدعي Google Mobile Ads SDK (Legacy) طريقة onAdSwipeGestureClicked() في AdListener، بالإضافة إلى طريقة onAdClicked() الحالية.

جافا

AdLoader adLoader =
    new AdLoader.Builder(context, AD_UNIT_ID)
        .withAdListener(
            new AdListener() {
              // Called when a swipe gesture click is recorded.
              @Override
              public void onAdSwipeGestureClicked() {
                // Called when a swipe gesture click is recorded.
                Log.d(TAG, "A swipe gesture click has occurred.");
              }

              @Override
              public void onAdClicked() {
                // Called when a swipe gesture click or a tap click is recorded, as
                // configured in NativeAdOptions.
                Log.d(TAG, "A swipe gesture click or a tap click has occurred.");
              }
            })
        .build();NativeAdOptionsSnippets.java

Kotlin

val adLoader =
  AdLoader.Builder(context, AD_UNIT_ID)
    .withAdListener(
      object : AdListener() {
        override fun onAdSwipeGestureClicked() {
          // Called when a swipe gesture click is recorded.
          Log.d(TAG, "A swipe gesture click has occurred.")
        }

        override fun onAdClicked() {
          // Called when a swipe gesture click or a tap click is recorded, as
          // configured in NativeAdOptions.
          Log.d(TAG, "A swipe gesture click or a tap click has occurred.")
        }
      }
    )
    .build()NativeAdOptionsSnippets.kt

الوساطة

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

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

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

عناصر التحكّم في مواد العرض

عناصر التحكّم المفضّلة في نسبة العرض إلى الارتفاع للوسائط

جافا

Kotlin

التحكّم في تنزيل الصور

جافا

Kotlin

عناصر التحكّم في حمولة الصور

جافا

Kotlin

مواضع "خيارات الإعلان"

عناصر التحكّم في موضع AdChoices

جافا

Kotlin

عرض مخصّص لـ AdChoices

جافا

Kotlin

عناصر التحكُّم في الفيديو

بدء سلوك كتم الصوت

جافا

Kotlin

عناصر التحكّم المخصّصة في التشغيل

جافا

Kotlin

التحقّق من تفعيل عناصر التحكّم المخصّصة

جافا

Kotlin

عرض عناصر تحكّم مخصّصة في الفيديو

إيماءات النقر المخصّصة

جافا

Kotlin

الاستماع إلى أحداث إيماءات التمرير السريع

جافا

Kotlin

الوساطة

ضبط الميزات المتقدّمة