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

بالإضافة إلى الأشكال المدمجة مع المحتوى التي يحددها النظام، يمكن للناشرين على "إدارة إعلانات 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();
}

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

عرض رمز AdChoices

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

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

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

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

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.

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

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

جافا

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

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

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

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

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 بالتحكّم في الردّ على النقرة. يمكنها تلقائيًا إرسال طلبات ping إلى عناوين URL لتتبُّع الجهات الخارجية التي تم ضبطها للتصميم، على سبيل المثال، والتعامل مع المهام الأخرى وراء الكواليس، بدون أي رمز إضافي.