Engage SDK Watch: Instrukcje dotyczące integracji technicznej z usługami innych firm

Ważne: pakiet Engage SDK zastąpił Media Home, który został wycofany. Jeśli masz już integrację z Media Home, postępuj zgodnie z instrukcjami w tych przewodnikach, aby przenieść treści do pakietu Engage SDK, co pozwoli na ich publikowanie na większej liczbie urządzeń i w większej liczbie formatów. Jeśli masz pytania, skontaktuj się z [e-mail].

Zwiększ zaangażowanie w aplikację, docierając do użytkowników tam, gdzie się znajdują. Zintegruj pakiet Engage SDK, aby wyświetlać treści do dalszego oglądania i spersonalizowane rekomendacje bezpośrednio użytkownikom na różnych platformach na urządzeniu, takich jak Kolekcje, Entertainment Space i Sklep Play. Integracja zwiększa rozmiar średniego pliku APK (skompresowany) o mniej niż 50 KB i zajmuje deweloperom około tygodnia pracy. Więcej informacji znajdziesz na naszej stronie.

Ten przewodnik zawiera instrukcje dla partnerów deweloperów dotyczące integracji treści wideo za pomocą pakietu Engage SDK w celu wypełnienia zarówno tego nowego obszaru, jak i istniejących platform Google.

Uwaga: zapoznaj się z przewodnikiem po integracji z telewizorem, aby dowiedzieć się więcej o funkcji Oglądaj dalej w Google TV.

Obsługa kategorii i platformy

Kwalifikacja do korzystania z platformy Engage SDK zależy od kategorii treści aplikacji. W tabeli poniżej możesz sprawdzić, czy kwalifikujesz się do wyświetlania produktów na określonych platformach:

Stan	Kategoria treści lub przypadek użycia	Obsługiwane platformy
Obsługiwane (Kwalifikuje się do wyświetlania na wszystkich platformach)	Filmy i telewizja na żądanie Telewizja na żywo / sport Klipy wideo na żądanie Filmy o sporcie Minidramaty podcasty wideo,	Kolekcje Entertainment Space Karta Aplikacje w Sklepie Play Karta Ty w Sklepie Play strona z informacjami o aplikacji w Sklepie Play,
Częściowo obsługiwane (kwalifikuje się do wyświetlania na niektórych platformach)	klipów wideo z aplikacji z wiadomościami;	Kolekcje Entertainment Space
Nieobsługiwane	Piloty Narzędzia do pobierania filmów, odtwarzacze i edytory Recenzje filmów, seriali i programów telewizyjnych Bilety do kina Programy TV Rozmowy wideo i pokoje czatu

Umiejętności związane z Androidem

Wyświetl na GitHubie

Integracja z pakietem Engage SDK

Użyj umiejętności Androida w pakiecie Engage SDK, aby zintegrować i debugować aplikację oraz rozwiązać problemy z implementacją.

Aby zainstalować umiejętność z interfejsu wiersza poleceń Androida, uruchom:

android skills add engage-sdk-integration

Szczegóły integracji

W tej sekcji opisano kroki, modele danych i terminologię wymagane do integracji z pakietem Engage SDK w przypadku treści wideo.

Terminologia

Ta integracja obejmuje 3 typy klastrów: Rekomendacja, Kontynuacja i Polecane.

• Rekomendacje to grupy zawierające spersonalizowane sugestie dotyczące treści do obejrzenia od konkretnego partnera deweloperskiego.

  Rekomendacje mają taką strukturę:

  • Grupa rekomendacji: widok interfejsu zawierający grupę rekomendacji od tego samego partnera deweloperskiego.

    

    Rysunek 1. Interfejs Entertainment Space przedstawiający klaster rekomendacji od jednego partnera.

  • Encja: obiekt reprezentujący pojedynczy element w klastrze. Encją może być film, program telewizyjny, serial telewizyjny, transmisja na żywo itp. Listę obsługiwanych typów encji znajdziesz w sekcji Podawanie danych encji.

    

    Rysunek 2. Interfejs Entertainment Space wyświetlający pojedynczy element w grupie rekomendacji jednego partnera.

