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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

יישום

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

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

טעינת מודעה

טעינת המודעה מתבצעת באמצעות השיטה loadWithAdUnitID:request:completionHandler: הסטטית במחלקה GADRewardedAd. לשיטת הטעינה נדרשים מזהה יחידת המודעות, אובייקט GADRequest וגורם handler להשלמה שנקרא כשטעינת המודעה מצליחה או נכשלת. האובייקט GADRewardedAd שנטען נטען כפרמטר ב-handler של ההשלמה. בדוגמה הבאה מוסבר איך לטעון GADRewardedAd בכיתה ViewController.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    let request = GADRequest()
    GADRewardedAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("Rewarded ad loaded.")
    }
    )
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GADRequest *request = [GADRequest request];
  [GADRewardedAd
       loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                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.");
      }];
}

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

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

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

Swift

GADRewardedInterstitialAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedInterstitialAd = ad
      let options = GADServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedInterstitialAd.serverSideVerificationOptions = options
    }

Objective-C

GADRequest *request = [GADRequest request];
[GADRewardedInterstitialAd
     loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
              request:request
    completionHandler:^(GADRewardedInterstitialAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedInterstitialAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

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

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

Swift

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    let request = GADRequest()
    GADRewarded.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                     request: request,
                     completionHandler: { [self] ad, error in
      if let error = error {
        print("Failed to load rewarded ad with error: \(error.localizedDescription)")
        return
      }
      rewardedAd = ad
      print("Rewarded ad loaded.")
      rewardedAd?.fullScreenContentDelegate = self
    }
    )
  }

  /// 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 {
  GADRequest *request = [GADRequest 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() {
  if let ad = rewardedAd {
    ad.present(fromRootViewController: self) {
      let reward = ad.adReward
      print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
      // TODO: Reward the user.
    }
  } else {
    print("Ad wasn't ready")
  }
}

Objective-C

- (void)show {
  ...
  if (self.rewardedAd) {
    [self.rewardedAd presentFromRootViewController:self
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

שאלות נפוצות

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

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

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

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

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

האם הגורם המטפל בהשלמת userDidEarnRewardHandler תמיד מתקשר לפני שיטת ההאצלה adDidDismissFullScreenContent:?

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

דוגמאות ל-GitHub

השלבים הבאים

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