Korzystanie z interfejsu Ad Placement API

Interfejs Ad Placement API zawiera 2 funkcje: adBreak() i adConfig(), zdefiniowane w tej globalnej przestrzeni nazw: Większość argumentów to funkcje, które umożliwiają obsługę kluczowych etapów przygotowywania i wyświetlania reklamy:

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

Te funkcje służą do umieszczania i konfigurowania reklam w grze. Argumenty podane powyżej to jedyne prawidłowe argumenty, które można przekazać do tych funkcji. Różne typy reklam wymagają różnych podzbiorów tych argumentów, co opisujemy poniżej.

adBreak() to kluczowa funkcja umieszczania reklam w grze. Określa miejsce docelowe reklamy i przyjmuje obiekt o nazwie konfiguracja miejsca docelowego, który określa wszystko, co jest potrzebne do wyświetlenia reklamy.

Funkcja adBreak() określa miejsce docelowe, w którym może się wyświetlać reklama. To, czy reklama się wyświetli, zależy od takich czynników jak:

  • Zadeklarowany typ miejsca docelowego reklamy
    • Czy ta reklama jest wyświetlana na początku meczu? Między poziomami? w momencie, gdy gracz wstrzymał grę?
  • Czy dla bieżącego odtwarzacza istnieje odpowiednia reklama
    • Czy ta reklama jest dla nich trafna?
    • Czy jest ona zgodna z ustawieniami prywatności i zgody użytkownika?
  • Liczba reklam, które ostatnio widział odtwarzacz
  • Ustawienia kontroli, np. częstotliwość wyświetlania reklam, skonfigurowane przez Ciebie w tej grze
    • jako wskazówki w tagu lub
    • W AdSense – pamiętaj, że ustawienia dostępne w AdSense będą się z czasem zmieniać.

Rodzaj wyświetlanej reklamy zależy od podobnych czynników.

Pamiętaj, że wywołanie funkcji adBreak() może w ogóle nie wyświetlić reklamy. Określa ona tylko miejsce, w którym reklama może się wyświetlać.

Różni się to od tradycyjnych interfejsów API, w których kod zawsze wie, czy reklama jest dostępna, a Ty decydujesz w grze, czy ją wyświetlić. Takie podejście, w którym API umieszczania reklam decyduje, czy reklama ma się wyświetlać w określonym miejscu, jest czasami nazywane „odwróceniem kontroli”.

Powodem, dla którego przenosimy nasz interfejs API gier na ten model, jest przede wszystkim to, że skraca on kod, który musisz napisać w swojej grze. Po drugie, ułatwia to dostarczanie miejsc docelowych zgodnych z zasadami, które zapewniają użytkownikom świetne wrażenia. Dzięki temu możemy udostępniać wydawcom gier niektóre z naszych formatów o najwyższej skuteczności. Poza tym wyraźniej oddziela proces umieszczania reklam w grze od decyzji dotyczących zarabiania, takich jak typ i liczba wyświetlanych reklam.

Chcemy, aby można było zmieniać ustawienia zarabiania i kontrolować wrażenia użytkowników bez konieczności edytowania i publikowania nowej wersji gry. Początkowo będzie to możliwe dzięki określeniu wskazówek w tagu. W przyszłych wersjach będziemy jednak mogli udostępniać ustawienia bezpośrednio w interfejsach AdSense i AdMob.

Reklamy pełnoekranowe

Reklama pełnoekranowa to reklama zajmująca cały ekran, która może wyświetlać się w różnych momentach gry, np. gdy gracz rozpoczyna grę lub po ukończeniu poziomu. Wstrzymuje ona grę i zasłania cały dokument. Gracz może kliknąć reklamę (wtedy wyświetli się ona w innej karcie przeglądarki) lub ją zamknąć, aby kontynuować grę.

Aby umieścić reklamę pełnoekranową, wypełnij te pola w konfiguracji miejsca docelowego:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

Argument type jest wymagany i zalecamy, aby zawsze nadawać nazwy miejscom docelowym. Pozostałe wywołania zwrotne są opcjonalne.

Sekwencja połączeń

Sprawdź sekwencję wywołań w przypadku reklamy pełnoekranowej.

Diagram sekwencji wywołań reklamy pełnoekranowej

Opis

Reklama pełnoekranowa – szczegółowa sekwencja wywołań
Twoja gra H5 Ad Placement API
  Inicjowanie i wstępne ładowanie reklam
