Reklamy z nagrodą


Reklamy z nagrodą dają użytkownikom możliwość interakcji 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 C++.

Przeczytaj kilka historii 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 reklam rzeczywistych. W przeciwnym razie Twoje konto może zostać zawieszone.

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

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

Zostały one specjalnie skonfigurowane tak, aby zwracać reklamy testowe w odpowiedzi na każde żądanie. Możesz ich używać w swoich aplikacjach podczas kodowania, testowania i debugowania. Pamiętaj tylko, aby przed opublikowaniem aplikacji zastąpić je własnym identyfikatorem jednostki reklamowej.

Więcej informacji o tym, jak działają reklamy testowe w pakiecie SDK do reklam mobilnych, znajdziesz w artykule Reklamy testowe.

Implementacja

Główne kroki integracji reklam z nagrodą:

  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. Pierwszym krokiem do zintegrowania reklam z nagrodą 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, używając widoku rodzica przekształconego na typ AdParent. Widok rodzica to odwołanie JNI jobject do Activity na Androidzie lub wskaźnik do UIView na iOS.

    // 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 firebase::Future znajdziesz w artykule Używanie przyszłości do monitorowania stanu zakończenia wywołań metod.

Wczytaj reklamę

Wczytywanie reklamy odbywa się za pomocą metody LoadAd() na obiekcie RewardedAd. Metoda wczytywania wymaga zainicjowania obiektu RewardedAd, a także identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracana jest wartość firebase::Future, której możesz użyć do monitorowania stanu i wyniku operacji wczytywania.

Poniższy kod pokazuje, jak wczytać reklamę po pomyślnym 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 wywołania zwrotne

Aby otrzymywać powiadomienia o wyświetlaniu reklam z nagrodą i zdarzeniach cyklu życia, musisz rozszerzyć klasę FullScreenContentListener. Twoją niestandardową FullScreenContentListener podklasę można zarejestrować za pomocą metody RewardedAd::SetFullScreenContentListener(). Będzie ona otrzymywać wywołania zwrotne, gdy reklama zostanie wyświetlona pomyślnie lub nie, a także 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 wyświetlić ponownie. Zgodnie ze sprawdzoną metodą wczytaj kolejną reklamę z nagrodą w metodzie OnAdDismissedFullScreenContent() klasy FullScreenContentListener, aby następna reklama z nagrodą zaczęła się wczytywać, gdy tylko poprzednia zostanie zamknięta.

Wyświetl reklamę i obsłuż zdarzenie nagrody

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz dać im wyraźną możliwość obejrzenia 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, aby obsłużyć nagrodę dla użytkownika.

Poniższy 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 wywołanie inicjowania ma limit czasu?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w C++ kończy działanie firebase::Future zwróconego 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?

Zgodnie ze sprawdzoną metodą reklamy należy wczytywać 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.

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

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

AdapterStatus.description() opisuje, dlaczego adapter nie jest gotowy do obsługi żądań reklam. Przykład logowania stanu adaptera zapośredniczenia znajdziesz w kodzie źródłowym naszej przykładowej aplikacji krótkiego wprowadzenia w GitHubie.

Dodatkowe materiały

Przykład w GitHubie