الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها مقابل الحصول على مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات التي تضم مكافآت من Ad Manager في أحد تطبيقات iOS.
المتطلبات الأساسية
- حزمة SDK لإعلانات Google على الأجهزة الجوّالة 8.0.0 أو إصدار أحدث.
- أكمل دليل البدء.
الاختبار دائمًا من خلال الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات تجريبية وليس إعلانات مباشرة. وقد يؤدي عدم الالتزام بذلك إلى تعليق حسابك.
تتمثل أسهل طريقة لتحميل الإعلانات الاختبارية في استخدام رقم تعريف الوحدة الإعلانية التجريبية المخصص للإعلانات بمكافأة على نظام التشغيل iOS:
/6499/example/rewarded
لقد تم ضبطها خصّيصًا من أجل عرض إعلانات اختبارية لكل طلب، ويمكنك استخدامها في تطبيقاتك الخاصة أثناء الترميز والاختبار وتصحيح الأخطاء. ما عليك سوى استبداله برقم تعريف وحدتك الإعلانية قبل نشر تطبيقك.
لمزيدٍ من المعلومات عن آلية عمل الإعلانات الاختبارية في "حزمة تطوير البرامج (SDK) لإعلانات الأجهزة الجوّالة"، اطّلِع على الإعلانات الاختبارية.
التنفيذ
في ما يلي الخطوات الأساسية لدمج الإعلانات التي تضم مكافأة:
- تحميل إعلان
- [اختياري] التحقّق من صحة استدعاءات SSV
- التسجيل لمعاودة الاتصال
- عرض الإعلان والتعامل مع حدث المكافأة
تحميل إعلان
يتم تحميل الإعلان باستخدام طريقة 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: "/6499/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:@"/6499/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: "/6499/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:@"/6499/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: "/6499/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
- مثال على الإعلانات التي تضم مكافأة: Swift | Objective-C
الخطوات التالية
مزيد من المعلومات عن خصوصية المستخدم.