מודעות מתגמלות

בחירת פלטפורמה: Android iOS Unity Flutter Android (גרסה קודמת)

מודעות מתגמלות הן מודעות שהמשתמשים יכולים לבחור לבצע בהן פעולות בתמורה לתגמולים באפליקציה. במדריך הזה מוסבר איך לשלב באפליקציה ל-iOS מודעות מתגמלות מ-AdMob. כדאי לקרוא כמה סיפורי הצלחה של לקוחות: מקרה לדוגמה 1, מקרה לדוגמה 2.

דרישות מוקדמות

לפני שממשיכים, מגדירים את Google Mobile Ads SDK.

תמיד צריך לבדוק באמצעות מודעות בדיקה

כשאתם מפתחים ובודקים את האפליקציות, חשוב להשתמש במודעות בדיקה ולא במודעות פעילות. אחרת, אנחנו עלולים להשעות את החשבון.

הדרך הכי קלה לטעון מודעות לבדיקה היא להשתמש במזהה יחידת המודעות הייעודי לבדיקה של מודעות מתגמלות ב-iOS:

ca-app-pub-3940256099942544/1712485313

הוא הוגדר במיוחד כדי להחזיר מודעות בדיקה לכל בקשה, ואתם יכולים להשתמש בו באפליקציות שלכם בזמן התכנות, הבדיקה וניפוי הבאגים. רק חשוב להחליף אותו במזהה יחידת המודעות שלכם לפני שמפרסמים את האפליקציה.

מידע נוסף על אופן הפעולה של מודעות בדיקה ב-Google Mobile Ads SDK זמין במאמר מודעות בדיקה.

הטמעה

אלה השלבים העיקריים לשילוב מודעות מתגמלות:

• טעינת מודעה
• [אופציונלי] אימות קריאות חוזרות של SSV
• רישום להתקשרות חזרה
• הצגת המודעה וטיפול באירוע המתגמל

טעינת מודעה

כדי לטעון מודעה, משתמשים ב-method‏ load(adUnitID:request) במחלקה GADRewardedAd.

Swift

func loadRewardedAd() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
ViewController.swift

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, FullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: RewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "ca-app-pub-3940256099942544/1712485313", request: Request())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }
RewardedViewModel.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest request]
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
        return;
      }
      self.rewardedAd = ad;
      self.rewardedAd.fullScreenContentDelegate = self;
    }];
ViewController.m

טיפ: אפשר להשתמש בקריאות לטעינת מודעות כדי ליצור מטמון של מודעות שייטענו מראש לפני שמתכוונים להציג אותן. כך המודעות יוצגו בלי עיכוב שיגיע הזמן לכך. תוקף המודעות פג אחרי שעה, ולכן צריך לנקות את המטמון הזה ולטעון מחדש מודעות חדשות כל שעה.

[אופציונלי] אימות קריאות חוזרות של אימות בצד השרת (SSV)

באפליקציות שנדרשים בהן נתונים נוספים בקריאות חוזרות (callback) של אימות בצד השרת (SSV), צריך להשתמש בתכונה "נתונים מותאמים אישית" של מודעות מתגמלות. כל ערך מחרוזת שמוגדר באובייקט של מודעה מתגמלת מועבר לפרמטר השאילתה custom_data של הקריאה החוזרת ל-SSV. אם לא מוגדר ערך של נתונים מותאמים אישית, הערך של פרמטר השאילתה custom_data לא ייכלל בקריאה החוזרת ל-SSV.

בדוגמת הקוד הבאה אפשר לראות איך מגדירים נתונים מותאמים אישית באובייקט של מודעה מתגמלת לפני ששולחים בקשה להצגת מודעה:

Swift

private func validateServerSideVerification() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "ca-app-pub-3940256099942544/1712485313", request: Request())
    let options = ServerSideVerificationOptions()
    options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
    rewardedAd?.serverSideVerificationOptions = options
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}
RewardedAdSnippets.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:[GADRequest request]
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  NSLog(@"Rewarded ad failed to load with error: %@", error.localizedDescription);
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];
RewardedAdSnippets.m

מחליפים את SAMPLE_CUSTOM_DATA_STRING בנתונים בהתאמה אישית.

נקודה חשובה: מחרוזת התגמול בהתאמה אישית כוללת תו בריחה (escape) באחוזים, ויכול להיות שיהיה צורך לפענח אותה כדי לחלץ אותה מהקריאה החוזרת של SSV.

רישום להתקשרות חזרה

כדי לקבל התראות על אירועי מצגת, צריך להקצות את GADFullScreenContentDelegate למאפיין fullScreenContentDelegate של המודעה שמוחזרת:

Swift

rewardedAd?.fullScreenContentDelegate = self
ViewController.swift

SwiftUI

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Objective-C

self.rewardedAd.fullScreenContentDelegate = self;
ViewController.m

הפרוטוקול GADFullScreenContentDelegate מטפל בקריאות חוזרות (callbacks) כשהמודעה מוצגת בהצלחה או לא מוצגת בהצלחה, וכשהיא נסגרת. הקוד הבא מראה איך להטמיע את הפרוטוקול:

