מודעות מתגמלות הן מודעות שהמשתמשים יכולים ליצור איתן אינטראקציה בתמורה לתגמולים מתוך האפליקציה. במדריך הזה מוסבר איך לשלב מודעות מתגמלות Ad Managerבאפליקציה ל-iOS.
דרישות מוקדמות
- Google Mobile Ads SDK מגרסה 8.0.0 ואילך.
- מבצעים את ההוראות שמופיעות במדריך לתחילת העבודה.
ביצוע בדיקות תמיד באמצעות מודעות בדיקה
כשיוצרים ובודקים את האפליקציות, חשוב להשתמש במודעות בדיקה ולא במודעות פעילות בסביבת הייצור. אם לא תעשה זאת, ייתכן שהחשבון שלך יושעה.
הדרך הקלה ביותר לטעון מודעות בדיקה היא באמצעות המזהה הייעודי של יחידת המודעות לבדיקה עבור מודעות מתגמלות ב-iOS:
/6499/example/rewarded
היא הוגדרה במיוחד להחזרת מודעות בדיקה לכל בקשה, וניתן להשתמש בה באפליקציות שלכם בזמן תכנות, בדיקה וניפוי באגים. הקפידו להחליף אותה במזהה יחידת המודעות שלכם לפני פרסום האפליקציה.
רוצים לדעת איך מודעות הבדיקה ב-Mobile Ads SDK פועלות במאמר מודעות בדיקה?
הטמעה
אלה השלבים העיקריים לשילוב מודעות מעברון מתגמלות:
- טעינת מודעה
- [אופציונלי] אימות של קריאות חוזרות (callback) של SSV
- הרשמה לקריאה חוזרת (callback)
- הצגת המודעה וטיפול באירוע הפרס
טעינת מודעה
מתבצעת טעינה של מודעה באמצעות השיטה loadWithAdUnitID:request:completionHandler:
הסטטית במחלקה GADRewardedAd
. לשיטת הטעינה, צריך להפעיל את המזהה של יחידת המודעות, אובייקט GAMRequest
ו-handler להשלמה, שנקרא כאשר טעינת המודעה מצליחה או נכשלת. האובייקט GADRewardedAd
שנטען מסופק כפרמטר ב-handler להשלמה. הדוגמה הבאה ממחישה איך לטעון 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.");
}];
}
[אופציונלי] אימות קריאות חוזרות (callback) לאימות בצד השרת (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;
}];
הרשמה לקריאה חוזרת (callback)
על מנת לקבל התראות לגבי אירועי מצגת, יש להטמיע את הפרוטוקול GADFullScreenContentDelegate
ולהקצות אותו למאפיין fullScreenContentDelegate
של המודעה שהוחזרה. הפרוטוקול GADFullScreenContentDelegate
מטפל בקריאות חוזרות (callback) במקרים שבהם המודעה מוצגת בהצלחה או נכשלה, וכשהמודעה נסגרת. הקוד הבא מראה איך להטמיע את הפרוטוקול ולהקצות אותו למודעה:
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
? - כן, במקרה שאתם צריכים את סכום התגמול לפני הפעלת הקריאה החוזרת (callback) של
userDidEarnReward
, ב-GADRewardedAd
יש נכסadReward
שאפשר לבדוק כדי לאמת את סכום התגמול אחרי טעינת המודעה. - האם יש זמן קצוב לתפוגה של קריאת האתחול?
- אחרי 10 שניות, Google Mobile Ads SDK מפעיל את
GADInitializationCompletionHandler
שסופק ל-methodstartWithCompletionHandler:
, גם אם האתחול של הרשת לבחירת רשת עדיין לא הושלם. - מה קורה אם רשתות מסוימות בתהליך בחירת הרשת לא מוכנות אחרי שאקבל את הקריאה החוזרת מהאתחול?
מומלץ לטעון מודעה בתוך
GADInitializationCompletionHandler
. גם אם רשת מסוימת של תהליך בחירת הרשת לא מוכנה, ה-SDK של מודעות Google לנייד עדיין יבקש מהרשת הזו להציג מודעה. כך שאם האתחול של רשת בתהליך בחירת הרשת מסתיים לאחר הזמן הקצוב לתפוגה, היא עדיין יכולה לטפל בבקשות עתידיות להצגת מודעות בסשן הזה.אפשר להמשיך ולבחון את סטטוס האתחול של כל המתאמים במהלך סשן האפליקציה בקריאה ל-
GADMobileAds.initializationStatus
.- איך אפשר לברר למה רשת מסוימת של תהליך בחירת הרשת לא מוכנה?
במאפיין
description
של אובייקטGADAdapterStatus
מוסבר למה המתאם לא מוכן לטפל בבקשות להצגת מודעות.- האם ל-handler להשלמה של
userDidEarnRewardHandler
תמיד מתבצעת קריאה ל-method הענקת גישהadDidDismissFullScreenContent:
? במודעות Google, כל הקריאות מסוג
userDidEarnRewardHandler
מתבצעות לפניadDidDismissFullScreenContent:
. במודעות שמוצגות באמצעות תהליך בחירת הרשת (Mediation), ההטמעה של ה-SDK של רשת המודעות של הצד השלישי קובעת את סדר הקריאה החוזרת. בערכות SDK של רשתות מודעות שמספקות שיטת הענקת גישה יחידה עם פרטי פרס, המתאם של תהליך בחירת הרשת מפעיל אתuserDidEarnRewardHandler
לפניadDidDismissFullScreenContent:
.
דוגמאות ב-GitHub
השלבים הבאים
למידע נוסף על פרטיות המשתמשים