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

הפלטפורמה: Android iOS Unity Flutter

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

הטמעה

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

  • טעינת מודעה
  • [אופציונלי] אימות קריאות חוזרות של 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: "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 בנתונים המותאמים אישית.

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

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

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 לפני השיטה של delegate‏ adDidDismissFullScreenContent:?

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

דוגמאות ב-GitHub

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

השלבים הבאים

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