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 dostępne przez Ciebie funkcje, które pozwalają wykonać kluczowe kroki 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 widoczne powyżej to jedyne prawidłowe argumenty, które można przekazać do tych funkcji. Różne rodzaje reklam wymagają różnych podzbiorów tych argumentów, jak opisano poniżej.

adBreak() to kluczowa funkcja umożliwiająca wyświetlanie reklam w grze. Definiuje miejsce docelowe reklamy i przyjmuje obiekt o nazwie konfiguracja miejsca docelowego, który zawiera wszystkie elementy niezbędne do wyświetlenia reklamy.

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

  • Typ zadeklarowanego przez Ciebie miejsca docelowego reklamy
    • Czy ta reklama jest na początku gry? Pomiędzy poziomami? Chwila, kiedy gracz wstrzymał grę?
  • czy odpowiednia reklama ma wyświetlać się w przypadku obecnego gracza
    • Czy ta reklama jest dla nich odpowiednia?
    • Czy jest to zgodne z ustawieniami dotyczącymi prywatności i zgody użytkownika?
  • Liczba reklam, które ostatnio oglądał odtwarzacz
  • Ustawienia kontrolne – np. częstotliwość wyświetlania reklam ustawiona w tej grze
    • wskazówką w tagu lub
    • W AdSense – pamiętaj, że w AdSense będą cały czas dostępne opcje kontroli.

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

Pamiętaj, że wywołanie adBreak() może nie spowodować wyświetlenia reklamy. Określa po prostu miejsce, w którym może być wyświetlana reklama.

W przeciwieństwie do standardowych interfejsów API, w których kod zawsze wie, czy reklama jest dostępna, Ty decydujesz, czy chcesz ją wyświetlić. Takie podejście umożliwia interfejsowi Ad Placement API decydowanie, czy reklama jest wyświetlana w określonym miejscu docelowym. Czasami nazywane jest to „odwróceniem kontroli”.

Począwszy od tego, przenosimy nasz interfejs API do gier do tego modelu. Przede wszystkim skracamy kod, który trzeba wpisać w grze. Po drugie ułatwia ona dostarczanie miejsc docelowych zgodnych z zasadami, dbając o wygodę użytkowników. Dzięki temu możemy oferować wydawcom gier niektóre z najskuteczniejszych formatów. Poza tym proces wyraźnie rozdziela proces umieszczania reklam w grze z decyzją dotyczącą typu i liczby wyświetlanych reklam.

Chcemy dać Ci możliwość zmiany ustawień zarabiania i kontrolowania wygody użytkowników bez konieczności edytowania i publikowania nowej wersji gry. Najpierw trzeba wskazać wskazówki w tagu. W przyszłych wersjach będzie można udostępniać ustawienia bezpośrednio w interfejsach AdSense i AdMob.

Reklamy pełnoekranowe

Reklama pełnoekranowa może pojawiać się w różnych momentach w grze, np. po rozpoczęciu gry lub ukończeniu poziomu. Wstrzymuje grę, zasłania cały dokument, a gracz może kliknąć reklamę (w takim przypadku, gdy reklama wyświetla się na innej karcie przeglądarki) lub zamknąć, co pozwoli 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. Zalecamy zawsze nazywanie miejsc docelowych. Inne wywołania zwrotne są opcjonalne.

Sekwencja wywołań

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

Diagram sekwencji wywołania reklamy pełnoekranowej

Opis

Reklama pełnoekranowa – szczegółowa sekwencja połączeń
Twoja gra H5 Interfejs Ad Placement API
  Inicjalizacja i wstępne wczytywanie reklam
Uruchomiono grę  

Dobra okazja na wyświetlenie reklamy...

adBreak() →

 
 

Masz już reklamę, więc to dobry moment, aby ją wyświetlić...

← beforeAd(),
Gra zostanie wstrzymana, wyciszy dźwięk i będzie gotowa do wyświetlenia reklamy.

