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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

במאמר מודעות בדיקה מוסבר איך פועלות מודעות הבדיקה של Mobile Ads SDK.

הטמעה

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

  • טעינת מודעה
  • [אופציונלי] אימות התקשרות חזרה של 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() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

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.");
      }];
}

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

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

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

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
  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:@"ca-app-pub-3940256099942544/1712485313"
              request:[GADRequest 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 מטפל בקריאות חוזרות (callback) במקרים שבהם המודעה מוצגת בהצלחה או נכשלת, וכשהיא נסגרת. הקוד הבא מראה איך להטמיע את הפרוטוקול ולהקצות אותו למודעה:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
      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.")
  }
}

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() {
  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.
  }
}

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?
כן, אם אתם צריכים את סכום התגמול לפני הפעלת הקריאה החוזרת של userDidEarnReward, ב-GADRewardedAd יש מאפיין adReward, שאפשר לבדוק כדי לאמת את סכום התגמול אחרי שהמודעה נטענת.
האם יש זמן קצוב לתפוגה עבור קריאת האתחול?
אחרי 10 שניות, Google Mobile Ads SDK מפעיל את GADInitializationCompletionHandler שסופק ל-method startWithCompletionHandler:, גם אם האתחול של הרשת לבחירת הרשת עדיין לא הושלם.
מה קורה אם חלק מהרשתות בתהליך בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) של האתחול?

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

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

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

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

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

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

דוגמאות ב-GitHub

השלבים הבאים

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