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

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

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

• Google Mobile Ads SDK בגרסה 8.0.0 ואילך.
• קוראים את המדריך לתחילת העבודה.

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

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

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

/21775744923/example/rewarded

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

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

הטמעה

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

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

טעינת מודעה

הטעינה של מודעה מתבצעת באמצעות השיטה load(adUnitID:request) בכיתה GADRewardedAd.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/21775744923/example/rewarded", request: GAMRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, GADFullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: GADRewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }
RewardedViewModel.swift

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/21775744923/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.");
      }];
}

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

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

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

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

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "/21775744923/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:@"/21775744923/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;
    }];

חשוב: החל מגרסה 7.50.0 של ה-SDK, אפשר להגדיר את מחרוזת התגמול בהתאמה אישית בכל שלב.

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

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

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/21775744923/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.")
  }
}

SwiftUI

מקצים את המאפיין fullScreenContentDelegate למודעה שהוחזרה:

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

מטמיעים את הפרוטוקול:

func adDidRecordImpression(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: GADFullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}
RewardedViewModel.swift

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.
  }
}

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(fromRootViewController: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedViewModel.swift

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 שסופק לשיטה startWithCompletionHandler:, גם אם רשת תהליך בחירת הרשת עדיין לא השלימה את ההפעלה.

מה קורה אם חלק מרשתות בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) להפעלה?

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

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

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

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

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

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

דוגמאות ב-GitHub

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

• Swift
• SwiftUI
• Objective-C

השלבים הבאים

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