• Grupa Kontynuacja zawiera niedokończone filmy i odpowiednie nowo opublikowane odcinki od wielu partnerów deweloperskich w jednym układzie interfejsu. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Kontynuacja. Badania wykazały, że spersonalizowane rekomendacje wraz ze spersonalizowanymi treściami do kontynuowania zapewniają najlepsze zaangażowanie użytkowników.

  

  Rysunek 3. Interfejs Przestrzeni rozrywkowej z grupą Kontynuacja zawierającą niedokończone rekomendacje od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja).

• Grupa Polecane zawiera wybrane elementy od wielu partnerów programistów w jednym układzie interfejsu. Jeden wyróżniony klaster będzie wyświetlany u góry interfejsu w priorytetowym miejscu nad wszystkimi innymi klastrami rekomendacji. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Polecane.

  

  Rysunek 4. Interfejs Centrum rozrywki z grupą Polecane zawierającą rekomendacje od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja).

Przygotowanie

Minimalny poziom interfejsu API: 19

Dodaj bibliotekę com.google.android.engage:engage-core do aplikacji:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.6.0'
}

Więcej informacji znajdziesz w artykule Widoczność pakietów w Androidzie 11.

Podsumowanie

Projekt jest oparty na implementacji powiązanej usługi.

Dane, które klient może opublikować, podlegają tym limitom w przypadku różnych typów klastrów:

Typ klastra	Limity klastra	Maksymalne limity elementów w klastrze
Klastry rekomendacji	Maksymalnie 7	Maksymalnie 50
Klaster kontynuacji	Maksymalnie 1	Maksymalnie 20
Polecana grupa	Maksymalnie 1	Maksymalnie 20

Ważne: pakiet Engage SDK zastąpił Media Home, który został wycofany. Jeśli masz już integrację z Centrum multimediów, wykonaj instrukcje podane w kroku 0, aby przenieść treści do pakietu Engage SDK, co pozwoli na ich publikowanie na większej liczbie urządzeń i w większej liczbie formatów. Skontaktuj się z [e-mail]. Jeśli nie masz integracji z Media Home, przejdź do kroku 1.

Krok 0. Migracja z dotychczasowej integracji z pakietem SDK Media Home

W tej sekcji opisujemy, jak przenieść istniejące modele danych i wywołania interfejsu API pakietu Media Home SDK do pakietu Engage SDK.

Mapowanie modeli danych z istniejącej integracji

Jeśli przechodzisz z dotychczasowej integracji z ekranem głównym multimediów, w tej tabeli znajdziesz informacje o tym, jak mapować modele danych w dotychczasowych pakietach SDK na nowy pakiet Engage SDK:

Odpowiednik integracji MediaHomeVideoContract	Odpowiednik integracji pakietu Engage SDK
com.google.android.mediahome.video.PreviewChannel	com.google.android.engage.common.datamodel.RecommendationCluster
com.google.android.mediahome.video.PreviewChannel.Builder	com.google.android.engage.common.datamodel.RecommendationCluster.Builder
com.google.android.mediahome.video.PreviewChannelHelper	com.google.android.engage.video.service.AppEngageVideoClient
com.google.android.mediahome.video.PreviewProgram	Podzielone na osobne klasy: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder	Podzielone na kreatory w osobnych klasach: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.VideoContract	Nie jest już potrzebny.
com.google.android.mediahome.video.WatchNextProgram	Podzielone na atrybuty w oddzielnych klasach: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder	Podzielone na atrybuty w osobnych klasach: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity

Klastry publikujące w pakiecie Media Home SDK w porównaniu z pakietem Engage SDK

W przypadku pakietu Media Home SDK klastry i elementy były publikowane za pomocą oddzielnych interfejsów API:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

W pakiecie Engage SDK publikowanie klastrów i encji jest połączone w jedno wywołanie interfejsu API. Wszystkie elementy należące do klastra są publikowane razem z nim:

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

Krok 1. Podaj dane podmiotu

Pakiet SDK definiuje różne encje reprezentujące poszczególne typy produktów. W przypadku kategorii Zegarki obsługujemy te elementy:

1. MovieEntity
2. TvShowEntity
3. TvSeasonEntity
4. TvEpisodeEntity
5. LiveStreamingVideoEntity
6. VideoClipEntity

W tabeli poniżej znajdziesz atrybuty i wymagania dotyczące poszczególnych typów.

