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

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

  • الإصدار 19.7.0 أو إصدار أحدث من حزمة SDK لإعلانات Google على الأجهزة الجوّالة
  • عليك إكمال دليل البدء.

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

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

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

ca-app-pub-3940256099942544/5224354917

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

لمزيد من المعلومات عن آلية عمل الإعلانات التجريبية لحزمة تطوير البرامج (SDK) للإعلانات على الأجهزة الجوّالة، اطّلِع على إعلانات تجريبية.

تحميل عنصر إعلان بمكافأة

يتم تحميل الإعلانات بمكافأة من خلال طلب طريقة load() الثابتة في فئة RewardedAd وتمريرها في RewardedAdLoadCallback. ويتم ذلك عادةً باستخدام طريقة onCreate() من Activity. تجدر الإشارة إلى أنّه يمكن RewardedAdLoadCallback الاستفادة من LoadAdError الآخرين لتوفير

لغة Java

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {
  private RewardedAd rewardedAd;
  private final String TAG = "MainActivity";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    AdRequest adRequest = new AdRequest.Builder().build();
    RewardedAd.load(this, "ca-app-pub-3940256099942544/5224354917",
      adRequest, new RewardedAdLoadCallback() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
          // Handle the error.
          Log.d(TAG, loadAdError.toString());
          rewardedAd = null;
        }

        @Override
        public void onAdLoaded(@NonNull RewardedAd ad) {
          rewardedAd = ad;
          Log.d(TAG, "Ad was loaded.");
        }
    });
  }
}

Kotlin

class MainActivity : AppCompatActivity() {

  private var rewardedAd: RewardedAd? = null
  private final var TAG = "MainActivity"

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    var adRequest = AdRequest.Builder().build()
    RewardedAd.load(this,"ca-app-pub-3940256099942544/5224354917", adRequest, object : RewardedAdLoadCallback() {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.d(TAG, adError?.toString())
        rewardedAd = null
      }

      override fun onAdLoaded(ad: RewardedAd) {
        Log.d(TAG, "Ad was loaded.")
        rewardedAd = ad
       }
    })
  }
}

[اختياري] التحقّق من صحة استدعاءات التحقّق من جهة الخادم (SSV)

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

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

لغة Java

RewardedAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
    new AdRequest.Builder().build(),  new RewardedAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
      Log.d(TAG, loadAdError.toString());
      rewardedAd = null;
  }
});

Kotlin

RewardedAd.load(this, "ca-app-pub-3940256099942544/5354046379",
    AdRequest.Builder().build(), object : RewardedAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, adError?.toString())
      rewardedAd = null
  }
})

إذا كنت تريد ضبط سلسلة المكافآت المخصَّصة، عليك إجراء ذلك قبل عرض الإعلان.

ضبط الرد الكامل للشاشة

يتعامل FullScreenContentCallback مع الأحداث ذات الصلة بعرض RewardedAd الخاص بك. قبل عرض RewardedAd، احرص على ضبط معاودة الاتصال على النحو التالي:

لغة Java

rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
  @Override
  public void onAdClicked() {
    // Called when a click is recorded for an ad.
    Log.d(TAG, "Ad was clicked.");
  }

   @Override
  public void onAdDismissedFullScreenContent() {
    // Called when ad is dismissed.
    // Set the ad reference to null so you don't show the ad a second time.
    Log.d(TAG, "Ad dismissed fullscreen content.");
    rewardedAd = null;
  }

  @Override
  public void onAdFailedToShowFullScreenContent(AdError adError) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.");
    rewardedAd = null;
  }

  @Override
  public void onAdImpression() {
    // Called when an impression is recorded for an ad.
    Log.d(TAG, "Ad recorded an impression.");
  }

  @Override
  public void onAdShowedFullScreenContent() {
    // Called when ad is shown.
    Log.d(TAG, "Ad showed fullscreen content.");
  }
});

Kotlin

rewardedAd?.fullScreenContentCallback = object: FullScreenContentCallback() {
  override fun onAdClicked() {
    // Called when a click is recorded for an ad.
    Log.d(TAG, "Ad was clicked.")
  }

  override fun onAdDismissedFullScreenContent() {
    // Called when ad is dismissed.
    // Set the ad reference to null so you don't show the ad a second time.
    Log.d(TAG, "Ad dismissed fullscreen content.")
    rewardedAd = null
  }

  override fun onAdFailedToShowFullScreenContent(adError: AdError?) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.")
    rewardedAd = null
  }

  override fun onAdImpression() {
    // Called when an impression is recorded for an ad.
    Log.d(TAG, "Ad recorded an impression.")
  }

  override fun onAdShowedFullScreenContent() {
    // Called when ad is shown.
    Log.d(TAG, "Ad showed fullscreen content.")
  }
}

عرض الإعلان

عند عرض إعلان بمكافأة، ستستخدم عنصر OnUserEarnedRewardListener لمعالجة أحداث المكافآت.

لغة Java

if (rewardedAd != null) {
  Activity activityContext = MainActivity.this;
  rewardedAd.show(activityContext, new OnUserEarnedRewardListener() {
    @Override
    public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
      // Handle the reward.
      Log.d(TAG, "The user earned the reward.");
      int rewardAmount = rewardItem.getAmount();
      String rewardType = rewardItem.getType();
    }
  });
} else {
  Log.d(TAG, "The rewarded ad wasn't ready yet.");
}

Kotlin

rewardedAd?.let { ad ->
  ad.show(this, OnUserEarnedRewardListener { rewardItem ->
    // Handle the reward.
    val rewardAmount = rewardItem.amount
    val rewardType = rewardItem.type
    Log.d(TAG, "User earned the reward.")
  })
} ?: run {
  Log.d(TAG, "The rewarded ad wasn't ready yet.")
}

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

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

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

يمكنك مواصلة استطلاع حالة ضبط جميع المحوّلات على مستوى جلسة التطبيق عن طريق الاتصال بـ MobileAds.getInitializationStatus().

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

يوضّح AdapterStatus.getDescription() سبب عدم استعداد المحوِّل لخدمة طلبات الإعلانات.

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

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

أمثلة على GitHub

  • مثال على الإعلانات بمكافأة: Java | Kotlin

الخطوات التالية

مزيد من المعلومات عن خصوصية المستخدم