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

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

استخدام أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

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

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

تحميل أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

يشرح هذا الدليل كيفية تحميل أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة وعرضها.

تحميل "إعلان مخصص مدمج مع المحتوى"

مثل "الإعلانات المدمجة مع المحتوى"، يتم تحميل أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة باستخدام الفئة AdLoader:

جافا

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
            // Show the custom format and record an impression.
          }
        },
        new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
            // Handle the click action
          }
        })
    .forCustomFormatAd("12406343",
        new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
            // Show the custom format and record an impression.
          }
        },
        new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
            // Handle the click action
          }
        })
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
  .forCustomFormatAd(
    "12387226",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .forCustomFormatAd(
    "12406343",
    { customFormatAd ->
      // Show the custom format and record an impression.
    },
    { customFormatAd, s ->
      // Handle the click action
    })
  .build()

تضبط الطريقة forCustomFormatAd السمة AdLoader لطلب أشكال مخصّصة من "الإعلانات المدمجة مع المحتوى". يمكنك استدعاء الطريقة عدّة مرات لأرقام تعريف مختلفة للأشكال المخصّصة. تقبل الطريقة المَعلمات التالية:

رقم تعريف شكل "الإعلان المدمج مع المحتوى" المخصّص الذي يجب أن يطلبه AdLoader. يرتبط كل شكل من أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة بمعرّف. تحدّد هذه المَعلمة الشكل الذي يريد تطبيقك أن يطلبه من AdLoader.
‫OnCustomFormatAdLoadedListener يتم استدعاؤه عند تحميل إعلان بنجاح.
سمة اختيارية OnCustomClickListener يتم استدعاؤها عندما ينقر المستخدم على الإعلان. لمزيد من المعلومات عن هذا المستمع، يُرجى الاطّلاع على قسم "التعامل مع النقرات ومرّات الظهور".

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

رقم تعريف شكل "الإعلان المدمج مع المحتوى" المخصّص

يمكن العثور على معرّف الشكل المستخدَم لتحديد شكل إعلان مخصّص مدمج مع المحتوى في واجهة مستخدم "إدارة إعلانات Google" ضمن قسم مدمج مع المحتوى في القائمة المنسدلة العرض:

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

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

عرض أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

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

تتوفّر مواد العرض النصية ومواد عرض الصور من خلال دالّتَي الحصول getText() وgetImage() اللتين تستخدمان اسم الحقل كمعلَمة.
بما أنّه ما مِن فئة ViewGroup مخصّصة للتسجيل في Google، عليك تسجيل مرّات الظهور والنقرات يدويًا.
يحتوي "الإعلان المدمج مع المحتوى" المخصّص على محتوى وسائط null إذا لم يتضمّن الإعلان مادة عرض فيديو.

في ما يلي مثال على دالة تعرض NativeCustomFormatAd:

جافا

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

فيديو مدمج مع المحتوى لأشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

عند إنشاء تنسيق مخصّص، يتوفّر لك خيار جعل التنسيق مؤهلاً للفيديو.

في عملية تنفيذ تطبيقك، يمكنك استخدام NativeCustomFormatAd.getMediaContent() للحصول على محتوى الوسائط. بعد ذلك، استدعِ setMediaContent() لضبط محتوى الوسائط في عرض الوسائط. إذا كان الإعلان يتضمّن محتوى وسائط من النوع null، عليك وضع خطط بديلة لعرض الإعلان بدون فيديو.

يتحقّق المثال التالي مما إذا كان الإعلان يتضمّن محتوى فيديو، ويعرض صورة بدلاً منه في حال عدم توفّر فيديو:

جافا

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the ID media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

نزِّل مثال العرض المخصّص في "مدير إعلانات Google" للحصول على مثال عملي على "إعلانات الفيديو المدمجة مع المحتوى".

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

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

في إطار الالتزام بقانون الخدمات الرقمية (DSA)، تتطلّب الإعلانات المحجوزة المعروضة في المنطقة الاقتصادية الأوروبية (EEA) رمز "خيارات الإعلان" ورابطًا إلى صفحة "تفاصيل عن الإعلان" من Google. عند تنفيذ "الإعلانات المدمجة مع المحتوى" المخصّصة، تكون أنت المسؤول عن عرض رمز "خيارات الإعلان". ننصحك باتّخاذ خطوات لعرض رمز "خيارات الإعلان" وضبط متتبِّع النقرات له عند عرض مواد عرض الإعلان الرئيسية.

يفترض المثال التالي أنّك حدّدت عنصر <ImageView /> في هيكلية طرق العرض للاحتفاظ بشعار "خيارات الإعلان".

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

تعرض الأمثلة التالية رمز "خيارات الإعلان" وتضبط سلوك النقر المناسب.

جافا

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

تسجيل مرّات الظهور والإبلاغ عن النقرات

يكون تطبيقك مسؤولاً عن تسجيل مرّات الظهور وإرسال أحداث ناتجة عن النقر إلى Google Mobile Ads SDK (Legacy).

تسجيل مرّات الظهور

لتسجيل مرّة ظهور لـ "إعلان مدمج مع المحتوى" مخصّص، استدعِ طريقة recordImpression() للإعلان:

myCustomFormatAd.recordImpression();

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

النقرات على زر الإبلاغ

لإبلاغ حزمة SDK عن حدوث نقرة على طريقة عرض مادة عرض، استدعِ طريقة performClick() للإعلان. قدِّم اسم مادة العرض التي تم النقر عليها باستخدام السلسلة نفسها التي حدّدتها في واجهة مستخدم "مدير الإعلانات".

myCustomFormatAd.performClick("MainImage");

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

الاستجابة لإجراءات النقر المخصّصة

عند النقر على إعلان مخصّص، هناك ثلاثة ردود محتملة من حزمة تطوير البرامج (SDK)، يتم تنفيذها بهذا الترتيب:

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

لتنفيذ إجراء نقر مخصّص، قدِّم OnCustomClickListener:

جافا

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

في البداية، قد يبدو من الغريب وجود متتبِّعات نقرات مخصّصة. ففي النهاية، أخبر تطبيقك حزمة تطوير البرامج (SDK) بحدوث نقرة، فلماذا يجب أن تعود حزمة تطوير البرامج (SDK) وتُبلغ التطبيق بذلك؟

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

استخدام أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تحميل أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

تحميل &quot;إعلان مخصص مدمج مع المحتوى&quot;

جافا

Kotlin

رقم تعريف شكل "الإعلان المدمج مع المحتوى" المخصّص

عرض أشكال &quot;الإعلانات المدمجة مع المحتوى&quot; المخصّصة

جافا

Kotlin

فيديو مدمج مع المحتوى لأشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

جافا

Kotlin

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

جافا

Kotlin

تسجيل مرّات الظهور والإبلاغ عن النقرات

تسجيل مرّات الظهور

النقرات على زر الإبلاغ

الاستجابة لإجراءات النقر المخصّصة

جافا

Kotlin

استخدام أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة

تحميل "إعلان مخصص مدمج مع المحتوى"

عرض أشكال "الإعلانات المدمجة مع المحتوى" المخصّصة