Reklamy z nagrodą


Reklamy z nagrodą dają użytkownikom możliwość interakcji w zamian za nagrody w aplikacji. Z tego przewodnika dowiesz się, jak zintegrować reklamy z nagrodą z aplikacjami na Androida i iOS przy użyciu pakietu SDK do reklam mobilnych Google w C++.

Przeczytaj historie sukcesu klientów: studium przypadku 1, studium przypadku 2.

Wymagania wstępne

Zawsze testuj za pomocą reklam testowych

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

Najłatwiejszym sposobem wczytywania reklam testowych jest użycie specjalnego identyfikatora jednostki reklamowej do testowania reklam z nagrodą, który różni się w zależności od platformy urządzenia:

  • System Android: ca-app-pub-3940256099942544/5224354917
  • System iOS: ca-app-pub-3940256099942544/1712485313

Został 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

Główne kroki integracji reklam z nagrodą to:

  1. Wczytaj reklamę.
  2. Zarejestruj wywołania zwrotne.
  3. Wyświetl reklamę i obsłuż zdarzenie nagrody.

Skonfiguruj RewardedAd

Reklamy z nagrodą są wyświetlane w obiektach RewardedAd, więc pierwszym krokiem do zintegrowania ich z aplikacją jest utworzenie i zainicjowanie instancji RewardedAd.

  1. Dodaj ten nagłówek do kodu C++ aplikacji: 

     #include "firebase/gma/rewarded_ad.h"

  2. Zadeklaruj i utwórz instancję obiektu RewardedAd: 

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. Zainicjuj instancję RewardedAd za pomocą widoku rodzica przekształconego w typ AdParent. Widok nadrzędny to odwołanie JNI jobject do AndroidaActivity lub wskaźnik do iOS UIView.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. Zamiast zachowywać przyszłość jako zmienną, możesz okresowo sprawdzać stan operacji inicjowania, wywołując InitializeLastResult() na obiekcie RewardedAd. Może to być przydatne do śledzenia procesu inicjowania w globalnej pętli gry.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

Więcej informacji o pracy z obiektami firebase::Future znajdziesz w artykule Monitorowanie stanu zakończenia wywołań metod za pomocą obiektów Futures.

Wczytywanie reklamy

Reklamę wczytuje się za pomocą metody LoadAd() w obiekcie RewardedAd. Metoda wczytywania wymaga zainicjowania obiektu RewardedAd oraz podania identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracany jest obiekt A firebase::Future, którego możesz użyć do monitorowania stanu i wyniku operacji wczytywania.

Poniższy kod pokazuje, jak wczytać reklamę po prawidłowym zainicjowaniu RewardedAd:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

Rejestrowanie wywołań zwrotnych

Aby otrzymywać powiadomienia o wyświetlaniu reklam z nagrodą i zdarzeniach związanych z ich cyklem życia, musisz rozszerzyć klasę FullScreenContentListener. Twoją niestandardową podklasę FullScreenContentListener można zarejestrować za pomocą metody RewardedAd::SetFullScreenContentListener(). Będzie ona otrzymywać wywołania zwrotne, gdy reklama zostanie wyświetlona (lub nie) oraz gdy zostanie zamknięta.

Poniższy kod pokazuje, jak rozszerzyć klasę i przypisać ją do reklamy:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd to obiekt jednorazowego użytku. Oznacza to, że po wyświetleniu reklamy z nagrodą nie można jej ponownie wyświetlić. Zgodnie ze sprawdzoną metodą wczytaj kolejną reklamę z nagrodą w metodzie OnAdDismissedFullScreenContent()FullScreenContentListener, aby następna reklama z nagrodą zaczęła się wczytywać, gdy tylko poprzednia zostanie zamknięta.

Wyświetlanie reklamy i obsługa zdarzenia związanego z nagrodą

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz dać im możliwość wyrażenia jednoznacznej zgody na obejrzenie treści reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą muszą zawsze wymagać zgody użytkownika.

Podczas wyświetlania reklamy musisz podać obiekt UserEarnedReward, który będzie obsługiwać nagrodę dla użytkownika.

Poniższy kod pokazuje, jak wyświetlić element RewardedAd:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

Najczęstsze pytania

Czy połączenie inicjujące ma limit czasu?
Po 10 sekundach pakiet Google Mobile Ads C++ SDK kończy działanie funkcji firebase::Future zwróconej przez Initialize(), nawet jeśli sieć zapośredniczenia nie zakończyła jeszcze inicjowania.
Co się stanie, jeśli niektóre sieci zapośredniczenia nie będą gotowe, gdy otrzymam wywołanie zwrotne inicjowania?

Sprawdzoną metodą jest wczytywanie reklam po zakończeniu inicjowania pakietu SDK. Nawet jeśli sieć zapośredniczenia nie jest gotowa, pakiet SDK do reklam mobilnych Google w C++ nadal będzie wysyłać do niej żądanie reklamy. Jeśli więc sieć zapośredniczenia zakończy inicjowanie po upływie limitu czasu, nadal będzie mogła obsługiwać przyszłe żądania reklam w tej sesji.

Stan inicjowania wszystkich adapterów możesz sprawdzać przez cały czas trwania sesji w aplikacji, wywołując funkcję GetInitializationStatus().

Jak sprawdzić, dlaczego konkretna sieć zapośredniczenia nie jest gotowa?

AdapterStatus.description() wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklam. Przykład rejestrowania stanu adaptera do mediacji znajdziesz w kodzie źródłowym naszej przykładowej aplikacji do szybkiego rozpoczęcia w GitHubie.

Dodatkowe materiały

Przykład w GitHubie