Swift

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
  // Clear the rewarded ad.
  rewardedAd = nil
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called with error: \(error.localizedDescription).")
}
ViewController.swift

SwiftUI

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}
RewardedViewModel.swift

Objective-C

- (void)adDidRecordImpression:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidRecordClick:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillPresentFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
  // Clear the rewarded ad.
  self.rewardedAd = nil;
}

- (void)ad:(id)ad didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"%s called with error: %@", __PRETTY_FUNCTION__, error.localizedDescription);
}
ViewController.m

הצגת המודעה וטיפול באירוע המתגמל

לפני שמציגים למשתמשים מודעה מתגמלת, צריך להציג להם אפשרות בחירה מפורשת לצפות בתוכן של מודעה מתגמלת בתמורה לתגמול. מודעות מתגמלות חייבות תמיד להיות חוויה שהמשתמשים בוחרים בה.

כשמציגים את המודעה, צריך לספק אובייקט GADUserDidEarnRewardHandler כדי לטפל בתגמול למשתמש.

בדוגמה הבאה מוצגת השיטה הכי טובה להצגה של מודעה מתגמלת:

Swift

rewardedAd.present(from: self) {
  let reward = rewardedAd.adReward
  print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")

  // TODO: Reward the user.
}
ViewController.swift

SwiftUI

האזינו לאירועים של ממשק המשתמש בתצוגה כדי לקבוע מתי להציג את המודעה.

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }
RewardedContentView.swift

מציגים את המודעה המתגמלת מהמודל של התצוגה:

func showAd() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  rewardedAd.present(from: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedViewModel.swift

Objective-C

[self.rewardedAd presentFromRootViewController:self
                      userDidEarnRewardHandler:^{
                        GADAdReward *reward = self.rewardedAd.adReward;
                        NSString *rewardMessage = [NSString
                            stringWithFormat:@"Reward received with currency %@ , amount %lf",
                                             reward.type, [reward.amount doubleValue]];
                        NSLog(@"%@", rewardMessage);

                        // TODO: Reward the user.
                      }];
ViewController.m

שאלות נפוצות

אפשר לקבל את פרטי הפרס של GADRewardedAd?

כן, אם אתם צריכים את סכום התגמול לפני שהקריאה החוזרת (callback) של userDidEarnReward מופעלת, ל-GADRewardedAd יש מאפיין adReward שאפשר לבדוק כדי לאמת את סכום התגמול אחרי שהמודעה נטענה.

האם יש זמן קצוב לתפוגה של קריאת האתחול?

אחרי 10 שניות, Google Mobile Ads SDK מפעיל את GADInitializationCompletionHandler שסופק ל-method‏ startWithCompletionHandler:, גם אם רשת בתהליך בחירת הרשת עדיין לא סיימה את תהליך האיניציאליזציה.

מה קורה אם חלק מהרשתות שמשתתפות בתהליך בחירת הרשת (Mediation) לא מוכנות כשאני מקבל/ת את הקריאה החוזרת (callback) של האתחול?

מומלץ לטעון מודעה בתוך GADInitializationCompletionHandler. גם אם רשת בתהליך בחירת הרשת לא מוכנה, Google Mobile Ads SDK עדיין מבקש ממנה מודעה. לכן, אם רשת לבחירת רשת מסיימת את תהליך האיניציאליזציה אחרי הזמן הקצוב לתפוגה, היא עדיין יכולה לטפל בבקשות עתידיות להצגת מודעות באותו סשן.

אפשר להמשיך לדגום את סטטוס האיניציאליזציה של כל המתאמים במהלך הסשן באפליקציה באמצעות קריאה ל-GADMobileAds.initializationStatus.

איך אפשר לברר למה רשת מסוימת בתהליך בחירת הרשת (Mediation) לא מוכנה?

המאפיין description של אובייקט GADAdapterStatus מתאר למה מתאם לא מוכן לטפל בבקשות להצגת מודעות.

האם ה-completion handler של userDidEarnRewardHandler תמיד נקרא לפני ה-delegate method של adDidDismissFullScreenContent:?

במודעות Google, כל userDidEarnRewardHandler הקריאות מתרחשות לפני adDidDismissFullScreenContent:. במודעות שמוצגות דרך תהליך בחירת הרשת (Mediation), ההטמעה של ה-SDK של רשת המודעות של הצד השלישי קובעת את סדר הקריאות החוזרות. ב-SDK של רשתות מודעות שמספקות שיטת נציג אחת עם פרטי התגמול, המתאם של תהליך בחירת הרשת מפעיל את userDidEarnRewardHandler לפני adDidDismissFullScreenContent:.

דוגמאות ב-GitHub

דוגמאות מלאות למודעות מתגמלות בשפה המועדפת עליכם:

• Swift
• SwiftUI
• Objective-C

השלבים הבאים

מידע נוסף על פרטיות המשתמשים