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

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

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

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

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

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

ca-app-pub-3940256099942544/1712485313

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

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

הטמעה

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

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

טעינת מודעה

הטעינה של מודעה מתבצעת באמצעות המסנן הסטטי השיטה loadWithAdUnitID:request:completionHandler: ב כיתה אחת (GADRewardedAd). לשיטת הטעינה נדרש מזהה יחידת המודעות שלך, אובייקט GADRequest ו-handler של השלמה נשלחת קריאה כשטעינת המודעה מצליחה או נכשלת. הפריטים שנטענו אובייקט GADRewardedAd סופק כפרמטר בהשלמה המטפל. הדוגמה הבאה מראה איך לטעון 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 סופקו השיטה startWithCompletionHandler:, גם אם הרשת לבחירת רשת (Mediation) עדיין לא האתחול הושלם.
מה קורה אם חלק מהרשתות בתהליך בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) של האתחול?

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

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

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

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

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

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

דוגמאות ב-GitHub

השלבים הבאים

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