يمكنك مشاركة ملاحظاتك حول "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة" في قناة #gma-next-gen-sdk على Discord في خادم Google Advertising and Measurement Community.

تنفيذ إعلانات الرموز

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

يوضّح لك هذا الدليل كيفية طلب عرض إعلانات الرموز.

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

قبل البدء، يجب أن يكون لديك الإصدار GMA Next-Gen SDK 0.8.0-alpha01 أو إصدار أحدث.

اختبار الإعلانات دائمًا باستخدام الإعلانات الاختبارية

عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات اختبارية بدلاً من الإعلانات المباشرة الخاصة بالمنتج. قد يؤدي عدم استخدام الإعلانات الاختبارية إلى تعليق حسابك.

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

ca-app-pub-3940256099942544/1476272466

للحصول على تفاصيل حول الإعلانات التجريبية في GMA Next-Gen SDK، اطّلِع على مقالة تفعيل الإعلانات التجريبية.

تحميل إعلان رمزي

حمِّل إعلانًا على شكل رمز باستخدام طلب عرض الإعلان على شكل رمز، وتعامل مع أحداث تحميل الإعلان:

Kotlin

private fun loadIconAd() {
  val request =
    IconAdRequest.Builder(AD_UNIT_ID)
      // The "AdChoices" badge is rendered at the top right corner of the icon ad
      // if left unspecified.
      .setAdChoicesPlacement(AdChoicesPlacement.BOTTOM_RIGHT)
      // It is recommended to specify the placement of your icon ad
      // to help Google optimize your icon ad performance.
      .setIconAdPlacement(IconAdPlacement.BROWSER)
      .build()

  IconAd.load(
    request,
    object : AdLoadCallback<IconAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(Constant.TAG, "Icon ad failed to load: $adError")
        showToast("Icon ad failed to load.")
      }

      override fun onAdLoaded(ad: IconAd) {
        Log.d(Constant.TAG, "Icon ad loaded")
        // Always call destroy() on ads on removal.
        iconAd?.destroy()
        iconAd = ad
        setAdEventCallback(ad)
        displayIconAd(ad)
      }
    },
  )
}
IconAdFragment.kt

جافا

private void loadIconAd() {
  IconAdRequest request =
      new IconAdRequest.Builder(AD_UNIT_ID)
          // The "AdChoices" badge is rendered at the top right corner of the icon ad
          // if left unspecified.
          .setAdChoicesPlacement(AdChoicesPlacement.BOTTOM_RIGHT)
          // It is recommended to specify the placement of your icon ad
          // to help Google optimize your icon ad performance.
          .setIconAdPlacement(IconAdPlacement.BROWSER)
          .build();

  IconAd.load(
      request,
      new AdLoadCallback<IconAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(Constant.TAG, "Icon ad failed to load :" + adError);
          showToast("Icon ad failed to load with error code: " + adError.getCode());
        }

        @Override
        public void onAdLoaded(@NonNull IconAd ad) {
          Log.d(Constant.TAG, "Icon ad loaded.");

          // Always call destroy() on ads on removal.
          if (iconAd != null) {
              iconAd.destroy();
          }
          iconAd = ad;
          setAdEventCallback(ad);
          displayIconAd(ad);
        }
      });
}
IconAdFragment.java

إنشاء عرض لإعلان الرمز

يجب أن تستخدم إعلانات الرموز IconAdView كعنصر أساسي لمواد عرضها. ضَع جميع العناصر المرئية لإعلانك ضمن طريقة عرض الإعلان على شكل رمز.

يوضّح المثال التالي تخطيطًا لإنشاء طريقة عرض "إعلان رمزي":