Prowadzenie gry  

Dobry moment na wyświetlenie reklamy…

adBreak() →

 
 

Dostępna jest reklama i jest to dobry moment na jej wyświetlenie…

← beforeAd()
Gra wstrzymuje się, wycisza dźwięk i przygotowuje się do wyświetlenia reklamy.

return do interfejsu API →

 
  Interfejs Ad Placement API renderuje reklamę pełnoekranową. Gracz może kliknąć reklamę (która wyświetla się w nowej karcie). Aby kontynuować grę, muszą zamknąć reklamę.
  ← afterAd() jest wywoływana, jeśli reklama została wyświetlona.
Gra zostanie wznowiona, a dźwięk zostanie wyłączony.  
  ← adBreakDone()Funkcja adBreakDone() jest zawsze wywoływana (nawet jeśli reklama nie została wyświetlona).
Gra rejestruje dane analityczne dotyczące tego miejsca docelowego.  

Uwagi

  • adBreak() to funkcja asynchroniczna, która zwraca wartość natychmiast.
  • Jeśli w miejscu docelowym nie ma reklamy do wyświetlenia, żadne wywołania zwrotne nie są wywoływane, czyli nie są wywoływane funkcje beforeAd() ani afterAd().
  • Aby mieć pewność, że gra nie będzie działać podczas wyświetlania reklamy, użyj wywołania zwrotnego beforeAd(), aby wyciszyć dźwięk i wstrzymać grę.
  • beforeAd() jest synchroniczne, interfejs Ad Placement API nie wyświetli reklamy, dopóki nie zwróci wartości.
  • Uruchom ponownie grę i wyłącz wyciszenie dźwięku, gdy otrzymasz afterAd()połączenie.
  • Jeśli jest dostępna, funkcja adBreakDone() jest zawsze wywoływana, nawet jeśli w tym miejscu docelowym nie wyświetlono reklamy.
  • Wywołanie funkcji adBreak(), gdy wyświetla się inna reklama, spowoduje błąd i w konsoli JavaScript pojawi się ostrzeżenie.

Reklamy przed filmem

Reklama przed filmem to reklama pełnoekranowa wyświetlana przed załadowaniem interfejsu gry. To pierwsza rzecz, którą widzi gracz po przejściu do Twojej gry. Ponieważ reklama przed filmem jest wyświetlana na bardzo wczesnym etapie ładowania strony, a gra nie jest jeszcze wyświetlana, zwykłe wywołania wstrzymania i wyciszenia gry nie są wymagane. Zamiast tego używasz wywołania zwrotnego adBreakDone(), aby określić kolejność rozpoczęcia gry i wyświetlenia reklamy, czyli renderowania interfejsu i odtwarzania dźwięku. Przy każdym wczytaniu strony można uruchomić tylko 1 reklamę przed filmem.

Sekwencja połączeń

Wywołanie reklamy przed filmem następuje bardzo wcześnie w procesie wczytywania strony. Ponieważ w tym momencie interfejs gry nie jest jeszcze renderowany, nie należy przekazywać wywołań zwrotnych beforeAd() i afterAd(). Zamiast tego użyj wywołania zwrotnego adBreakDone(), aby rozpocząć grę po wyświetleniu miejsca docelowego. Wywołanie to jest gwarantowane nawet wtedy, gdy nie było reklamy.

Schemat sekwencji wywołań reklamy przed filmem

Wywołanie poniższego kodu na wczesnym etapie logiki gry spowoduje wyświetlenie reklamy przed filmem. Interfejs nie powinien być renderowany przed wywołaniem tego kodu.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Preroll – szczegółowa sekwencja wywołań
Twoja gra H5 Ad Placement API
  Rozpoczyna się inicjowanie interfejsu API i wstępne buforowanie reklam.
Działa, ale nie została jeszcze uruchomiona i nie wyświetla interfejsu.  

adBreak(type:'preroll',…) →

 
 

Interfejs Ad Placement API kończy inicjowanie i ładowanie reklam. Jeśli jest reklama, jest ona wyświetlana. Gracz może kliknąć reklamę (która wyświetla się w nowej karcie). Aby rozpocząć grę, muszą zamknąć to okno.

 

← adBreakDone() jest zawsze wywoływana (nawet jeśli reklama nie została wyświetlona)

