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

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

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

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

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

لتحميل "إعلان مدمج مع المحتوى مخصّص"، اتّبِع الخطوات التالية:

  1. يجب تضمين نوع "NativeAdType.CUSTOM_NATIVE" كنوع إعلان في NativeAdRequest.

  2. اضبط معرّف شكل "الإعلان المدمج مع المحتوى" المخصّص.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)

جافا

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });

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

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

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

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

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

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

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

يوضّح هذا المثال كيفية عرض CustomNativeAd:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

جافا

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

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

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

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

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

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

جافا

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

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

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

في إطار الالتزام بقانون الخدمات الرقمية (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>

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

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

جافا

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

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

يكون تطبيقك مسؤولاً عن تسجيل مرّات الظهور وإرسال أحداث ناتجة عن النقر إلى GMA Next-Gen SDK.

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

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

جافا

// Record an impression.
customNativeAd.recordImpression();

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

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

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

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }

جافا

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.performClick("MainImage");
      }
    });

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

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

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

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

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

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }

جافا

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });

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

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