return do interfejsu API →

 
  Interfejs Ad Placement API renderuje reklamę pełnoekranową. Odtwarzacz może kliknąć reklamę (wyświetla się w nowej karcie). Aby można było kontynuować grę, musi ona zamknąć reklamę.
  Wywołanie ← afterAd() w przypadku wyświetlenia reklamy
Gra wznawia i wycisza dźwięk.  
  ← adBreakDone()adBreakDone() jest zawsze wywoływane (nawet jeśli reklama nie została wyświetlona)
Statystyki z dziennika gry dotyczące tego miejsca docelowego.  

Uwagi

  • adBreak() to funkcja asynchroniczna, która zwraca natychmiastowy efekt.
  • Jeśli w miejscu docelowym nie ma reklamy, która mogłaby się wyświetlić, żadne wywołanie zwrotne nie jest wywoływane, czyli żadne z elementów beforeAd(),afterAd().
  • Aby mieć pewność, że gra nie będzie uruchamiana w trakcie wyświetlania reklamy, użyj wywołania zwrotnego beforeAd(), aby wyciszyć dźwięk i wstrzymać grę.
  • Interfejs beforeAd() jest synchroniczny, dlatego interfejs Ad Placement API nie wyświetla reklam, dopóki nie wróci.
  • Uruchom ponownie grę i wyłącz wyciszenie dźwięku po otrzymaniu wywołania afterAd().
  • Jeśli jest podany, parametr adBreakDone() jest zawsze wywoływany, nawet jeśli reklama nie została wyświetlona w tym miejscu docelowym.
  • Wywołanie adBreak() podczas wyświetlania innej reklamy nie powiedzie się, a w konsoli JavaScript wyświetli się ostrzeżenie.

Reklamy przed filmem

Reklama przed filmem to reklama pełnoekranowa, która pojawia się, zanim gra wczyta interfejs użytkownika. To pierwsza rzecz, jaką zobaczy gracz, gdy przechodzi do Twojej gry. Reklama przed filmem pojawia się na samym początku wczytywania strony, a gra nie jest jeszcze widoczna – typowe wywołania wstrzymania i wyciszenia gry nie są wymagane. Zamiast tego użyj wywołania zwrotnego adBreakDone(), aby zsekwencjonować początek gry z reklamą, czyli wyrenderować interfejs i rozpocząć odtwarzanie dźwięku. Przy każdym wczytaniu strony może być wywoływana tylko jedna reklama przed filmem.

Sekwencja wywołań

Wywołanie reklamy przed filmem następuje dokładnie na początku wczytywania strony. Ponieważ Twoja gra nie wyrenderowała jeszcze swojego interfejsu, nie przesyłaj wywołań zwrotnych beforeAd() i afterAd(). Zamiast tego użyj wywołania zwrotnego adBreakDone(), aby uruchomić grę po miejscu docelowym, ponieważ zostanie to zainicjowane nawet wtedy, gdy nie będzie reklamy.

Schemat sekwencji wywołań reklamy przed filmem

Wywoływanie poniższego kodu na początku logiki gry powoduje umieszczenie 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,
})
Reklama przed filmem – szczegółowa sekwencja połączeń
Twoja gra H5 Interfejs Ad Placement API
  Rozpoczęcie inicjowania i buforowania reklam przez interfejs API
Aplikacja jest uruchomiona, ale nie została uruchomiona i nie wyświetla interfejsu  

adBreak(type:'preroll',…) →

 
 

Interfejs Ad Placement API kończy inicjowanie i wczytywanie reklam. Jeśli jakaś reklama się wyświetli, zostanie wyświetlona. Odtwarzacz może kliknąć reklamę (wyświetli się w nowej karcie). Gra musi zostać zamknięta, aby można było ją rozpocząć.

 

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

Interfejs gry jest renderowany na ekranie i gracz może teraz z niego korzystać. W razie potrzeby gra może użyć obiektu placementInfo przekazanego do adBreakDone() (np. do zarejestrowania dodatkowych statystyk).

  

