Reklamy z nagrodą

Reklamy z nagrodą to reklamy, z którymi użytkownicy mogą wchodzić w interakcje w zamian za nagrody w aplikacji. Z tego przewodnika dowiesz się, jak zintegrować reklamy z nagrodą z Ad Managera w aplikacji na iOS.

Wymagania wstępne

• Pakiet SDK do reklam mobilnych Google w wersji 8.0.0 lub nowszej.
• Zapoznaj się z przewodnikiem dla początkujących.

Zawsze testuj reklamy za pomocą reklam testowych

Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie reklam produkcyjnych. Jeśli tego nie zrobisz, Twoje konto może zostać zawieszone.

Najłatwiejszym sposobem wczytywania reklam testowych jest użycie dedykowanego identyfikatora testowej jednostki reklamowej na potrzeby reklam z nagrodą na iOS:

/21775744923/example/rewarded

Jest on specjalnie skonfigurowany tak, aby zwracać reklamy testowe w przypadku każdego żądania. Możesz go używać w swoich aplikacjach podczas kodowania, testowania i debugowania. Pamiętaj tylko, aby przed opublikowaniem aplikacji zastąpić go własnym identyfikatorem jednostki reklamowej.

Więcej informacji o działaniu reklam testowych w pakiecie SDK do reklam mobilnych znajdziesz w artykule Reklamy testowe.

Implementacja

Oto główne etapy integracji reklam z nagrodą:

• Wczytywanie reklamy
• [Opcjonalnie] Weryfikowanie wywołań zwrotnych SSV
• Zarejestruj się na wywołania zwrotne
• Wyświetl reklamę i obsługuje zdarzenie nagrody

Wczytywanie reklamy

Ładowanie reklamy odbywa się za pomocą metody load(adUnitID:request) w klasie 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.");
      }];
}

Wskazówka: przed wyświetleniem reklam możesz użyć wywołań wczytywania reklam, aby utworzyć pamięć podręczną z wstępnie załadowanymi reklamami. Dzięki temu w razie potrzeby reklamy będą mogły być wyświetlane bez opóźnień. Reklamy tracą ważność po godzinie, dlatego co godzinę należy wyczyścić pamięć podręczną i załadować nowe reklamy.

[Opcjonalnie] Walidowanie wywołań zwrotnych weryfikacji po stronie serwera (SSV)

Aplikacje, które wymagają dodatkowych danych w zwrotach wywołania weryfikacji po stronie serwera, powinny korzystać z funkcji danych niestandardowych reklam z nagrodą. Każda wartość ciągu ustawiona w obiekcie reklamy z nagrodą jest przekazywana do parametru zapytania custom_data wywołania zwrotnego SSV. Jeśli nie ustawisz wartości danych niestandardowych, parametr zapytania custom_data nie będzie obecny w wywołaniu zwrotnym SSV.

Poniższy przykładowy kod pokazuje, jak ustawić dane niestandardowe obiektu reklamy z nagrodą przed wysłaniem prośby o reklamę.

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

Ważne: od pakietu SDK w wersji 7.50.0 niestandardowy ciąg znaków nagrody można ustawić w każdej chwili.

Ważne: niestandardowy ciąg znaków nagrody jest zakodowany za pomocą znaku zmiany znaczenia i może wymagać dekodowania podczas analizy z wywołania zwrotnego SSV.

Zarejestruj się na wywołania zwrotne

Aby otrzymywać powiadomienia o zdarzeniach związanych z prezentacją, musisz zaimplementować protokół GADFullScreenContentDelegate i przypisać go do właściwości fullScreenContentDelegate zwracanej reklamy. Protokół GADFullScreenContentDelegate obsługuje wywołania zwrotne w przypadku wyświetlenia reklamy (udanego lub nieudanego) oraz jej odrzucenia. Ten kod pokazuje, jak wdrożyć protokół i przypisać go do reklamy:

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

Przypisz do zwróconej reklamy właściwość fullScreenContentDelegate:

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Zaimplementuj protokół:

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 to obiekt jednorazowego użytku. Oznacza to, że po wyświetleniu reklamy z nagrodą nie można jej wyświetlić ponownie. Najlepiej wczytać kolejną reklamę z nagrodą za pomocą metody adDidDismissFullScreenContent: w komponencie GADFullScreenContentDelegate, aby następna reklama z nagrodą zaczęła się wczytywać, gdy tylko zamkniesz poprzednią.

Wyświetl reklamę i obsługuje zdarzenie nagrody

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz umożliwić im wyraźny wybór treści reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą muszą być zawsze opcjonalne.

Podczas wyświetlania reklamy musisz podać obiekt GADUserDidEarnRewardHandler, aby obsłużyć nagrodę dla użytkownika.

Poniższy kod przedstawia najlepszą metodę wyświetlania reklamy z nagrodą.

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

Wykrywaj zdarzenia interfejsu w widoku, aby określić, kiedy wyświetlić reklamę.

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }
RewardedContentView.swift

Wyświetl reklamę z nagrodą w ramach modelu wyświetlania:

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

Najczęstsze pytania

Czy mogę uzyskać szczegóły nagrody GADRewardedAd?

Jeśli potrzebujesz kwoty nagrody przed wywołaniem funkcji userDidEarnReward, GADRewardedAd ma właściwość adReward, którą możesz sprawdzić, aby potwierdzić kwotę nagrody po załadowaniu reklamy.

Czy istnieje limit czasu oczekiwania na wywołanie inicjujące?

Po 10 sekundach pakiet SDK do reklam mobilnych Google wywołuje funkcję GADInitializationCompletionHandler podaną w metodzie startWithCompletionHandler:, nawet jeśli sieć zapośredniczenia nie ukończyła jeszcze inicjalizacji.

Co zrobić, jeśli niektóre sieci pośredniczące nie są gotowe, gdy otrzymam wywołanie zwrotne inicjalizowania?

Zalecamy wczytanie reklamy w ramach GADInitializationCompletionHandler. Nawet jeśli sieć zapośredniczenia nie jest gotowa, pakiet SDK do reklam mobilnych Google nadal wysyła do niej żądanie reklamy. Jeśli sieć zapośredniczenia zakończy inicjowanie po upływie limitu czasu, nadal może obsługiwać przyszłe żądania reklamy w tej sesji.

Możesz nadal sprawdzać stan inicjalizacji wszystkich adapterów podczas sesji aplikacji, wywołując funkcję GADMobileAds.initializationStatus.

Jak sprawdzić, dlaczego dana sieć pośrednicząca nie jest gotowa?

Właściwość description obiektu GADAdapterStatus wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklamy.

Czy metoda obsługi zakończenia userDidEarnRewardHandler jest zawsze wywoływana przed metodą delegowaną adDidDismissFullScreenContent:?

W przypadku reklam Google wszystkie wywołania userDidEarnRewardHandler mają miejsce przed adDidDismissFullScreenContent:. W przypadku reklam wyświetlanych w ramach zapośredniczenia kolejność wywołań zależy od implementacji zewnętrznego pakietu SDK sieci reklamowej. W przypadku pakietów SDK sieci reklamowych, które udostępniają informacje o nagrodzie za pomocą pojedynczej metody przekazywania, adapter zapośredniczenia wywołuje userDidEarnRewardHandler przed adDidDismissFullScreenContent:.

Przykłady w GitHub

Zobacz pełne przykłady reklam z nagrodą w wybranym języku:

• Swift
• SwiftUI
• Objective-C

Dalsze kroki

Dowiedz się więcej o prywatności użytkowników.