<?xml version="1.0" encoding="utf-8"?>
<com.google.android.libraries.ads.mobile.sdk.iconad.IconAdView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

  <LinearLayout
      android:id="@+id/icon_ad_container"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_gravity="center"
      android:background="#00FFC107"
      android:orientation="vertical">

    <LinearLayout
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:orientation="horizontal">
      <TextView
          android:id="@+id/ad_badge"
          android:width="15dp"
          android:height="15dp"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:background="#FFC107"
          android:text="Ad"
          android:textColor="#FFFFFF"
          android:textSize="12sp" />
      <TextView
          android:id="@+id/ad_headline"
          android:textStyle="normal"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:layout_gravity="center"
          android:autoText="true"
          android:inputType="text|textMultiLine"
          android:textColor="#808080"
          android:textSize="12sp" />
    </LinearLayout>

    <com.google.android.material.imageview.ShapeableImageView xmlns:app="http://schemas.android.com/apk/res-auto"
        android:id="@+id/ad_icon"
        android:layout_width="100dp"
        android:layout_height="100dp"
        android:layout_gravity="center"
        android:adjustViewBounds="true"
        android:background="@android:color/holo_green_light"
        android:contentDescription="@string/content_description_icon_ad"
        android:theme="@style/Theme.AppCompat.Light"
        app:shapeAppearanceOverlay="@style/roundedCorners"
        app:strokeColor="@null" />

    <RatingBar
        android:id="@+id/ad_stars"
        style="?android:attr/ratingBarStyleSmall"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:isIndicator="true"
        android:numStars="5"
        android:stepSize="0.5" />
    <Button
        android:id="@+id/ad_call_to_action"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:gravity="center"
        android:textSize="12sp" />
  </LinearLayout>

</com.google.android.libraries.ads.mobile.sdk.iconad.IconAdView>

عرض الإعلان على شكل رمز على الشاشة

لعرض الإعلان الرمزي على الشاشة، أكمِل الخطوات التالية:

تضخيم عرض الإعلان الرمزي وإضافته إلى هيكلية طرق العرض
املأ كل عرض ملف الطفل بمادة عرض الإعلان المقابلة للرمز.

يغطّي المثال التالي الخطوات السابقة لعرض الإعلان على شكل رمز على الشاشة:

Kotlin

val iconAdViewBinding = IconAdBinding.inflate(layoutInflater)
// Add the ad view to the active view hierarchy.
binding.iconAdContainer.addView(iconAdViewBinding.root)
val iconAdView = iconAdViewBinding.root

// Populate the view elements with their respective icon ad asset.
iconAdView.callToActionView = iconAdViewBinding.adCallToAction
iconAdView.headlineView = iconAdViewBinding.adHeadline
iconAdView.iconView = iconAdViewBinding.adIcon
iconAdView.starRatingView = iconAdViewBinding.adStarsIconAdFragment.kt

جافا

IconAdBinding iconAdViewBinding = IconAdBinding.inflate(getLayoutInflater());
// Add the ad view to the active view hierarchy.
binding.iconAdContainer.addView(iconAdViewBinding.getRoot());
IconAdView iconAdView = iconAdViewBinding.getRoot();

// Populate the view elements with their respective icon ad asset.
iconAdView.setCallToActionView(iconAdViewBinding.adCallToAction);
iconAdView.setHeadlineView(iconAdViewBinding.adHeadline);
iconAdView.setIconView(iconAdViewBinding.adIcon);
iconAdView.setStarRatingView(iconAdViewBinding.adStars);IconAdFragment.java

جعل الإعلان على شكل رمز قابلاً للنقر

تسجّل السمة GMA Next-Gen SDK أدوات معالجة النقرات لكل طريقة عرض لمادة العرض يتم ربطها عند استدعاء registerIconAd(). اربط خصائص عرض الإعلان على شكل رمز بالخصائص المقابلة في التسلسل الهرمي للعرض قبل تسجيل الإعلان على شكل رمز:

Kotlin

// Map each asset view property to the corresponding view in your view hierarchy.
iconAdViewBinding.adCallToAction.text = iconAd.callToAction
iconAdViewBinding.adHeadline.text = iconAd.headline
iconAdViewBinding.adIcon.setImageDrawable(iconAd.icon.drawable)
iconAd.starRating?.toFloat().also { value ->
  if (value != null) {
    iconAdViewBinding.adStars.rating = value
  }
}

// Register the icon ad with the view presenting it.
iconAdView.registerIconAd(iconAd)IconAdFragment.kt

جافا

