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

اختيار النظام الأساسي: 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();

Kotlin

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

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

استبدِل 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();

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

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

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

اتّصِل بالرقم 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();

Kotlin

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

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

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

يوضّح هذا القسم بالتفصيل كيفية تحديد موضع التراكب 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();

Kotlin

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

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

طريقة العرض المخصّصة "خيارات الإعلان"

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

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

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

جافا

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

Kotlin

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

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

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

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

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

اتّصِل بالرقم 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();

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

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

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

اتّصِل بالرقم 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();

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

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

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

جافا

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

Kotlin

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

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

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

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

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

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

اتّصِل بـ 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);

Kotlin

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

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

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

عند تسجيل نقرة بإيماءة التمرير السريع، يستدعي 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();

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

الوساطة

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