المتطلبات الأساسية
- الإصدار 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
الخطوات التالية
مزيد من المعلومات عن خصوصية المستخدم