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

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

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

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

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

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

/21775744923/example/rewarded

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

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

הטמעה

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

  • טעינת מודעה
  • [אופציונלי] אימות התקשרות חזרה של 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)")
    }
  }

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;
    }];

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

כדי לקבל התראות על אירועי הצגה, צריך להטמיע את פרוטוקול 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

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

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
}

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
      }

הצגת המודעה המתגמלת מהמודל לצפייה:

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

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:, גם אם רשת תהליך בחירת הרשת עדיין לא השלימה את ההפעלה.
מה קורה אם חלק מהרשתות בתהליך בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) של האתחול?

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

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

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

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

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

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

דוגמאות ב-GitHub

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

השלבים הבאים

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