// Map each asset view property to the corresponding view in your view hierarchy.
iconAdViewBinding.adCallToAction.setText(iconAd.getCallToAction());
iconAdViewBinding.adHeadline.setText(iconAd.getHeadline());
iconAdViewBinding.adIcon.setImageDrawable(iconAd.getIcon().getDrawable());

if (iconAd.getStarRating() != null) {
  iconAdViewBinding.adStars.setRating(iconAd.getStarRating().floatValue());
}

// Register the icon ad with the view presenting it.
iconAdView.registerIconAd(iconAd);IconAdFragment.java

اختياري: ضبط وظيفة استدعاء نتائج حدث الإعلان الرمزي

للتعامل مع أحداث مراحل نشاط إعلانات الرموز، اضبط معاودة الاتصال بالحدث:

Kotlin

iconAd.adEventCallback =
  object : IconAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Icon ad showed full screen content.
    }

    override fun onAdDismissedFullScreenContent() {
      // Icon ad dismissed full screen content.
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Icon ad failed to show full screen content.
    }

    override fun onAdImpression() {
      // Icon ad recorded an impression.
    }

    override fun onAdClicked() {
      // Icon ad recorded a click.
    }

    override fun onAdPaid(value: AdValue) {
      // Icon ad estimated to have earned money.
    }
  }IconAdFragment.kt

جافا

iconAd.setAdEventCallback(
    new IconAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Icon ad showed full screen content.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Icon ad dismissed full screen content.
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Icon ad failed to show full screen content.
      }

      @Override
      public void onAdImpression() {
        // Icon ad recorded an impression.
      }

      @Override
      public void onAdClicked() {
        // Icon ad recorded a click.
      }

      @Override
      public void onAdPaid(@NonNull AdValue value) {
        // Icon ad estimated to have earned money.
      }
    });IconAdFragment.java

تحسين الأداء

تتناول الأقسام التالية خطوات التنفيذ الاختيارية لتحسين أداء الإعلانات التي تتضمّن رموزًا.

استخدام معرّف الربط لتحميل إعلانات متعدّدة

عند تحميل إعلانات متعدّدة على شكل رموز لعرضها معًا، عليك إرسال طلبات متسلسلة باستخدام قيمة معرّف الارتباط نفسها لضمان أنّ الإعلانات التي تم تحميلها فريدة. تبلغ مدة صلاحية أداة الربط 10 ثوانٍ. لا يعتبر الخادم الطلبات التي تم إجراؤها بفارق زمني يزيد عن 10 ثوانٍ مرتبطة ببعضها.

يوضّح المثال التالي كيفية ضبط قيمة أداة الربط في طلب عرض الإعلان:

Kotlin

val correlator = Correlator.generateCorrelator()
val request =
      IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setCorrelator(correlator)
        .build()

جافا

Correlator correlator = Correlator.generateCorrelator();
IconAdRequest request =
    new IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setCorrelator(correlator)
        .build();

ضبط موضع إعلان الرمز

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

استخدِم قيمة التعداد IconAdPlacement التي تمثّل حالة الاستخدام بشكلٍ أدق:

Kotlin

val request =
  IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
    .setIconAdPlacement(IconAdPlacement.BROWSER)
    .build()

جافا

IconAdRequest request =
    new IconAdRequest.Builder("ca-app-pub-3940256099942544/1476272466")
        .setIconAdPlacement(IconAdPlacement.BROWSER)
        .build();

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

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

اختبار الإعلانات دائمًا باستخدام الإعلانات الاختبارية

تحميل إعلان رمزي

Kotlin

جافا

إنشاء عرض لإعلان الرمز

عرض الإعلان على شكل رمز على الشاشة

Kotlin

جافا

جعل الإعلان على شكل رمز قابلاً للنقر

Kotlin

جافا

اختياري: ضبط وظيفة استدعاء نتائج حدث الإعلان الرمزي

Kotlin

جافا

تحسين الأداء

استخدام معرّف الربط لتحميل إعلانات متعدّدة

Kotlin

جافا

ضبط موضع إعلان الرمز

Kotlin

جافا

تنفيذ إعلانات الرموز