MovieEntity

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI odtwarzania	Wymagany w przypadku urządzeń mobilnych	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania filmu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikatory URI odtwarzania na danej platformie	Opcjonalne w przypadku urządzeń mobilnych, wymagane w przypadku Google TV	Precyzyjne linki do aplikacji dostawcy na konkretną platformę, które umożliwiają rozpoczęcie odtwarzania filmu.
Identyfikator URI strony z informacjami	Opcjonalny	Precyzyjny link do aplikacji dostawcy, który prowadzi do szczegółowych informacji o filmie. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Data premiery	Opcjonalny	W milisekundach od początku epoki.
Dostępność	Opcjonalny	AVAILABLE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań. FREE_WITH_SUBSCRIPTION: treść jest dostępna po zakupie subskrypcji przez użytkownika. PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika. PURCHASED: treść została kupiona lub wypożyczona przez użytkownika.
Cena oferty	Opcjonalny	Dowolny tekst
Czas trwania	Wymagany	W milisekundach.
gatunek;	Opcjonalny	Dowolny tekst
Oceny treści	Opcjonalny	Dowolny tekst, zgodny ze standardem branżowym. (przykład)
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze Kontynuacja, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

TvShowEntity

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI strony z informacjami	Wymagany	Precyzyjny link do aplikacji dostawcy, który prowadzi do szczegółowych informacji o programie telewizyjnym. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikator URI odtwarzania	Opcjonalny	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania programu telewizyjnego. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikatory URI odtwarzania na danej platformie	Opcjonalne w przypadku urządzeń mobilnych, wymagane w przypadku Google TV	Precyzyjne linki do aplikacji dostawcy na konkretną platformę, które umożliwiają rozpoczęcie odtwarzania programu telewizyjnego.
Data emisji pierwszego odcinka	Opcjonalny	W milisekundach od początku epoki.
Data emisji najnowszego odcinka	Opcjonalny	W milisekundach od początku epoki.
Dostępność	Opcjonalny	AVAILABLE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań. FREE_WITH_SUBSCRIPTION: treść jest dostępna po zakupie subskrypcji przez użytkownika. PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika. PURCHASED: treść została kupiona lub wypożyczona przez użytkownika.
Cena oferty	Opcjonalny	Dowolny tekst
Liczba sezonów	Opcjonalny	Dodatnia liczba całkowita
gatunek;	Opcjonalny	Dowolny tekst
Oceny treści	Opcjonalny	Dowolny tekst, zgodny ze standardem branżowym. (przykład)
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze Kontynuacja, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

TvSeasonEntity

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI strony z informacjami	Wymagany	Precyzyjny link do aplikacji dostawcy, który prowadzi do szczegółowych informacji o sezonie serialu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikator URI odtwarzania	Opcjonalny	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania sezonu serialu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Wyświetl numer sezonu	Opcjonalny Dostępne w wersji 1.3.1	Ciąg znaków
Data emisji pierwszego odcinka	Opcjonalny	W milisekundach od początku epoki.
Data emisji najnowszego odcinka	Opcjonalny	W milisekundach od początku epoki.
Dostępność	Opcjonalny	AVAILABLE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań. FREE_WITH_SUBSCRIPTION: treść jest dostępna po zakupie subskrypcji przez użytkownika. PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika. PURCHASED: treść została kupiona lub wypożyczona przez użytkownika.
Cena oferty	Opcjonalny	Dowolny tekst
Liczba odcinków	Opcjonalny	Dodatnia liczba całkowita
gatunek;	Opcjonalny	Dowolny tekst
Oceny treści	Opcjonalny	Dowolny tekst, zgodny ze standardem branżowym. (przykład)
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze Kontynuacja, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

