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

اختيار النظام الأساسي: Android New-selected Android iOS Unity Flutter

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

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

  • إعداد GMA Next-Gen SDK.
  • الاختبار دائمًا باستخدام "الإعلانات التجريبية"

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

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

    ca-app-pub-3940256099942544/5224354917

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

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

    تحميل إعلان

    لتحميل إعلان، GMA Next-Gen SDK توفّر ما يلي:

    التحميل باستخدام واجهة برمجة التطبيقات لتحميل إعلان واحد

    يوضّح المثال التالي كيفية تحميل إعلان واحد:

    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 GMA Next-Gen SDK.
        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"
      }
    }
    

    جافا

    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 GMA Next-Gen SDK.
        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;
              }
            }
        );
      }
    }
    

    التحميل باستخدام واجهة برمجة التطبيقات لتحميل الإعلانات مسبقًا

    لبدء التحميل المسبق، اتّبِع الخطوات التالية:

    1. إعداد تهيئة التحميل المُسبق باستخدام طلب عرض الإعلان.

    2. ابدأ أداة التحميل المسبق لـ "الإعلانات مقابل مكافأة" باستخدام رقم تعريف الوحدة الإعلانية وإعداد التحميل المسبق:

    Kotlin

    private fun startPreloading(adUnitId: String) {
      val adRequest = AdRequest.Builder(adUnitId).build()
      val preloadConfig = PreloadConfiguration(adRequest)
      RewardedAdPreloader.start(adUnitId, preloadConfig)
    }
    
    

    جافا

    private void startPreloading(String adUnitId) {
      AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
      PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
      RewardedAdPreloader.start(adUnitId, preloadConfig);
    }
    
    

    عندما تكون مستعدًا لعرض الإعلان، اطلب الإعلان من أداة التحميل المسبق:

    Kotlin

    // Polling returns the next available ad and loads another ad in the background.
    val ad = RewardedAdPreloader.pollAd(adUnitId)
    

    جافا

    // Polling returns the next available ad and loads another ad in the background.
    final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);
    

    ضبط السمة 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.
        }
      }
    

    جافا

    // 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
        }
      },
    )
    

    جافا

    // 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 ثوانٍ، تستدعي GMA Next-Gen SDK السمة OnInitializationCompleteListener حتى إذا لم تكمل شبكة توسّط عملية الإعداد بعد.
    ماذا يحدث إذا لم تكن بعض شبكات التوسّط جاهزة عندما أتلقّى معاودة الاتصال الخاصة بالإعداد؟

    ننصحك بتحميل إعلان داخل معاودة الاتصال الخاصة بالسمة OnInitializationCompleteListener. حتى إذا لم تكن شبكة توسّط جاهزة، GMA Next-Gen SDK تطلب إعلانًا من تلك الشبكة. لذلك، إذا انتهت شبكة توسّط من عملية الإعداد بعد انتهاء المهلة، يمكنها مع ذلك عرض الإعلانات لطلبات الإعلانات المستقبلية في تلك الجلسة.

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

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

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

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

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

    مثال

    نزِّل التطبيق النموذجي الذي يوضّح كيفية استخدام GMA Next-Gen SDK وشغِّله.