الإعلانات بمكافأة

تسمح لك الإعلانات مقابل مكافأة بمكافأة المستخدمين باستخدام عناصر داخل التطبيق نظير التفاعل مع إعلانات الفيديو، و"إعلانات تشغيل إصدار بسيط من اللعبة"، والاستطلاعات.

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

أكمِل دليل البدء.

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

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

أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام معرّف وحدة الإعلانات الاختبارية المخصّص لـ "الإعلانات مقابل مكافأة" على Android:

ca-app-pub-3940256099942544/5224354917

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

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

تحميل إعلان

لتحميل "إعلان مقابل مكافأة"، استدعِ طريقة RewardedAd الثابتة load() وأدخِل AdLoadCallback<RewardedAd> لتلقّي الإعلان المحمَّل أو أي أخطاء محتملة.

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

Kotlin

import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback
import com.google.android.libraries.ads.mobile.sdk.common.AdRequest
import com.google.android.libraries.ads.mobile.sdk.common.FullScreenContentError
import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAd
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAdEventCallback
import com.google.android.libraries.ads.mobile.sdk.MobileAds

class RewardedActivity : Activity() {
  private var rewardedAd: RewardedAd? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Load ads after you inititalize Google Mobile Ads SDK (beta).
    RewardedAd.load(
      AdRequest.Builder(AD_UNIT_ID).build(),
      object : AdLoadCallback<RewardedAd> {
        override fun onAdLoaded(ad: RewardedAd) {
          // Rewarded ad loaded.
          rewardedAd = ad
        }

        override fun onAdFailedToLoad(adError: LoadAdError) {
          // Rewarded ad failed to load.
          rewardedAd = null
        }
      },
    )
  }

  companion object {
    // Sample rewarded ad unit ID.
    const val AD_UNIT_ID = "ca-app-pub-3940256099942544/5224354917"
  }
}

Java

import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback;
import com.google.android.libraries.ads.mobile.sdk.common.AdRequest;
import com.google.android.libraries.ads.mobile.sdk.common.FullScreenContentError;
import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError;
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAd;
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAdEventCallback;
import com.google.android.libraries.ads.mobile.sdk.MobileAds;

class RewardedActivity extends Activity {
  // Sample rewarded ad unit ID.
  private static final String AD_UNIT_ID = "ca-app-pub-3940256099942544/5224354917";
  private RewardedAd rewardedAd;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Load ads after you initialize Google Mobile Ads SDK (beta).
    RewardedAd.load(
        new AdRequest.Builder(AD_UNIT_ID).build(),
        new AdLoadCallback<RewardedAd>() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // Rewarded ad loaded.
            AdLoadCallback.super.onAdLoaded(rewardedAd);
            RewardedActivity.this.rewardedAd = rewardedAd;
          }

          @Override
          public void onAdFailedToLoad(@NonNull LoadAdError adError) {
            // Rewarded ad failed to load.
            AdLoadCallback.super.onAdFailedToLoad(adError);
            rewardedAd = null;
          }
        }
    );
  }
}

ضبط RewardedAdEventCallback

يتعامل RewardedAdEventCallback مع الأحداث المرتبطة بعرض RewardedAd. قبل عرض "الإعلان مقابل مكافأة"، تأكَّد من ضبط دالة الرجوع على النحو التالي:

Kotlin

// Listen for ad events.
rewardedAd?.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Rewarded ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Rewarded ad did dismiss.
      rewardedAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Rewarded ad failed to show.
      rewardedAd = null
    }

    override fun onAdImpression() {
      // Rewarded ad did record an impression.
    }

    override fun onAdClicked() {
      // Rewarded ad did record a click.
    }
  }

Java

// Listen for ad events.
rewardedAd.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Rewarded ad did show.
        RewardedAdEventCallback.super.onAdShowedFullScreenContent();
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        RewardedAdEventCallback.super.onAdDismissedFullScreenContent();
        rewardedAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Rewarded ad failed to show.
        RewardedAdEventCallback.super.onAdFailedToShowFullScreenContent(
            fullScreenContentError);
        rewardedAd = null;
      }

      @Override
      public void onAdImpression() {
        // Rewarded ad did record an impression.
        RewardedAdEventCallback.super.onAdImpression();
      }

      @Override
      public void onAdClicked() {
        // Rewarded ad did record a click.
        RewardedAdEventCallback.super.onAdClicked();
      }
    }
);

عرض الإعلان

لعرض إعلان مقابل مكافأة، استخدِم الطريقة show(). استخدِم عنصر OnUserEarnedRewardListener للتعامل مع أحداث المكافآت.

Kotlin

// Show the ad.
rewardedAd?.show(
  this@RewardedActivity,
  object : OnUserEarnedRewardListener {
    override fun onUserEarnedReward(rewardItem: RewardItem) {
      // User earned the reward.
      val rewardAmount = rewardItem.amount
      val rewardType = rewardItem.type
    }
  },
)

Java

// Show the ad.
rewardedAd.show(
    RewardedActivity.this,
    new OnUserEarnedRewardListener() {
      @Override
      public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
        // User earned the reward.
        int rewardAmount = rewardItem.getAmount();
        String rewardType = rewardItem.getType();
    }
});

الأسئلة الشائعة

هل هناك مهلة زمنية لمكالمة الإعداد؟

بعد 10 ثوانٍ، تستدعي حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة (الإصدار التجريبي) OnInitializationCompleteListener حتى إذا لم تكمل إحدى شبكات التوسّط عملية الإعداد بعد.

ماذا يحدث إذا لم تكن بعض شبكات التوسّط جاهزة عند تلقّي معاودة الاتصال الخاصة ببدء التشغيل؟

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

يمكنك مواصلة طلب حالة الإعداد لجميع المحوّلات طوال جلسة تطبيقك من خلال استدعاء MobileAds.getInitializationStatus().

كيف يمكنني معرفة سبب عدم جاهزية شبكة توسّط معيّنة؟

توضّح السمة AdapterStatus.getDescription() سبب عدم جاهزية إحدى الجهات الوسيطة لتلبية طلبات الإعلانات.

هل يتم دائمًا استدعاء رد الاتصال onUserEarnedReward() قبل رد الاتصال onAdDismissedFullScreenContent()؟

بالنسبة إلى إعلانات Google، تحدث جميع عمليات استدعاء onUserEarnedReward() قبل onAdDismissedFullScreenContent(). بالنسبة إلى الإعلانات التي يتم عرضها من خلال التوسّط، يحدّد تنفيذ حزمة تطوير البرامج (SDK) لشبكة الإعلانات التابعة لجهة خارجية ترتيب عمليات معاودة الاتصال. بالنسبة إلى حِزم SDK لشبكات الإعلانات التي توفّر معاودة اتصال واحدة عند الإغلاق مع معلومات المكافأة، يستدعي برنامج التكييف الخاص بالتوسّط الدالة onUserEarnedReward() قبل الدالة onAdDismissedFullScreenContent().

مثال

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