TvEpisodeEntity

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI odtwarzania	Wymagany w przypadku urządzeń mobilnych	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania odcinka. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikatory URI odtwarzania na danej platformie	Opcjonalne w przypadku urządzeń mobilnych, wymagane w przypadku Google TV	Precyzyjne linki do aplikacji dostawcy na konkretną platformę, które umożliwiają rozpoczęcie odtwarzania odcinka.
Identyfikator URI strony z informacjami	Opcjonalny	Precyzyjny link do aplikacji dostawcy, który umożliwia wyświetlanie szczegółowych informacji o odcinku programu telewizyjnego. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Pokaż tytuł	Opcjonalne w przypadku urządzeń mobilnych; wymagane w przypadku funkcji Oglądaj dalej w Google TV	Tytuł programu telewizyjnego, z którego pochodzi odcinek.
Numer sezonu	Opcjonalne w przypadku urządzeń mobilnych; wymagane w przypadku funkcji Oglądaj dalej w Google TV	Ciąg znaków
Wyświetl numer odcinka	Opcjonalne w przypadku urządzeń mobilnych; wymagane w przypadku funkcji Oglądaj dalej w Google TV Dostępne w wersji 1.3.1	Ciąg znaków
Data emisji	Opcjonalny	W milisekundach od początku epoki.
Dostępność	Opcjonalny	AVAILABLE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań. FREE_WITH_SUBSCRIPTION: treść jest dostępna po zakupie subskrypcji przez użytkownika. PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika. PURCHASED: treść została kupiona lub wypożyczona przez użytkownika.
Cena oferty	Opcjonalny	Dowolny tekst
Czas trwania	Wymagany	Musi być wartością dodatnią w milisekundach.
gatunek;	Opcjonalny	Dowolny tekst
Oceny treści	Opcjonalny	Dowolny tekst, zgodny ze standardem branżowym. (przykład)
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze Kontynuacja, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

LiveStreamingVideoEntity

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI odtwarzania	Wymagany w przypadku urządzeń mobilnych	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania filmu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikatory URI odtwarzania na danej platformie	Opcjonalne w przypadku urządzeń mobilnych, wymagane w przypadku Google TV	Precyzyjne linki do aplikacji dostawcy na konkretną platformę, które umożliwiają rozpoczęcie odtwarzania filmu.
Prezenterzy	Opcjonalny	Dowolny tekst
Czas rozpoczęcia	Opcjonalny	W milisekundach od początku epoki.
Czas zakończenia	Opcjonalny	W milisekundach od początku epoki.
Liczba wyświetleń	Opcjonalny	Dowolny tekst, musi być zlokalizowany.
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze Kontynuacja, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

VideoClipEntity

Obiekt VideoClipEntity reprezentuje element wideo pochodzący z mediów społecznościowych, takich jak TikTok czy YouTube.

Atrybut	Wymaganie	Uwagi
Nazwa	Wymagany
Obrazy plakatu	Wymagany	Wymagany jest co najmniej 1 obraz, który musi mieć określony format. (Preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów zarówno w orientacji pionowej, jak i poziomej, aby uwzględnić różne scenariusze). Wskazówki znajdziesz w specyfikacji obrazu.
Identyfikator URI odtwarzania	Wymagany w przypadku urządzeń mobilnych	Precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania filmu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.
Identyfikatory URI odtwarzania na danej platformie	Opcjonalne w przypadku urządzeń mobilnych, wymagane w przypadku Google TV	Precyzyjne linki do aplikacji dostawcy na konkretną platformę, które umożliwiają rozpoczęcie odtwarzania filmu.
Czas utworzenia	Opcjonalny	W milisekundach od początku epoki.
Czas trwania	Wymagany	Musi być wartością dodatnią w milisekundach.
Twórca	Opcjonalny	Dowolny tekst
Obraz twórcy	Opcjonalny	Obraz awatara twórcy
Liczba wyświetleń	Opcjonalny	Dowolny tekst, musi być zlokalizowany.
Tekst wezwania do działania	Opcjonalny	Dowolny tekst, który będzie wyświetlany jako wezwanie do działania.
Tagi	Opcjonalny	Lista tagów powiązanych z encją.
Typ „Warte obejrzenia”	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. Musi to być jeden z tych 4 typów: CONTINUE: użytkownik obejrzał już ponad minutę tych treści. NEW: użytkownik obejrzał wszystkie dostępne odcinki treści, ale pojawił się nowy odcinek i jest dokładnie 1 nieobejrzany odcinek. Dotyczy to treści podzielonych na odcinki, takich jak seriale czy nagrane mecze piłki nożnej. NEXT: użytkownik obejrzał co najmniej 1 cały odcinek treści, ale pozostał jeszcze więcej niż 1 odcinek lub dokładnie 1 odcinek, który nie jest oznaczony jako „NEW” i został opublikowany, zanim użytkownik zaczął oglądać treści. LISTA DO OBEJRZENIA: użytkownik wyraźnie zdecydował się dodać film, wydarzenie lub serial do listy do obejrzenia, aby ręcznie wybrać, co chce obejrzeć w następnej kolejności.
Czas ostatniego zaangażowania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania	Wymagane warunkowo	Należy podać, gdy element znajduje się w klastrze kontynuacji, a WatchNextType to CONTINUE. W milisekundach od początku epoki.

