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

اختيار النظام الأساسي: 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 اختيار الزاوية التي سيتم عرض رمز "خيارات الإعلان" فيها.

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

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

  • إذا تم ضبط هذه القيمة، يتم وضع "خيارات الإعلان" في الموضع المخصّص المطلوب.

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

جافا

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

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

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

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

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

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

يمكنك استدعاء 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()

الوساطة

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