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

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

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

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

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

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

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

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

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

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

استدعِ NativeAdRequest.Builder.setMediaAspectRatio() باستخدام قيمة NativeAd.NativeMediaAspectRatio.

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

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

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

Kotlin

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build()

جافا

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build();

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

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

الاتصال بـ NativeAdRequest.Builder.disableImageDownloading()

• تكون عناصر التحكّم في تنزيل الصور غير مفعّلة تلقائيًا.

• عند إيقاف هذا الخيار، يملأ GMA Next-Gen SDK كلاً من الصورة ومعرّف الموارد المنتظم (URI) نيابةً عنك.

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

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

Kotlin

val adRequest = NativeAdRequest.Builder(
    "ca-app-pub-3940256099942544/2247696110",
    listOf(NativeAd.NativeAdType.NATIVE))
    .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
    .disableImageDownloading()
    .build()

val adCallback: NativeAdLoaderCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      // Get the image uri.
      val imageUri = nativeAd.image?.uri
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

جافا

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .disableImageDownloading()
  .build();

NativeAdLoaderCallback adLoaderCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      // Get the image uri.
      Uri imageUri = nativeAd.getImage().getUri();
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

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

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

• تكون عناصر التحكّم في حمولة الصور غير مفعَّلة تلقائيًا.

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

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

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

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

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

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

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

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

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

• في حال ضبط هذا الخيار، يتم وضع AdChoices في الموضع المخصّص حسب الطلب.

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

Kotlin

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build()

جافا

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build();

عرض مخصّص لـ AdChoices

تحذير: الوصول إلى هذه الميزة محدود. لطلب الوصول، يُرجى التواصل مع مدير حسابك.

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

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

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

Kotlin

override fun onNativeAdLoaded(nativeAd: NativeAd) {
  val nativeAdView = NativeAdView(applicationContext)
  val adChoicesView = AdChoicesView(this)
  nativeAdView.adChoicesView = adChoicesView
}

جافا

public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
  NativeAdView nativeAdView = new NativeAdView(getApplicationContext());
  AdChoicesView adChoicesView = new AdChoicesView(this);
  nativeAdView.setAdChoicesView(adChoicesView);
}

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

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

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

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

استدعِ VideoOptions.Builder.setStartMuted() باستخدام قيمة boolean واستدعِ NativeAdOptions.Builder.setVideoOptions().

• يتم تفعيل سلوك "بدء الاجتماع بكتم الصوت" تلقائيًا.

• عند إيقاف هذا الخيار، يطلب تطبيقك بدء الفيديو بالصوت.

• عند تفعيل هذا الخيار، يطلب تطبيقك أن يبدأ الفيديو بدون صوت.

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

Kotlin

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

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

جافا

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

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

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

تحذير: الوصول إلى هذه الميزة محدود. لطلب الوصول، يُرجى التواصل مع مدير حسابك.

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

لضبط حالة كتم الصوت عند بدء الإعلانات، استخدِم الدالة VideoOptions.Builder.setCustomControlsRequested().

• تكون عناصر التحكّم المخصّصة في التشغيل غير مفعّلة تلقائيًا.

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

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

VideoOptions.Builder.setCustomControlsRequested().

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

Kotlin

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

val adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

جافا

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

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

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

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

Kotlin

  val adCallback: NativeAdLoaderCallback =
    object : NativeAdLoaderCallback {
      override fun onNativeAdLoaded(nativeAd: NativeAd) {
        val mediaContent = nativeAd.mediaContent;
        if (mediaContent != null) {
          val videoController = mediaContent.videoController;
          val canShowCustomControls = videoController?.isCustomControlsEnabled();
        }
      }
    };

جافا

NativeAdLoaderCallback adCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      MediaContent mediaContent = nativeAd.getMediaContent();
      if (mediaContent != null) {
        VideoController videoController = mediaContent.getVideoController();
        if (videoController != null) {
          boolean canShowCustomControls = videoController.isCustomControlsEnabled();
        }
      }
    }
  };

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

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

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

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

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

تحذير: الوصول إلى هذه الميزة محدود. لطلب الوصول، يُرجى التواصل مع مدير حسابك.

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

استدعِ NativeAdRequest.Builder.enableCustomClickGestureDirection() باستخدام NativeAd.SwipeGestureDirection وقيمة boolean.

• تكون إيماءات النقر المخصّصة غير مفعّلة تلقائيًا.

• وعند إيقافها، يتيح تطبيقك سلوك النقر العادي.

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

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

Kotlin

val adRequest =
  NativeAdRequest.Builder(AD_UNIT_ID, listOf(NativeAdType.NATIVE))
    .enableCustomClickGestureDirection(
      SwipeGestureDirection.RIGHT,
      /* customClickGestureAllowTaps= */ true,
    )
    .build()

جافا

NativeAdRequest adRequest =
    new NativeAdRequest.Builder(AD_UNIT_ID, List.of(NativeAdType.NATIVE))
        .enableCustomClickGestureDirection(
            SwipeGestureDirection.RIGHT, /* customClickGestureAllowTaps= */ true)
        .build();

تحذير: إذا لم تكن إيماءات النقر المخصّصة مفعَّلة في حسابك، ستؤدي طلبات الإعلانات إلى عدم تعبئة المساحة الإعلانية.

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

للاستماع إلى أحداث إيماءات التمرير السريع، يمكنك استدعاء NativeAd.setAdEventCallback() باستخدام NativeAdEventCallback وتنفيذ طريقة onAdSwipeGestureClicked().

Kotlin

  val adCallback: NativeAdLoaderCallback =
    object : NativeAdLoaderCallback {
      override fun onNativeAdLoaded(nativeAd: NativeAd) {
        // Implement the onAdSwipeGestureClicked() method.
        val nativeAdCallback: NativeAdEventCallback = object : NativeAdEventCallback {
          override fun onAdSwipeGestureClicked() {
            // A swipe gesture click has occurred.
          }
        }
      }
    }
  // Load the native ad with the ad request and callback.
  NativeAdLoader.load(adRequest, adCallback)

جافا

  NativeAdLoaderCallback adCallback =
    new NativeAdLoaderCallback() {
      @Override
      public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
        // Implement the onAdSwipeGestureClicked() method.
        NativeAdEventCallback nativeAdCallback = new NativeAdEventCallback() {
          @Override
          public void onAdSwipeGestureClicked() {
            // A swipe gesture click has occurred.
          }
        };
      }
    };
  // Load the native ad with the ad request and callback.
  NativeAdLoader.load(adRequest, adCallback);

الوساطة

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