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

اختيار النظام الأساسي: Android Android iOS

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build()

جافا

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  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(
    "/21775744923/example/native",
    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(
  "/21775744923/example/native",
  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 اختيار الزاوية التي سيتم عرض رمز "خيارات الإعلان" فيها.

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

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

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

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

Kotlin

val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build()

جافا

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build();

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

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

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

يمكنك استدعاء 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(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

جافا

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

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  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(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

جافا

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

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  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 adOptions = NativeAdOptions
  .Builder()
  .enableCustomClickGestureDirection(
    /* swipeDirection */ NativeAdOptions.SWIPE_GESTURE_DIRECTION_RIGHT,
    /* tapsAllowed= */ true)
  .build();

// The following sample ad unit ID has been enabled for custom click gestures
// and can be used for testing.
val adRequest = NativeAdRequest.Builder(
  "/21775744923/example/native",
  listOf(NativeAd.NativeAdType.NATIVE))
  .withNativeAdOptions(adOptions)
  .build();

جافا

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

// The following sample ad unit ID has been enabled for custom click gestures
// and can be used for testing.
NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "/21775744923/example/native",
  List.of(NativeAd.NativeAdType.NATIVE))
  .withNativeAdOptions(adOptions)
  .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) تابعة لجهة خارجية للعرض لإعدادات اتجاهات النقر المخصّصة.