Uwagi

  • Reklama przed filmem zawsze próbuje wstępnie wczytywać reklamy:
    • W przypadku reklam przed filmem wywołanie adConfig(preloadAds: ‘on') nie jest wymagane.
  • Podobnie jak w przypadku innych miejsc docelowych reklamy, reklama przed filmem może być wyświetlana lub nie.
  • beforeAd() i afterAd() nie należy przekazywać do reklamy przed filmem.
    • Reklamy przed filmem wyświetlają się przed rozpoczęciem gry, więc nie musisz wstrzymywać ani wyciszać dźwięku.
    • Jeśli prześlesz tag beforeAd() lub afterAd() z reklamą przed filmem, wywołanie nie powiedzie się, a w konsoli JavaScript zostanie zapisany błąd.
  • Reklama przed filmem automatycznie czeka na zainicjowanie i wstępne wczytanie reklam przez interfejs Ad Placement API:
    • Występuje jednak limit czasu (2 s), który uniemożliwia nieograniczone czas oczekiwania na wywołanie. Dzięki temu adBreakDone() będzie wywoływany w odpowiednim czasie i po uruchomieniu gry.
    • adBreakDone() jest zawsze wywoływane, nawet gdy nie ma reklamy.
  • Zalecamy umieszczanie reklam 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 użyciem inicjacji interfejsu API i wstępnego wczytywania reklam.

Reklamy z nagrodą

Reklama z nagrodą umożliwia nagradzanie graczy elementami w aplikacji, jeśli zechcą obejrzeć reklamę. Gdy reklamy pełnoekranowe są wyłączane, gracz widzi reklamę i może ją odrzucić. Reklamy z nagrodą są włączone. Gracz decyduje, czy i kiedy chce obejrzeć reklamę, aby otrzymać nagrodę.

W przeciwieństwie do reklam pełnoekranowych, w których odtwarzacz może w dowolnym momencie zamknąć reklamę, aby otrzymać nagrodę, użytkownik musi obejrzeć reklamę przez określony czas (który może różnić się w zależności od wyświetlanej kreacji).

Reklamy z nagrodą są opcjonalne w odtwarzaczu, dlatego wymagają większej integracji z procesem gry. Musisz udostępnić funkcje wyświetlające komunikat przypominający o przyznaniu nagrody w grze i przyznający nagrodę, jeśli użytkownik obejrzy reklamę.

Nagrody nie mogą mieć wartości poza aplikacją, nie mogą też mieć wartości pieniężnej ani łatwej wymiany, nie mogą też być sprzedawane ani wymieniane na towary i usługi. Nie można też zachęcać graczy do klikania reklam. Więcej informacji znajdziesz w wersji roboczej zasad dotyczących reklam pełnoekranowych i reklam z nagrodą.

Nagrody są opcjonalne, więc możesz dodawać je w dowolnym miejscu w grze i używać ich wraz z reklamami pełnoekranowymi. Te miejsca docelowe, podobnie jak reklamy pełnoekranowe, mają możliwości wyświetlania reklam z nagrodą. Interfejs Ad Placement API wywoła Twój kod tylko wtedy, gdy reklama z nagrodą będzie rzeczywista oferowana w danym momencie gry.

Po raz kolejny chodzi nam o to, aby umożliwić integrację gry z interfejsem Ad Placement API. Później za pomocą elementów sterujących w tagu lub w AdSense można zmienić dokładną kombinację reklam, które są aktywowane, bez konieczności ponownego kodowania i ponownego publikowania gry.

Typ miejsca docelowego z nagrodą to zawsze 'reward' i można użyć 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() (wyzwalacz informujący o wyświetleniu prośby o nagrodę) i adViewed() (wywoływane, gdy odtwarzacz wyświetli reklamę), więc możesz przydzielać nagrody.

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 podpowiedzi w grze, które oferują graczowi nagrodę, jeśli obejrzą reklamę.

Przykładowy tekst reklamy: Obejrzyj film, aby zyskać dodatkowe życie

Sekwencja wywołań reklamy z nagrodą

Schemat sekwencji połączeń z nagrodą

Opis

Reklama z nagrodą – szczegółowa sekwencja połączeń
Twoja gra H5 Interfejs Ad Placement API
  Inicjowanie i buforowanie reklam z wyprzedzeniem
Uruchomiono grę  

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

 
 

Masz reklamę, więc zacznij wyświetlać reklamy z nagrodą. Pole beforeReward() jest wywoływane synchronicznie – natychmiast po wywołaniu funkcji adBreak()

← beforeReward(showAdFn),

Gra renderuje pytanie o nagrodę. To daje graczowi szansę na zdobycie nagrody za obejrzenie reklamy. Można oferować różne rodzaje nagród (np. nowe życie czy złote monety).

Gracz może kliknąć potwierdzenie, odrzucić je lub po prostu zignorować.

Jeśli kliknie potwierdzenie, gra zapisze rodzaj nagrody, o którą prosi, i wywoła: showAdFn()...

W przeciwnym razie, jeśli prośba o nagrodę zostanie odrzucona lub zignorowana, nic się nie stanie, dopóki nie wywołasz kolejnego wywołania adBreak() z typem miejsca docelowego nagrody. Wtedy interfejs Ad Placement API zresetuje się i usunie stan ze wywołania. Jeśli aplikacja wywołuje metodę showAdFn z poprzedniej przerwy na reklamę, nie będzie działać.

  

showAdFn() →

 
  ← beforeAd(),

Gra wstrzymuje się, wycisza dźwięk i jest gotowa do wyświetlenia reklamy

return do interfejsu API →

 
  Interfejs API wyświetla reklamę. Zawiera przycisk zamykania i odliczanie czasu do końca reklamy.
Jeśli odtwarzacz zamknie reklamę...
  ← adDismissed(),
Gracz odrzucił reklamę, a gra nie przyznaje nagrody.  
ELSE widz ogląda reklamę do końca...
  ← adViewed(),
Gracz obejrzał reklamę do końca, a gra uzyskała nagrodę. Zwykle wiąże się to z ustawieniem stanu gry, który jest ustawiany podczas ponownego uruchamiania gry na afterAd().  
Po obejrzeniu lub odrzuceniu reklamy...
  ← afterAd() jest wywoływane, gdy reklama została wyświetlona
Gra wznawia i wycisza dźwięk.  
  ← adBreakDone()adBreakDone() jest zawsze wywoływane (nawet jeśli reklama nie została wyświetlona)
Statystyki z dziennika gry dotyczące tego miejsca docelowego.  

Uwagi

  • adBreak() to funkcja asynchroniczna, która zwraca natychmiastowy efekt.
  • Jeśli w miejscu docelowym nie ma reklamy, która zostałaby wyświetlona, żadne wywołanie zwrotne nie ma żadnego wywołania beforeAd() ani beforeReward().
  • Aby mieć pewność, że gra nie będzie uruchamiana w trakcie wyświetlania reklamy, użyj wywołania zwrotnego beforeAd(), aby wyciszyć dźwięk i wstrzymać grę.
  • Interfejs beforeAd() jest synchroniczny, dlatego interfejs Ad Placement API nie wyświetla reklam, dopóki nie wróci.
  • Uruchom ponownie grę i wyłącz wyciszenie dźwięku po otrzymaniu wywołania afterAd().
  • Jeśli jest podany, parametr adBreakDone() jest zawsze wywoływany, nawet jeśli reklama nie została wyświetlona w tym miejscu docelowym.
  • Wywołanie adBreak() podczas wyświetlania innej reklamy nie powiedzie się, a w konsoli JavaScript wyświetli się ostrzeżenie.