Reklamy z nagrodą

Reklamy z nagrodą umożliwiają użytkownikom interakcję z nimi w zamian za nagrody w aplikacji. Z tego przewodnika dowiesz się, jak zintegrować reklamy z nagrodą z aplikacjami na Androida i iOS za pomocą pakietu SDK do reklam mobilnych Google w języku 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, a nie aktywnych wersji produkcyjnej. Jeśli tego nie zrobisz, Twoje konto może zostać zawieszone.

Najprostszym sposobem wczytywania reklam testowych jest użycie na potrzeby reklam z nagrodą dedykowanego testowego identyfikatora jednostki reklamowej, 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ły one specjalnie skonfigurowane tak, aby zwracały reklamy testowe w odpowiedzi na każde żądanie. Możesz ich używać w swoich aplikacjach przy kodowaniu, testowaniu i debugowaniu. Pamiętaj, aby przed opublikowaniem aplikacji zastąpić go własnym identyfikatorem jednostki reklamowej.

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

Implementacja

Główne kroki, które należy wykonać, aby zintegrować reklamy z nagrodą:

  1. Wczytaj reklamę.
  2. Zarejestruj się na wywołania zwrotne.
  3. Wyświetla reklamę i obsługuje zdarzenie nagrody.

Skonfiguruj: RewardedAd

Reklamy z nagrodą są wyświetlane w obiektach RewardedAd, dlatego pierwszym krokiem do integracji reklam z nagrodą z aplikacją jest utworzenie i zainicjowanie wystąpienia obiektu 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 nadrzędnego rzutu na typ AdParent. Widok nadrzędny to odwołanie do systemu JNI jobject do Androida Activity lub wskaźnik do systemu 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 przechowywać przyszłość jako zmienną, możesz okresowo sprawdzać stan operacji inicjowania, wywołując InitializeLastResult() w obiekcie RewardedAd. Pozwala śledzić proces 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 firebase::Future znajdziesz w artykule o używaniu transakcji terminowych do monitorowania stanu ukończenia wywołań metod.

Wczytywanie reklamy

Wczytywanie reklamy odbywa się za pomocą metody LoadAd() na obiekcie RewardedAd. Metoda wczytywania wymaga zainicjowania obiektu RewardedAd oraz posiadania identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracany jest parametr firebase::Future, którego można użyć do monitorowania stanu i wyniku operacji wczytywania.

Poniższy kod pokazuje, jak wczytać reklamę po 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);

Zarejestruj się na wywołania zwrotne

Aby otrzymywać powiadomienia o prezentacji reklam z nagrodą i zdarzeniach cyklu życia, musisz rozszerzyć klasę FullScreenContentListener. Podklasę niestandardową FullScreenContentListener możesz zarejestrować za pomocą metody RewardedAd::SetFullScreenContentListener() i będzie ona otrzymywać wywołania zwrotne zarówno po wyświetleniu, jak i niepowodzeniem wyświetlenia reklamy oraz po jej odrzuceniu.

Poniższy kod pokazuje, jak rozszerzyć zajęcia i przypisać je 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 jednorazowy. Oznacza to, że raz wyświetlona reklama z nagrodą nie będzie mogła zostać wyświetlona ponownie. Sprawdzoną metodą jest wczytanie kolejnej reklamy z nagrodą za pomocą metody OnAdDismissedFullScreenContent() obiektu FullScreenContentListener, tak aby następna reklama z nagrodą zaczęła ładować się od razu po odrzuceniu poprzedniej.

Wyświetlanie reklamy i obsługa zdarzenia nagrody

Przed wyświetleniem reklamy z nagrodą musisz zaoferować im możliwość obejrzenia treści reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą muszą być zawsze dostępne po wyrażeniu zgody.

Podczas wyświetlania reklamy musisz podać obiekt UserEarnedReward do obsługi nagrody dla użytkownika.

Ten kod pokazuje, jak wyświetlić 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 określono czas oczekiwania na wywołanie inicjowania?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w języku C++ ukończy procedurę firebase::Future zwracaną przez funkcję Initialize(), nawet jeśli sieć zapośredniczenia nadal nie ukończyła inicjowania.
Co zrobić, jeśli niektóre sieci zapośredniczenia nie są gotowe, gdy otrzymam wywołanie zwrotne inicjowania?

Sprawdzoną metodą jest wczytywanie reklam po zakończeniu inicjowania pakietu SDK. Nawet jeśli sieć zapośredniczeń nie jest gotowa, pakiet SDK do reklam mobilnych Google w języku C++ nadal będzie prosić ją o wyświetlenie reklamy. Jeśli więc sieć zapośredniczeń zakończy inicjowanie po upływie limitu czasu, nadal może obsługiwać przyszłe żądania reklamy w tej sesji.

Możesz nadal sondować stan inicjowania wszystkich adapterów podczas sesji aplikacji, wywołując metodę GetInitializationStatus().

Jak mogę sprawdzić, dlaczego dana sieć zapośredniczenia nie jest gotowa?

AdapterStatus.description() wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklamy. Przykład rejestrowania stanu adaptera zapośredniczenia znajdziesz w kodzie źródłowym naszej przykładowej aplikacji z krótkim wprowadzeniem na GitHubie.

Dodatkowe zasoby

Przykład w GitHubie