Specyfikacja obrazu

W tej sekcji znajdziesz wymagane specyfikacje komponentów z obrazem:

Formaty plików

PNG, JPG, statyczny GIF, WebP

Maksymalny rozmiar pliku

5120 KB

Dodatkowe zalecenia

• Zawsze widoczny obszar obrazu: ważne treści umieść w środkowych 80% obrazu.

Przykład

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .setCallToActionText("Watch Now")
    .addTag("Action")
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .setCallToActionText("Watch Now")
                  .addTag("Action")
                  .build();

Krok 2. Podaj dane klastra

Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i było zaplanowane regularnie lub na podstawie zdarzenia (np. za każdym razem, gdy użytkownik otwiera aplikację lub gdy właśnie dodał coś do koszyka).

AppEngagePublishClient odpowiada za klastry publikujące. W kliencie dostępne są te interfejsy API:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

Ten interfejs API służy do sprawdzania, czy usługa jest dostępna do integracji i czy treści mogą być wyświetlane na urządzeniu.

Pakiet Engage SDK w wersji 1.6.0 lub nowszej (zalecany)

Umiejętności związane z Androidem

Wyświetl na GitHubie

Integracja z pakietem Engage SDK

Aby zainstalować umiejętność z interfejsu wiersza poleceń Androida, uruchom:

android skills add engage-sdk-integration

Jeśli Twój zespół korzysta z narzędzi do kodowania opartych na AI (takich jak Gemini w Android Studio), możesz zautomatyzować tę migrację, prosząc asystenta AI o pomoc:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

Możesz sprawdzić dostępność usługi dla każdego typu klastra, który chcesz opublikować. Interfejs API isServiceAvailable akceptuje obiekt żądania ServiceAvailabilityRequest, który zawiera typy klastrów, dla których należy sprawdzić dostępność usługi. Wartości typu wyliczeniowego ClusterType wymagane w przypadku ServiceAvailabilityRequest znajdziesz w tabeli poniżej.

Typ klastra	Stała typu klastra	Wartość w formie liczby całkowitej
Nieznany	TYPE_UNKNOWN	0
Klaster rekomendacji	TYPE_RECOMMENDATION	1
Polecana grupa	TYPE_FEATURED	2
Klaster kontynuacji	TYPE_CONTINUATION	3
Klaster zarządzania użytkownikami	TYPE_ENGAGEMENT	8
Klaster subskrypcji	TYPE_SUBSCRIPTION	12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

Funkcja warunkowej dostępności usługi

Niektóre zintegrowane aplikacje wymagają specjalnej konfiguracji, która okresowo włącza i wyłącza usługę Engage, aby obniżyć koszty wyświetlania. Jednak ta strategia przerywanego przetwarzania treści negatywnie wpływa na wrażenia użytkowników: nieaktualne treści nie będą wyświetlane, a niektóre platformy nie będą obsługiwane.

Od wersji 1.6.0 pakiet Engage SDK umożliwia sprawdzanie dostępności określonych typów klastrów. Jeśli aplikacja korzysta z przetwarzania przerywanego:

• Klastry kontynuacji (takie jak Oglądaj dalej) pozostają domyślnie włączone na wszystkich obsługiwanych urządzeniach.
• Inne typy klastrów (np. rekomendacje) są włączane i wyłączane okresowo.

Jeśli ta domyślna konfiguracja nie odpowiada Twoim potrzebom, skontaktuj się z nami pod adresem [e-mail].

Wersje pakietu SDK starsze niż 1.6.0 (wycofane)

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

Uwaga: zdecydowanie zalecamy okresowe uruchamianie zadania, aby sprawdzić, czy usługa stanie się dostępna w późniejszym czasie. Dostępność usługi może się zmieniać wraz z aktualizacjami wersji Androida, aktualizacjami aplikacji, instalacjami i odinstalowaniami. Dzięki okresowemu sprawdzaniu zadań w określonych odstępach czasu dane mogą być publikowane, gdy tylko usługa stanie się dostępna.

publishRecommendationClusters

Ten interfejs API służy do publikowania listy obiektów RecommendationCluster.

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie.

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

Gdy usługa otrzyma żądanie, w ramach jednej transakcji zostaną wykonane te działania:

