מודעת מעברון מתגמלת (בטא)

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

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

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

הטמעה

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

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

טעינת מודעה

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

  override func viewDidLoad() {
    super.viewDidLoad()

    Task {
      do {
        rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
          withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
      } catch {
        print("Failed to load rewarded interstitial ad with error: \(error.localizedDescription)")
      }
    }
  }
}

SwiftUI

import GoogleMobileAds

class RewardedInterstitialViewModel: NSObject, ObservableObject,
  GADFullScreenContentDelegate
{
  @Published var coins = 0
  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

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

Objective-C

#import "ViewController.h"

@interface ViewController ()
@property(nonatomic, strong) GADRewardedInterstitialAd* rewardedInterstitialAd;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  [GADRewardedInterstitialAd
      loadWithAdUnitID:@"<var label='the ad unit ID'>ca-app-pub-3940256099942544/6978759866</var>"
                request:[GADRequest request]
      completionHandler:^(
          GADRewardedInterstitialAd* _Nullable rewardedInterstitialAd,
          NSError* _Nullable error) {
        if (!error) {
          self.rewardedInterstitialAd = rewardedInterstitialAd;
        }
      }
  ];
}

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

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

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

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

Swift

do {
  rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
    withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedInterstitialAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedInterstitialAd
    loadWithAdUnitID:@"ca-app-pub-3940256099942544/6978759866"
              request:GADRequest
    completionHandler:^(GADRewardedInterstitialAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedInterstitialAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

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

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

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

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedInterstitialAd: GADRewardedInterstitialAd?

  override func viewDidLoad() {
    super.viewDidLoad()

    Task {
      do {
        rewardedInterstitialAd = try await GADRewardedInterstitialAd.load(
          withAdUnitID: "ca-app-pub-3940256099942544/6978759866", request: GADRequest())
        self.rewardedInterstitialAd?.fullScreenContentDelegate = self
      } catch {
        print("Failed to load rewarded interstitial ad 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 למודעה שהוחזרה:

rewardedInterstitialAd?.fullScreenContentDelegate = self
RewardedInterstitialViewModel.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 interstitial ad.
  rewardedInterstitialAd = nil
}
RewardedInterstitialViewModel.swift

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>
@property(nonatomic, strong) GADRewardedInterstitialAd *rewardedInterstitialAd;
@end

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];
  // Do any additional setup after loading the view.

  [GADRewardedInterstitialAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/6978759866"
                request:[GADRequest request]
      completionHandler:^(
          GADRewardedInterstitialAd *_Nullable rewardedInterstitialAd,
          NSError *_Nullable error) {
        if (!error) {
          self.rewardedInterstitialAd = rewardedInterstitialAd;
          self.rewardedInterstitialAd.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.");
}

הצגת המודעה וטיפול באירוע של מתן הפרס

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

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

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

Swift

func show() {
  guard let rewardedInterstitialAd = rewardedInterstitialAd else {
    return print("Ad wasn't ready.")
  }

  // The UIViewController parameter is an optional.
  rewardedInterstitialAd.present(fromRootViewController: nil) {
    let reward = rewardedInterstitialAd.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

SwiftUI

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

var rewardedInterstitialBody: some View {
  // ...
  }
  .onChange(
    of: showAd,
    perform: { newValue in
      if newValue {
        viewModel.showAd()
      }
    }
  )
RewardedInterstitialContentView.swift

הצגת מודעת המעברון המתגמלת באמצעות מודל התצוגה:

func showAd() {
  guard let rewardedInterstitialAd = rewardedInterstitialAd else {
    return print("Ad wasn't ready.")
  }

  rewardedInterstitialAd.present(fromRootViewController: nil) {
    let reward = rewardedInterstitialAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedInterstitialViewModel.swift

Objective-C

- (void)show {
  // The UIViewController parameter is nullable.
  [_rewardedInterstitialAd presentFromRootViewController:nil
                                userDidEarnRewardHandler:^{

                                  GADAdReward *reward =
                                      self.rewardedInterstitialAd.adReward;
                                  // TODO: Reward the user.
                                }];
}

דוגמאות ב-GitHub

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

• Swift
• SwiftUI
• Objective-C

השלבים הבאים

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