الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها في مقابل للحصول على مكافآت داخل التطبيق هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة من "مدير إعلانات Google" في تطبيق iOS.
المتطلبات الأساسية
- الإصدار 8.0.0 أو إصدار أحدث من حزمة "SDK لإعلانات Google على الأجهزة الجوّالة".
- أكمِل دليل البدء.
الاختبار دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات تجريبية بدلاً من إعلانات بث مباشر وقد يؤدي عدم الالتزام بذلك إلى تعليق حسابك.
أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم التعريف المخصّص للوحدة الإعلانية الاختبارية لنظام التشغيل iOS. الإعلانات التي تضم مكافأة:
/21775744923/example/rewarded
لقد تم إعدادها خصيصًا لعرض إعلانات اختبارية لكل طلب، يمكن استخدامها مجانًا في تطبيقاتك الخاصة أثناء الترميز والاختبار وتصحيح الأخطاء. ما عليك سوى إجراء واحرص على استبداله بمعرّف وحدتك الإعلانية قبل نشر تطبيقك.
لمزيد من المعلومات عن آلية عمل الإعلانات الاختبارية لحزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة، راجع اختبار الإعلانات:
التنفيذ
في ما يلي الخطوات الأساسية لدمج الإعلانات التي تضم مكافأة:
- تحميل إعلان
- [اختياري] التحقُّق من عمليات معاودة الاتصال باستخدام ميزة "التحقُّق بخطوتين"
- التسجيل لتلقّي طلبات معاودة الاتصال
- عرض الإعلان والتعامل مع حدث المكافأة
تحميل إعلان
يتم الانتهاء من تحميل إعلان باستخدام الثابت
طريقة "loadWithAdUnitID:request:completionHandler:
" على
صف واحد (GADRewardedAd
). تتطلب طريقة التحميل رقم تعريف وحدتك الإعلانية، وهو
كائن GAMRequest
ومعالج عملية الإكمال
والذي يتم طلبه عند نجاح تحميل الإعلان أو تعذُّر تحميله.
يتوفّر عنصر GADRewardedAd
كمَعلمة في عملية الإكمال.
. يوضح المثال التالي كيفية تحميل GADRewardedAd
في
صف ViewController
.
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
}
Objective-C
@import GoogleMobileAds;
@import UIKit;
@interface ViewController ()
@property(nonatomic, strong) GADRewardedAd *rewardedAd;
@end
@implementation ViewController
- (void)loadRewardedAd {
GAMRequest *request = [GAMRequest request];
[GADRewardedAd
loadWithAdUnitID:@"/21775744923/example/rewarded"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
return;
}
self.rewardedAd = ad;
NSLog(@"Rewarded ad loaded.");
}];
}
[اختياري] التحقق من صحة عمليات استدعاء التحقّق من جهة الخادم (SSV)
التطبيقات التي تتطلب بيانات إضافية في خادم
التحقق، يجب أن تستخدم استدعاءات
الخاصة بالإعلانات التي تضم مكافأة. أي قيمة سلسلة تمّ تحديدها على إعلان يضم مكافأة
يتم تمرير الكائن إلى معلَمة طلب البحث custom_data
لمعاودة اتصال SSV. إذا كانت الإجابة "لا"
البيانات المخصّصة، ولن يتم تغيير قيمة معلَمة طلب البحث custom_data
الموجودة في معاودة اتصال SSV.
يوضح نموذج الرمز البرمجي التالي كيفية ضبط البيانات المخصّصة في إعلان يضم مكافأة. قبل طلب إعلان.
Swift
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
let options = GADServerSideVerificationOptions()
options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
rewardedAd.serverSideVerificationOptions = options
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
Objective-C
[GADRewardedAd
loadWithAdUnitID:@"/21775744923/example/rewarded"
request:[GAMRequest request];
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
// Handle Error
return;
}
self.rewardedAd = ad;
GADServerSideVerificationOptions *options =
[[GADServerSideVerificationOptions alloc] init];
options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
ad.serverSideVerificationOptions = options;
}];
التسجيل لتلقّي طلبات معاودة الاتصال
لتلقي إشعارات لأحداث العرض التقديمي، يجب تنفيذ
بروتوكول GADFullScreenContentDelegate
وتعيينه إلى
السمة fullScreenContentDelegate
للإعلان الذي تم عرضه. تشير رسالة الأشكال البيانية
يتعامل بروتوكول GADFullScreenContentDelegate
مع عمليات معاودة الاتصال عند ظهور الإعلان
نجاحه أو عدم نجاحه وعندما يتم رفضه. ما يلي:
طريقة تنفيذ البروتوكول وتعيينه للإعلان:
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController, GADFullScreenContentDelegate {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
rewardedAd?.fullScreenContentDelegate = self
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
/// Tells the delegate that the ad failed to present full screen content.
func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
print("Ad did fail to present full screen content.")
}
/// Tells the delegate that the ad will present full screen content.
func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("Ad will present full screen content.")
}
/// Tells the delegate that the ad dismissed full screen content.
func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("Ad did dismiss full screen content.")
}
}
Objective-C
@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADRewardedAd *rewardedAd;
@end
@implementation ViewController
- (void)loadRewardedAd {
GAMRequest *request = [GAMRequest request];
[GADRewardedAd
loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
if (error) {
NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
return;
}
self.rewardedAd = ad;
NSLog(@"Rewarded ad loaded.");
self.rewardedAd.fullScreenContentDelegate = self;
}];
}
/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
NSLog(@"Ad did fail to present full screen content.");
}
/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad will present full screen content.");
}
/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
NSLog(@"Ad did dismiss full screen content.");
}
GADRewardedAd
هو عنصر يُستخدم لمرة واحدة. وهذا يعني أنه بعد عرض الإعلان الذي يضم مكافأة
كما هو موضح، لا يمكن عرضه مرة أخرى. ومن أفضل الممارسات تحميل إعلان آخر يضم مكافأة.
في طريقة adDidDismissFullScreenContent:
على GADFullScreenContentDelegate
لكي يبدأ تحميل الإعلان التالي الذي يضم مكافأة بمجرد تحميل الإعلان السابق
رفضت.
عرض الإعلان والتعامل مع حدث المكافأة
قبل عرض إعلان يضم مكافأة للمستخدمين، يجب أن تقدّم للمستخدم خيار صريح لعرض محتوى الإعلان الذي يضم مكافأة مقابل مكافأة. مكافأة أن تتضمّن الإعلانات دائمًا تجربة تتطلّب موافقة المستخدمين.
عند عرض إعلانك، يجب تقديم كائن GADUserDidEarnRewardHandler
.
لمعالجة المكافأة للمستخدم.
يوضّح الرمز التالي أفضل طريقة لعرض الإعلان الذي يضم مكافأة.
Swift
func show() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
// The UIViewController parameter is an optional.
ad.present(fromRootViewController: nil) {
let reward = ad.adReward
print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
// TODO: Reward the user.
}
}
Objective-C
- (void)show {
if (self.rewardedAd) {
// The UIViewController parameter is nullable.
[self.rewardedAd presentFromRootViewController:nil
userDidEarnRewardHandler:^{
GADAdReward *reward =
self.rewardedAd.adReward;
// TODO: Reward the user!
}];
} else {
NSLog(@"Ad wasn't ready");
}
}
الأسئلة الشائعة
- هل يمكنني الحصول على تفاصيل المكافأة الخاصة بـ "
GADRewardedAd
"؟ - نعم، إذا كنت بحاجة إلى مبلغ المكافأة قبل معاودة الاتصال على
userDidEarnReward
تم تنشيطها، يمتلكGADRewardedAd
adReward
الموقع الذي يمكنك التحقّق منه للتحقّق من قيمة المكافأة بعد تحميل الإعلان. - هل هناك مهلة لطلب الإعداد؟
- بعد 10 ثوانٍ، تستدعي "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة"
تمّ توفير
GADInitializationCompletionHandler
إلىstartWithCompletionHandler:
، حتى إذا لم يتم إجراء ذلك من خلال شبكة توسّط حتى الآن إكمال عملية الإعداد - ماذا لو لم تكن بعض شبكات التوسّط جاهزة عند تلقّي معاودة الاتصال بالإعداد؟
نقترح تحميل إعلان داخل
GADInitializationCompletionHandler
وحتى إذا لم تكن شبكة التوسّط جاهزة إلا أن حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" لا تزال تطلب من تلك الشبكة عرض إعلان. لذلك إذا كانت تنتهي تهيئة شبكة التوسط بعد انتهاء المهلة، فيمكن أن يستمر في لطلبات الإعلان المستقبلية في تلك الجلسة.يمكنك مواصلة التحقق من حالة الإعداد لجميع المحوّلات. جلسة التطبيق من خلال الاتصال بالرقم
GADMobileAds.initializationStatus
.- كيف يمكنني معرفة سبب عدم جهوزية شبكة توسّط معيَّنة؟
تصف السمة
description
لكائنGADAdapterStatus
سبب المحوّل غير جاهز لمعالجة طلبات الإعلان.- هل يتم دائمًا استدعاء معالج إكمال
userDidEarnRewardHandler
قبل طريقة التفويضadDidDismissFullScreenContent:
؟ بالنسبة إلى "إعلانات Google"، تتم جميع المكالمات البالغ عددها
userDidEarnRewardHandler
. قبلadDidDismissFullScreenContent:
. بالنسبة إلى الإعلانات التي يتم عرضها من خلال التوسط، وشبكة المواقع الإعلانية التابعة لجهة خارجية تحدّد عملية تنفيذ حزمة تطوير البرامج (SDK) طلب معاودة الاتصال. بالنسبة إلى حِزم تطوير البرامج (SDK) لشبكات الإعلانات التي وتوفير طريقة تفويض واحدة تضم معلومات المكافأة، وهي عبارة عن محوّل التوسط يستدعيuserDidEarnRewardHandler
قبلadDidDismissFullScreenContent:
.
أمثلة على GitHub
الخطوات التالية
مزيد من المعلومات حول خصوصية المستخدم