• Dotychczasowe dane RecommendationCluster od partnera dewelopera zostaną usunięte.
• Dane z żądania są analizowane i zapisywane w zaktualizowanym klastrze rekomendacji.

W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

publishFeaturedCluster

Ten interfejs API służy do publikowania listy obiektów FeaturedCluster.

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie.

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

Gdy usługa otrzyma żądanie, w ramach jednej transakcji zostaną wykonane te działania:

• Dotychczasowe dane FeaturedCluster od partnera dewelopera zostaną usunięte.
• Dane z żądania są analizowane i zapisywane w zaktualizowanym klastrze polecanych.

W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

publishContinuationCluster

Ten interfejs API służy do publikowania obiektu ContinuationCluster.

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie.

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

Gdy usługa otrzyma żądanie, w ramach jednej transakcji zostaną wykonane te działania:

• Dotychczasowe dane ContinuationCluster od partnera dewelopera zostaną usunięte.
• Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze kontynuacji.

W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Działanie logowania kieruje użytkowników na stronę logowania aplikacji, dzięki czemu aplikacja może publikować treści (lub udostępniać bardziej spersonalizowane treści).

Karta logowania zawiera te metadane:

Atrybut	Wymaganie	Opis
Identyfikator URI działania	Wymagane	Precyzyjny link do działania (np. przekierowuje na stronę logowania w aplikacji)
Obraz	Opcjonalny – jeśli nie zostanie podany, należy podać tytuł	Obraz wyświetlany na karcie obrazy o formacie obrazu 16:9 i rozdzielczości 1264 x 712,
Tytuł	Opcjonalny – jeśli nie zostanie podany, należy podać obraz	Tytuł na karcie
Tekst z opcją działania	Opcjonalny	Tekst wyświetlany w wezwaniu do działania (np. Zaloguj się)
Podtytuł	Opcjonalny	Opcjonalne napisy na karcie

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie.

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Gdy usługa otrzyma żądanie, w ramach jednej transakcji zostaną wykonane te działania:

• Istniejące dane UserAccountManagementCluster od partnera dewelopera zostaną usunięte.
• Dane z żądania są analizowane i zapisywane w zaktualizowanym klastrze UserAccountManagementCluster.

W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

updatePublishStatus

Jeśli z jakiegoś powodu żaden z klastrów nie zostanie opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu API updatePublishStatus. To ważne, ponieważ :