Interfejs gry jest renderowany na ekranie i gracz może teraz z niego korzystać. Gra może w razie potrzeby używać obiektu placementInfo przekazanego do funkcji adBreakDone() (np. do rejestrowania dodatkowych danych analitycznych).

  

Uwagi

  • Reklama przed filmem zawsze próbuje wstępnie wczytać reklamy:
    • W przypadku reklam typu preroll wywoływanie funkcji adConfig(preloadAds: ‘on') nie jest wymagane.
  • Podobnie jak w przypadku innych miejsc docelowych reklamy, reklama przed filmem może się wyświetlić lub nie.
  • Parametry beforeAd() i afterAd() nie powinny być przekazywane do reklamy przed filmem.
    • Reklamy przed filmem wyświetlają się przed rozpoczęciem gry, więc nie musisz wstrzymywać ani wyciszać dźwięku gry.
    • Jeśli przekażesz wartość beforeAd() lub afterAd() z reklamą przed filmem, wywołanie zakończy się niepowodzeniem, a w konsoli JavaScriptu zostanie zarejestrowany błąd.
  • Reklama przed filmem automatycznie czeka na zainicjowanie interfejsu Ad Placement API i wstępne wczytanie reklam:
    • Istnieje jednak limit czasu (2 s), który zapobiega nieokreślonemu opóźnianiu wywołania. Dzięki temu funkcja adBreakDone() jest wywoływana w odpowiednim czasie i gra się uruchamia.
    • adBreakDone() jest zawsze wywoływana, nawet jeśli nie ma reklamy.
  • Zalecamy używanie reklamy przed filmem, aby wyświetlać reklamy przed rozpoczęciem gry.
    • Możesz też użyć wywołania zwrotnego onReady() do adConfig() jako mechanizmu sekwencjonowania logiki gry z inicjowaniem interfejsu API i wstępnym wczytywaniem reklam.

Reklamy z nagrodą

Reklama z nagrodą umożliwia nagradzanie graczy elementami dodawanymi w aplikacji, jeśli zdecydują się oni obejrzeć reklamę. Reklamy pełnoekranowe są opcjonalne – gracz widzi reklamę i może ją zamknąć. Reklamy z nagrodą wymagają zgody użytkownika. Gracz sam decyduje, czy i kiedy chce obejrzeć reklamę, aby otrzymać nagrodę.

W przeciwieństwie do reklam pełnoekranowych, które gracz może w każdej chwili zamknąć, aby otrzymać nagrodę, musi on obejrzeć reklamę przez określony czas (który może się różnić w zależności od wyświetlanej kreacji).

Reklamy z nagrodą są opcjonalne dla gracza, dlatego wymagają głębszej integracji z przebiegiem gry. Musisz udostępnić funkcje, które będą wyświetlać w grze prośbę o nagrodę i przyznawać ją graczowi, jeśli obejrzy reklamę.

Nagrody nie mogą mieć wartości poza aplikacją, nie mogą mieć wartości pieniężnej (ani być łatwo wymienialne na pieniądze) i nie mogą podlegać sprzedaży ani wymianie na towary i usługi. Nie należy też zachęcać graczy do klikania reklam. Więcej informacji znajdziesz w projekcie zasad dotyczących reklam pełnoekranowych i reklam z nagrodą.

Nagrody są opcjonalne dla gracza, więc możesz je dodawać w dowolnym miejscu w grze i używać ich w połączeniu z reklamami pełnoekranowymi. Podobnie jak w przypadku reklam pełnoekranowych, te miejsca docelowe to okazje do wyświetlania reklam z nagrodą. Interfejs Ad Placement API wywoła Twój kod tylko wtedy, gdy w danym momencie w grze rzeczywiście będzie można wyświetlić reklamę z nagrodą.

Celem jest umożliwienie Ci jednorazowej integracji gry z interfejsem Ad Placement API, a następnie z czasem, za pomocą elementów sterujących w tagu lub w AdSense, możesz zmieniać dokładny zestaw aktywowanych reklam bez konieczności ponownego kodowania i publikowania gry.

Typ miejsca docelowego z nagrodą to zawsze 'reward' i można używać wszystkich pól w konfiguracji miejsca docelowego.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

Kluczowe nowe funkcje to beforeReward(), czyli wyzwalacz, który sygnalizuje, że należy wyświetlić prośbę o nagrodę, oraz adViewed(), czyli funkcja wywoływana, gdy gracz obejrzy reklamę, dzięki czemu możesz przyznać mu nagrodę.

Miejsce docelowe z nagrodą możesz zdefiniować w ten sposób:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Reklamy z nagrodą zaczynają się od wyświetlenia w grze prośby o obejrzenie reklamy w zamian za nagrodę.

Przykładowy komunikat reklamy: obejrzyj film, aby zdobyć dodatkowe życie

Sekwencja wywołań w przypadku reklamy z nagrodą

Schemat sekwencji połączenia z nagrodą

Opis

Reklama z nagrodą – szczegółowa sekwencja wywołań
Twoja gra H5 Ad Placement API
  Inicjowanie i wstępne buforowanie reklam
Prowadzenie gry  

adBreak(type:'reward', ... ) →

 
 

Dostępna jest reklama, więc rozpocznij umieszczanie reklamy z nagrodą. beforeReward() jest wywoływana synchronicznie – natychmiast po wywołaniu funkcji adBreak().

← beforeReward(showAdFn)

Gra wyświetla prompt z nagrodą. Dzięki temu gracz może otrzymać nagrodę za obejrzenie reklamy. Można oferować więcej niż jeden rodzaj nagrody (np. nowe życie lub złotą monetę).

Gracz może kliknąć prośbę o nagrodę, odrzucić ją lub po prostu zignorować.

Jeśli kliknie on prompt, gra zapisze rodzaj nagrody, o którą poprosił, i wywoła funkcję showAdFn()...

Jeśli jednak użytkownik zamknie lub zignoruje prośbę o przyznanie nagrody, nic się nie stanie, dopóki nie wywołasz ponownie funkcji adBreak() z typem miejsca docelowego nagrody. W tym momencie interfejs Ad Placement API zresetuje i wyczyści stan z tego wywołania. Jeśli aplikacja wywoła showAdFn z poprzedniej przerwy na reklamę, nie będzie to miało żadnego wpływu.

  

showAdFn() →

 
  ← beforeAd()

Gra zostaje wstrzymana, dźwięk jest wyciszony, a gra jest gotowa do wyświetlenia reklamy.

return do interfejsu API →

 
  Interfejs API wyświetla reklamę. Zawiera przycisk zamykania i odliczanie czasu pozostałego do końca reklamy.
JEŚLI odtwarzacz zamknie reklamę...
  ← adDismissed()
Gracz zamknął reklamę, a gra nie przyznała nagrody.  
ELSE odtwarzacz obejrzy reklamę do końca...
  ← adViewed()
Gracz obejrzał reklamę do końca i otrzymał nagrodę. (Zwykle polega to na ustawieniu stanu gry, który jest następnie pobierany po ponownym uruchomieniu gry za pomocą wywołania funkcji afterAd() poniżej).  
Po obejrzeniu lub zamknięciu reklamy...
  ← afterAd() jest wywoływana, jeśli reklama została wyświetlona.
Gra zostanie wznowiona, a dźwięk zostanie wyłączony.  
  ← adBreakDone()Funkcja adBreakDone() jest zawsze wywoływana (nawet jeśli reklama nie została wyświetlona).
Gra rejestruje dane analityczne dotyczące tego miejsca docelowego.  

Uwagi

  • adBreak() to funkcja asynchroniczna, która zwraca wartość natychmiast.
  • Jeśli w przypadku miejsca docelowego nie ma reklamy do wyświetlenia, żadne wywołania zwrotne nie są wywoływane, czyli nie są wywoływane funkcje beforeAd() ani beforeReward().
  • Aby mieć pewność, że gra nie będzie działać podczas wyświetlania reklamy, użyj wywołania zwrotnego beforeAd(), aby wyciszyć dźwięk i wstrzymać grę.
  • beforeAd() jest synchroniczne, interfejs Ad Placement API nie wyświetli reklamy, dopóki nie zwróci wartości.
  • Uruchom ponownie grę i wyłącz wyciszenie dźwięku, gdy otrzymasz afterAd()połączenie.
  • Jeśli jest dostępna, funkcja adBreakDone() jest zawsze wywoływana, nawet jeśli w tym miejscu docelowym nie wyświetlono reklamy.
  • Wywołanie funkcji adBreak(), gdy wyświetla się inna reklama, spowoduje błąd i w konsoli JavaScript pojawi się ostrzeżenie.