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

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

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

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

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

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

/6499/example/rewarded

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

רוצים לדעת איך מודעות הבדיקה ב-Mobile Ads SDK פועלות במאמר מודעות בדיקה?

הטמעה

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

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

טעינת מודעה

מתבצעת טעינה של מודעה באמצעות השיטה loadWithAdUnitID:request:completionHandler: הסטטית במחלקה GADRewardedAd. לשיטת הטעינה, צריך להפעיל את המזהה של יחידת המודעות, אובייקט GAMRequest ו-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: "/6499/example/rewarded", request: GAMRequest())
    } 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 {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/6499/example/rewarded"
                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: "/6499/example/rewarded", request: GAMRequest())
  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:@"/6499/example/rewarded"
              request:[GAMRequest 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;
    }];

הרשמה לקריאה חוזרת (callback)

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

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

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

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

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

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

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

דוגמאות ב-GitHub

השלבים הבאים

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