• Podawanie stanu we wszystkich scenariuszach, nawet gdy treść jest opublikowana (STATUS == PUBLISHED), ma kluczowe znaczenie dla wypełniania paneli, które używają tego stanu do przekazywania informacji o stanie i innych danych dotyczących integracji.
• Jeśli nie opublikowano żadnych treści, ale stan integracji nie jest uszkodzony (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów w panelach stanu aplikacji. Potwierdza, że treści nie są publikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
• Pomaga deweloperom dostarczać informacje o tym, kiedy dane są publikowane, a kiedy nie.
• Google może używać kodów stanu, aby zachęcić użytkownika do wykonania określonych działań w aplikacji, dzięki czemu będzie on mógł zobaczyć jej zawartość lub rozwiązać problem.

Lista kwalifikujących się kodów stanu publikacji :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Jeśli treści nie są publikowane, ponieważ użytkownik nie jest zalogowany, Google zaleca opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_PUBLISHED_REQUIRES_SIGN_IN.

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationsClusters

Ten interfejs API służy do usuwania treści klastrów rekomendacji.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

Uwaga: ten interfejs API jest dostępny od wersji 1.1.0.

deleteFeaturedCluster

Ten interfejs API służy do usuwania zawartości klastra polecanych.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treści, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra polecanych. W przypadku błędu całe żądanie zostanie odrzucone i zostanie zachowany dotychczasowy stan.

Uwaga: ten interfejs API jest dostępny od wersji 1.1.0.

deleteContinuationCluster

Ten interfejs API służy do usuwania zawartości klastra kontynuacji.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treści, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra kontynuacji. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

Uwaga: ten interfejs API jest dostępny od wersji 1.1.0.

deleteUserManagementCluster

Ten interfejs API służy do usuwania zawartości klastra UserAccountManagement.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treści, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra UserAccountManagement. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

Uwaga: ten interfejs API jest dostępny od wersji 1.1.0.

deleteClusters

Ten interfejs API służy do usuwania zawartości danego typu klastra.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

Gdy usługa otrzyma żądanie, usunie istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienci mogą przekazywać jeden lub wiele typów klastrów. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

Obsługa błędów

Zdecydowanie zalecamy nasłuchiwanie wyniku zadania z interfejsów API publikowania, aby można było podjąć działania następcze w celu odzyskania i ponownego przesłania zadania, które zakończyło się powodzeniem.

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Błąd jest zwracany jako AppEngageException, a jego przyczyna jest podana jako kod błędu.

Kod błędu	Nazwa błędu	Uwaga
1	SERVICE_NOT_FOUND	Usługa jest niedostępna na danym urządzeniu.
2	SERVICE_NOT_AVAILABLE	Usługa jest dostępna na danym urządzeniu, ale nie jest dostępna w momencie wywołania (np. jest wyraźnie wyłączona).
3	SERVICE_CALL_EXECUTION_FAILURE	Nie udało się wykonać zadania z powodu problemów z wątkami. W takim przypadku można spróbować ponownie.
4	SERVICE_CALL_PERMISSION_DENIED	Wywołujący nie ma uprawnień do wywołania usługi.
5	SERVICE_CALL_INVALID_ARGUMENT	Żądanie zawiera nieprawidłowe dane (np. więcej klastrów niż dozwolona liczba).
6	SERVICE_CALL_INTERNAL	Wystąpił błąd po stronie usługi.
7	SERVICE_CALL_RESOURCE_EXHAUSTED	Wywołanie usługi jest wykonywane zbyt często.

Krok 3. Obsługa intencji rozgłaszania

Oprócz wywoływania interfejsu API do publikowania treści za pomocą zadania musisz też skonfigurować BroadcastReceiver, aby otrzymywać żądania publikowania treści.

Celem intencji rozgłaszania jest głównie reaktywacja aplikacji i wymuszenie synchronizacji danych. Intencje rozgłaszania nie są przeznaczone do częstego wysyłania. Jest wywoływana tylko wtedy, gdy usługa Engage określi, że treści mogą być nieaktualne (np. mają tydzień). Dzięki temu użytkownik może mieć pewność, że zobaczy aktualne treści, nawet jeśli aplikacja nie była uruchamiana przez dłuższy czas.

BroadcastReceiver należy skonfigurować na 2 sposoby:

• Zarejestruj dynamicznie instancję klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacjami, które nadal działają w pamięci.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents. ACTION_PUBLISH_RECOMMENDATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

• Zadeklaruj statycznie implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać intencje transmisji, gdy nie jest uruchomiona, a także publikować treści.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Usługa wysyła te intencje:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Po otrzymaniu tej intencji zalecamy rozpoczęcie połączenia publishRecommendationClusters.
• com.google.android.engage.action.PUBLISH_FEATURED Po otrzymaniu tej intencji zalecamy rozpoczęcie połączenia publishFeaturedCluster.
• com.google.android.engage.action.PUBLISH_CONTINUATION Zalecamy rozpoczęcie połączenia publishContinuationCluster po otrzymaniu tej intencji.

Przepływ pracy integracji

Szczegółowe instrukcje dotyczące weryfikacji integracji po jej zakończeniu znajdziesz w artykule Proces integracji dla deweloperów Engage.

Najczęstsze pytania

Najczęstsze pytania znajdziesz w artykule Najczęstsze pytania dotyczące pakietu Engage SDK.

Kontakt

Jeśli podczas procesu integracji pojawią się pytania, skontaktuj się z [e-mail].

Dalsze kroki

Po zakończeniu integracji wykonaj te czynności:

• Wyślij e-maila na adres [e-mail] i załącz zintegrowany plik APK, który jest gotowy do przetestowania przez Google.
• Google przeprowadza weryfikację i sprawdza wewnętrznie, czy integracja działa zgodnie z oczekiwaniami. Jeśli konieczne będą zmiany, Google skontaktuje się z Tobą i poda niezbędne informacje.
• Jeśli testy zakończą się pomyślnie i nie będą potrzebne żadne zmiany, Google skontaktuje się z Tobą, aby poinformować, że możesz zacząć publikować zaktualizowany i zintegrowany pakiet APK w Sklepie Play.
• Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, klastry Polecane, Wyróżnione i Kontynuacja mogą zostać opublikowane i stać się widoczne dla użytkowników.