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

בחירת פלטפורמה: Android iOS Unity Flutter

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

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

• כדאי לעיין במדריך לתחילת העבודה.

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

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

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

/21775744923/example/rewarded

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

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

הטמעה

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

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

טעינת מודעה

טעינת מודעה מתבצעת באמצעות השיטה 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: "/21775744923/example/rewarded", request: AdManagerRequest())
    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:@"/21775744923/example/rewarded"
              request:[GAMRequest 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

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

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

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

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

Swift

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

נקודה חשובה: מחרוזת התגמול המותאמת אישית היא percent escaped ועשויה לדרוש פענוח כשמנתחים אותה מקריאה חוזרת (callback) של אימות בצד השרת (SSV).

הרשמה להתקשרות חזרה

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

Swift

rewardedAd?.fullScreenContentDelegate = self
ViewController.swift

SwiftUI

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Objective-C

self.rewardedAd.fullScreenContentDelegate = self;
ViewController.m

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

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?

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

האם יש פסק זמן לשיחת ההפעלה?

אחרי 10 שניות, Google Mobile Ads SDK מפעיל את GADInitializationCompletionHandler שסופק לשיטת startWithCompletionHandler:, גם אם רשת גישור עדיין לא סיימה את ההפעלה.

מה קורה אם חלק מרשתות הגישור לא מוכנות כשאני מקבל את הקריאה החוזרת לאתחול?

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

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

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

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

האם תמיד מתבצעת קריאה ל-completion handler‏ userDidEarnRewardHandler לפני השיטה adDidDismissFullScreenContent: של delegate?

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

דוגמאות ב-GitHub

אפשר לראות את הדוגמאות המלאות של מודעות מתגמלות בשפה המועדפת:

• Swift
• SwiftUI
• ‫Objective-C

השלבים הבאים

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