מודעות מתגמלות הן מודעות שהמשתמשים יכולים ליצור איתן אינטראקציה בתמורה לתגמולים באפליקציה. במדריך הזה מוסבר איך לשלב מודעות מתגמלות מ-Ad Manager באפליקציה ל-iOS.
דרישות מוקדמות
- Google Mobile Ads SDK בגרסה 8.0.0 ואילך.
- קוראים את המדריך לתחילת העבודה.
תמיד כדאי לבדוק באמצעות מודעות בדיקה
כשאתם מפתחים ובודקים את האפליקציות, חשוב להשתמש במודעות בדיקה במקום במודעות פעילות בסביבת הייצור. אם לא תעשו זאת, החשבון שלכם עלול להיחסם.
הדרך הקלה ביותר לטעון מודעות בדיקה היא להשתמש במזהה הייעודי של יחידת המודעות לבדיקה של מודעות תמורת פרסים ל-iOS:
/21775744923/example/rewarded
הוא מוגדר במיוחד להחזיר מודעות בדיקה לכל בקשה, ואתם יכולים להשתמש בו באפליקציות שלכם בזמן הכתיבה, הבדיקה ותיקון הבאגים. חשוב רק לוודא שתחליפו אותו במזהה של יחידת המודעות שלכם לפני שתפרסמו את האפליקציה.
מידע נוסף על אופן הפעולה של מודעות הבדיקה של Mobile Ads SDK זמין במאמר מודעות בדיקה.
הטמעה
השלבים העיקריים לשילוב מודעות מתגמלות הם:
- טעינת מודעה
- [אופציונלי] אימות קריאות חוזרות (callbacks) של SSV
- הרשמה להתקשרויות חוזרות
- הצגת המודעה וטיפול באירוע של מתן הפרס
טעינת מודעה
הטעינה של מודעה מתבצעת באמצעות השיטה load(adUnitID:request)
בכיתה GADRewardedAd
.
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
} catch {
print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}
}
}
SwiftUI
import GoogleMobileAds
class RewardedViewModel: NSObject, ObservableObject, GADFullScreenContentDelegate {
@Published var coins = 0
private var rewardedAd: GADRewardedAd?
func loadAd() async {
do {
rewardedAd = try await GADRewardedAd.load(
withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
rewardedAd?.fullScreenContentDelegate = self
} catch {
print("Failed to load rewarded ad 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.");
}];
}
[אופציונלי] אימות קריאות חוזרות (callbacks) של אימות בצד השרת (SSV)
באפליקציות שדורשות נתונים נוספים בקריאות חזרה של אימות בצד השרת, צריך להשתמש בתכונה 'נתונים מותאמים אישית' של מודעות מתגמלות. כל ערך מחרוזת שמוגדר באובייקט של מודעה עם פרס מועבר לפרמטר השאילתה custom_data
של קריאה חוזרת (callback) של 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
מטפל בקריאות חזרה (callbacks) במקרים שבהם המודעה מוצגת בהצלחה או לא מוצגת, וגם במקרים שבהם היא נסגרת. הקוד הבא מראה איך מטמיעים את הפרוטוקול ומקצים אותו למודעה:
Swift
import GoogleMobileAds
import UIKit
class ViewController: UIViewController, GADFullScreenContentDelegate {
private var rewardedAd: GADRewardedAd?
func loadRewardedAd() async {
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.")
}
}
SwiftUI
מקצים את המאפיין fullScreenContentDelegate
למודעה שהוחזרה:
rewardedAd?.fullScreenContentDelegate = self
מטמיעים את הפרוטוקול:
func adDidRecordImpression(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidRecordClick(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func ad(
_ ad: GADFullScreenPresentingAd,
didFailToPresentFullScreenContentWithError error: Error
) {
print("\(#function) called")
}
func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adWillDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
}
func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
print("\(#function) called")
// Clear the rewarded ad.
rewardedAd = nil
}
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.
}
}
SwiftUI
אפשר להאזין לאירועים בממשק המשתמש בתצוגה כדי לקבוע מתי להציג את המודעה.
var body: some View {
VStack(spacing: 20) {
Button("Watch video for additional 10 coins") {
viewModel.showAd()
showWatchVideoButton = false
}
הצגת המודעה המתגמלת מתוך מודל התצוגה:
func showAd() {
guard let rewardedAd = rewardedAd else {
return print("Ad wasn't ready.")
}
rewardedAd.present(fromRootViewController: nil) {
let reward = rewardedAd.adReward
print("Reward amount: \(reward.amount)")
self.addCoins(reward.amount.intValue)
}
}
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
שסופק לשיטהstartWithCompletionHandler:
, גם אם רשת תהליך בחירת הרשת עדיין לא השלימה את ההפעלה. - מה קורה אם חלק מרשתות בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) להפעלה?
מומלץ לטעון מודעה בתוך ה-
GADInitializationCompletionHandler
. גם אם רשת מסוימת לבחירת רשת לא מוכנה, ה-Google Mobile Ads SDK עדיין מבקש מודעה מהרשת הזו. לכן, אם רשת לבחירת רשת מסיימת את האינטראקציה הראשונית אחרי זמן הקצוב לתפוגה, היא עדיין יכולה לטפל בבקשות עתידיות להצגת מודעות בסשן הזה.אפשר להמשיך לבצע סקרים של סטטוס האיפוס של כל המתאמים במהלך סשן האפליקציה באמצעות קריאה ל-
GADMobileAds.initializationStatus
.- איך אפשר לבדוק למה רשת ספציפית לבחירת רשת לא מוכנה?
המאפיין
description
של אובייקטGADAdapterStatus
מתאר למה מתאם לא מוכן לטפל בבקשות להצגת מודעות.- האם פונקציית הטיפול בהשלמה
userDidEarnRewardHandler
תמיד נקראת לפני שיטת הענקת הגישהadDidDismissFullScreenContent:
? במודעות Google, כל הקריאות ל-
userDidEarnRewardHandler
מתרחשות לפניadDidDismissFullScreenContent:
. במודעות שמוצגות דרך תהליך בחירת הרשת, ההטמעה של ה-SDK של רשת המודעות של הצד השלישי קובעת את סדר הקריאה החוזרת. בערכות SDK של רשתות מודעות שמספקות שיטת הענקת גישה אחת עם פרטי התגמול, מתאם בחירת הרשת קורא ל-userDidEarnRewardHandler
לפניadDidDismissFullScreenContent:
.
דוגמאות ב-GitHub
כאן אפשר לראות את הדוגמאות המלאות למודעות מתגמלות בשפה המועדפת עליכם: