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

Google tworzy platformę na urządzeniu, która porządkuje aplikacje użytkowników według branż i zapewnia nowe, immersyjne środowisko do przeglądania i odkrywania treści z aplikacji. Tryb pełnoekranowy daje partnerom deweloperom możliwość zaprezentowania swoich najlepszych treści w ramach dedykowanego kanału poza aplikacją.

Ten przewodnik zawiera instrukcje dla partnerów deweloperów dotyczące integracji treści wideo za pomocą pakietu Engage SDK w celu wypełniania nowej powierzchni reklamowej i dotychczasowych powierzchni Google.

Szczegóły integracji

Terminologia

Ta integracja obejmuje 3 typy klasterów: Recommendation (Rekomendacja), Continuation (Kontynuacja) i Featured (Polecane).

  • Gromadzenie rekomendacji wyświetla spersonalizowane sugestie dotyczące treści do obejrzenia od konkretnego partnera deweloperskiego.

    Rekomendacje mają następującą strukturę:

    • Klaster rekomendacji: widok interfejsu, który zawiera grupę rekomendacji od tego samego partnera dewelopera.

      Rysunek 1. Interfejs Entertainment Space pokazujący grupę rekomendacji od jednego partnera.

    • Jednostka: obiekt reprezentujący pojedynczy element w klastrze. Elementem może być film, program telewizyjny, serial telewizyjny, transmisja na żywo itd. Listę obsługiwanych typów encji znajdziesz w sekcji Przygotowanie danych o elementach.

      Rysunek 2. Interfejs Entertainment Space pokazujący pojedynczy element w ramach klastra rekomendacji jednego partnera.

  • Klaster Kontynuacja zawiera nieukończone filmy i odpowiednie nowo opublikowane odcinki od wielu partnerów deweloperów w ramach jednej grupy interfejsu. Każdy partner programistów będzie mógł transmitować maksymalnie 10 podmiotów w klastrze kontynuacji. Badania wykazały, że spersonalizowane rekomendacje wraz z spersonalizowanymi treściami kontynuacji zapewniają najlepsze zaangażowanie użytkowników.

    Rysunek 3. Interfejs Pokoju z rozrywką przedstawiający klaster kontynuacji z nieukończonymi rekomendacjami od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja).

  • Klaster Polecane zawiera zbiór elementów od wielu partnerów programistów w jednym układzie interfejsu. Będzie jeden wyróżniony klaster, który będzie wyświetlany u góry interfejsu w priorytetowym miejscu nad wszystkimi innymi klastrami rekomendacji. Każdy partner programistów będzie mógł transmitować do 10 elementów w klastrze Polecany.

    Rysunek 4. Interfejs Entertainment Space: klaster Polecane z rekomendacjami od wielu partnerów (obecnie widoczna jest tylko 1 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.5.2'
}

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

Podsumowanie

Projekt jest oparty na implementacji usługi z ograniczeniami.

Dane, które klient może publikować, podlegają następującym ograniczeniom w przypadku różnych typów klastrów:

Typ klastra Limity klastra Maksymalne limity elementów w klastrze
Klastry rekomendacji Maksymalnie 5 Maksymalnie 50
Klaster kontynuacji Maksymalnie 1 Maksymalnie 10
Polecany klaster Maksymalnie 1 Maksymalnie 10

Krok 0. Migracja z dotychczasowej integracji pakietu SDK Media Home

Mapowanie modeli danych z dotychczasowej integracji

Jeśli migrujesz z obecnej integracji z Media Home, w tej tabeli znajdziesz informacje o mapowaniu modeli danych w dotychczasowych pakietach SDK na nowy pakiet SDK Engage:

odpowiednik integracji MediaHomeVideoContract odpowiednik integracji z pakietem SDK Engage,
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 Podzielono na osobne klasy: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder Dzielone na konstruktory 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 Dzielone na atrybuty w osobnych klasach:EventVideoEntity, LiveStreamingVideoEntity,MovieEntity, TvEpisodeEntity,TvSeasonEntity, TvShowEntity,VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder Dzielone na atrybuty w osobnych klasach:EventVideoEntity, LiveStreamingVideoEntity,MovieEntity, TvEpisodeEntity,TvSeasonEntity, TvShowEntity,VideoClipEntity

Grupy publikacji w pakiecie Media Home SDK i Engage SDK

W pakiecie 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 łączone w jedno wywołanie interfejsu API. Wszystkie elementy należące do klastra są publikowane razem z tym klastrem:

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 o podmiocie

Pakiet SDK definiuje różne elementy, które reprezentują poszczególne typy elementów. W przypadku kategorii „Oglądanie” 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 Wymagane jest co najmniej 1 obraz, który musi mieć określony format. (preferowany jest poziomo, ale w przypadku różnych scenariuszy zalecamy przesłanie zarówno obrazów pionowych, jak i poziomych).

Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI odtwarzania Wymagany

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

Identyfikator URI strony z informacjami Opcjonalnie

Precyzyjny link do aplikacji dostawcy, który zawiera informacje o filmie.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Data premiery Wymagany W milisekundach epoki.
Dostępność Wymagany

DOSTĘPNE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań.

FREE_WITH_SUBSCRIPTION: treści są dostępne po zakupie subskrypcji przez użytkownika.

PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika.

KUPIONE: treści zostały kupione lub wypożyczone przez użytkownika.
Cena oferty Opcjonalnie Tekst otwarty
Czas działania Wymagany W milisekundach.
Gatunek Wymagany Dowolny tekst
Oceny treści Wymagany Tekst dowolny, zgodny ze standardami branżowymi. (przykład)
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Musi być podany, gdy element znajduje się w klastrze kontynuacji, a WatchNextType ma wartość CONTINUE. W milisekundach od początku epoki.

TvShowEntity

Atrybut Wymaganie Uwagi
Nazwa Wymagany
obrazy plakatu, Wymagany Wymagany jest co najmniej 1 obraz o określonym współczynniku proporcji. (preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów w orientacji poziomej i pionowej na potrzeby różnych scenariuszy).

Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI strony z informacjami Wymagany

Precyzyjny link do aplikacji dostawcy, który umożliwia wyświetlenie szczegółów serialu telewizyjnego.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI odtwarzania Opcjonalnie

Precyzyjny link do aplikacji dostawcy, aby rozpocząć odtwarzanie programu telewizyjnego.

Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Data emisji pierwszego odcinka Wymagany W milisekundach epoki.
Data emisji ostatniego odcinka Opcjonalnie W milisekundach od początku epoki.
Dostępność Wymagany

DOSTĘPNE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań.

FREE_WITH_SUBSCRIPTION: treści są dostępne po zakupie subskrypcji przez użytkownika.

PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika.

KUPIONE: treści zostały kupione lub wypożyczone przez użytkownika.
Cena oferty Opcjonalnie Tekst otwarty
Liczba sezonów Wymagany Dodatnia liczba całkowita
Gatunek Wymagany Dowolny tekst
Oceny treści Wymagany Tekst dowolny, zgodny ze standardami branżowymi. (przykład)
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Musi być podany, gdy element znajduje się w klastrze kontynuacji, a WatchNextType ma wartość CONTINUE. W milisekundach od początku epoki.

TvSeasonEntity

Atrybut Wymaganie Uwagi
Nazwa Wymagany
obrazy plakatu, Wymagany Wymagane jest co najmniej 1 obraz, który musi mieć określony format. (preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów w orientacji poziomej i pionowej na potrzeby różnych scenariuszy).

Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI strony z informacjami Wymagany

Precyzyjny link do aplikacji dostawcy, który pozwala zobaczyć szczegóły sezonu programu telewizyjnego.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI odtwarzania Opcjonalnie

precyzyjny link do aplikacji dostawcy, który umożliwia rozpoczęcie odtwarzania sezonu serialu telewizyjnego;

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Wyświetlany numer sezonu

Opcjonalnie

Dostępne w wersji 1.3.1

 Ciąg znaków
Data emisji pierwszego odcinka Wymagany W milisekundach epoki.
Data emisji ostatniego odcinka Opcjonalnie W milisekundach od początku epoki.
Dostępność Wymagany

DOSTĘPNE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań.

FREE_WITH_SUBSCRIPTION: treści są dostępne po zakupie subskrypcji przez użytkownika.

PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika.

KUPIONE: treści zostały kupione lub wypożyczone przez użytkownika.
Cena oferty Opcjonalnie Dowolny tekst
Liczba odcinków Wymagany Dodatnia liczba całkowita
Gatunek Wymagany Dowolny tekst
Oceny treści Wymagany Dowolny tekst zgodny ze standardem branżowym. (Przykład).
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Musi być podany, gdy element znajduje się w klastrze kontynuacji, a WatchNextType ma wartość CONTINUE. W milisekundach od początku epoki.

TvEpisodeEntity

Atrybut Wymaganie Uwagi
Nazwa Wymagany
obrazy plakatu, Wymagany Wymagane jest co najmniej 1 obraz, który musi mieć określony format. (preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów w orientacji poziomej i pionowej na potrzeby różnych scenariuszy).

Wskazówki znajdziesz w specyfikacjach obrazów.
Identyfikator URI odtwarzania Wymagany

precyzyjny link do aplikacji dostawcy, który umożliwia odtworzenie odcinka;

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI strony z informacjami Opcjonalnie

Precyzyjny link do aplikacji dostawcy, który umożliwia wyświetlenie szczegółów dotyczących odcinka serialu.

Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Wyświetlanie numeru odcinka

Opcjonalnie

Dostępne w wersji 1.3.1

 Ciąg znaków
Data emisji Wymagany W milisekundach epoki.
Dostępność Wymagany

DOSTĘPNE: treści są dostępne dla użytkownika bez konieczności podejmowania dalszych działań.

FREE_WITH_SUBSCRIPTION: treści są dostępne po zakupie subskrypcji przez użytkownika.

PAID_CONTENT: treści wymagają zakupu lub wypożyczenia przez użytkownika.

KUPIONE: treści zostały kupione lub wypożyczone przez użytkownika.
Cena oferty Opcjonalnie Tekst otwarty
Czas działania Wymagany Musi być dodatnią liczbą w milisekundach.
Gatunek Wymagany Dowolny tekst
Oceny treści Wymagany Tekst dowolny, zgodny ze standardami branżowymi. (przykład)
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Musi być podany, gdy element znajduje się w klastrze kontynuacji, a WatchNextType ma wartość CONTINUE. W milisekundach od początku epoki.

LiveStreamingVideoEntity

Atrybut Wymaganie Uwagi
Nazwa Wymagany
obrazy plakatu, Wymagany Wymagane jest co najmniej 1 obraz, który musi mieć określony format. (preferowana jest orientacja pozioma, ale zalecamy przekazywanie obrazów w orientacji poziomej i pionowej na potrzeby różnych scenariuszy).

Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI odtwarzania Wymagany

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

Prezenterzy Wymagany Tekst otwarty
Godzina rozpoczęcia Opcjonalnie W milisekundach od początku epoki.
Godzina zakończenia Opcjonalnie W milisekundach od początku epoki.
Liczba wyświetleń Opcjonalnie Wolny tekst, który musi zostać przetłumaczony.
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Ten atrybut musi być podany, gdy element znajduje się w klastrze kontynuacji, a typ WatchNextType ma wartość DALEJ. 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 o określonym współczynniku proporcji. (preferowany jest poziomo, ale w przypadku różnych scenariuszy zalecamy przesłanie zarówno obrazów pionowych, jak i poziomych).

Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI odtwarzania Wymagany

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

datę utworzenia; Wymagany W milisekundach od początku epoki.
Czas działania Wymagany Musi być dodatnią liczbą w milisekundach.
Twórca Wymagany Dowolny tekst
Zdjęcie twórcy Opcjonalnie Obraz awatara twórcy
Liczba wyświetleń Opcjonalnie Wolny tekst, który musi zostać przetłumaczony.
Typ „Obejrzyj następny” Wymagane warunkowo

Ten atrybut musi być podany, jeśli element znajduje się w klastrze kontynuacji i musi być jednym z tych 4 typów:

CDN: użytkownik obejrzał już ponad minutę tych treści.

NOWOŚĆ: użytkownik obejrzał wszystkie dostępne odcinki serialu, ale pojawił się nowy odcinek i jest dokładnie jeden niezaoglądany odcinek. Ta opcja działa w przypadku programów telewizyjnych, nagranych meczów piłki nożnej w ramach serii itp.

NASTĘPNY: użytkownik obejrzał co najmniej 1 pełny odcinek serialu, ale zostało jeszcze więcej odcinków lub dokładnie 1 odcinek, który nie jest oznaczony jako „NOWY” i został wydany przed rozpoczęciem przez użytkownika oglądania serialu.

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ć.
Czas ostatniego zaangażowania Wymagane warunkowo Musi być podany, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki.
Czas ostatniej pozycji odtwarzania Wymagane warunkowo Musi być podany, gdy element znajduje się w klastrze kontynuacji, a WatchNextType ma wartość 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 rekomendacje

  • Bezpieczny 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)
    .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)
                  .build();

Krok 2. Podaj dane klastra

Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i zaplanowane w sposób regularny lub w zależności od zdarzenia (np. za każdym razem, gdy użytkownik otworzy aplikację lub doda produkt do koszyka).

AppEngagePublishClient odpowiada za publikowanie klastrów. 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 można wyświetlić treści na urządzeniu.

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.
    }
});

publishRecommendationClusters

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

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 wykona te działania:

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

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishFeaturedCluster

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

Kotlin

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

Java

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

  • Dotychczasowe dane FeaturedCluster pochodzące od partnera dewelopera zostaną usunięte.
  • Dane z zapytania są analizowane i przechowywane w zaktualizowanym zbiorze polecanych.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishContinuationCluster

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

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 wykonywane są te działania:

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

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishUserAccountManagementRequest

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

Te metadane są częścią karty logowania:

Atrybut Wymaganie Opis
Identyfikator URI działania Wymagane Precyzyjny link do działania (np. otwiera stronę logowania w aplikacji)
Obraz Opcjonalnie – jeśli nie zostanie podany, należy podać tytuł.

Obraz na karcie

Obrazy o współczynniku proporcji 16 x 9 i rozdzielczości 1264 x 712
Tytuł Opcjonalnie – jeśli nie zostanie podany, należy podać obraz Tytuł na karcie
Tekst wezwania do działania Opcjonalnie Tekst wezwania do działania (np. Zaloguj się)
Podtytuł Opcjonalnie Opcjonalny tekst na karcie

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 wykonywane są te działania:

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

W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.

updatePublishStatus

Jeśli z jakiegokolwiek wewnętrznego powodu biznesowego żaden z tych klastrów nie został opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu updatePublishStatus API. Jest to ważne, ponieważ:

  • Podanie stanu we wszystkich scenariuszach, nawet po opublikowaniu treści (STATUS == PUBLISHED), ma kluczowe znaczenie przy wypełnianiu paneli, które używają tego stanu wprost do przekazywania danych o stanie i innych wskaźnikach związanych z integracją.
  • Jeśli nie zostaną opublikowane żadne treści, ale stan integracji nie jest nieprawidłowy (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów w panelach stanu aplikacji. Potwierdza ono, że treść nie została opublikowana z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
  • Pomaga deweloperom udostępniać 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 którym będzie on mógł zobaczyć jej zawartość lub ją pokonać.

Lista kodów stanu publikacji, które kwalifikują się do opublikowania:

// 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 jakiegokolwiek 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());

deleteRecommendationClusters

Ten interfejs API służy do usuwania treści z grup rekomendacji.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Gdy usługa otrzyma prośbę, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.

deleteFeaturedCluster

Ten interfejs API służy do usuwania treści z wyróżnionego klastra.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra wyróżnionego. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.

deleteContinuationCluster

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

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z Klastra Kontynuacji. W przypadku błędu cała prośba zostaje odrzucona, a obecny stan jest zachowany.

deleteUserManagementCluster

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Po otrzymaniu żądania usługa usuwa istniejące dane z klastra zarządzania kontami użytkowników. W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

deleteClusters

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

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. Klienty mogą przesyłać 1 lub wiele typów klastrów. W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.

Obsługa błędów

Zdecydowanie zalecamy odsłuchanie wyniku zadania z interfejsów API do publikowania, aby móc podjąć dalsze działania w celu odzyskania i ponowniego przesłania zadania, które zostało wykonane prawidłowo.

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 z przyczyną podaną w kodzie 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 połączenia (na przykład 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żesz spróbować ponownie.
4 SERVICE_CALL_PERMISSION_DENIED Rozmówca nie ma uprawnień do zgłoszenia.
5 SERVICE_CALL_INVALID_ARGUMENT Żądanie zawiera nieprawidłowe dane (np. więcej niż dozwoloną liczbę klastrów).
6 SERVICE_CALL_INTERNAL Po stronie usługi wystąpił błąd.
7 SERVICE_CALL_RESOURCE_EXHAUSTED wywołanie usługi jest wykonywane zbyt często;

Krok 3. Obsługa intencji przesyłania

Oprócz wykonywania wywołań interfejsu Publishing Content API za pomocą zadania musisz też skonfigurować BroadcastReceiver, aby otrzymywać żądanie publikacji treści.

Intencje przesyłania strumieniowego służą głównie do ponownego aktywowania aplikacji i wymuszania synchronizacji danych. Intencje związane z transmisją nie są przeznaczone do wysyłania zbyt często. Jest ona wywoływana tylko wtedy, gdy usługa Engage stwierdzi, że treści mogą być nieaktualne (np. mają tydzień). Dzięki temu użytkownik ma pewność, że będzie mieć dostęp do aktualnych treści, nawet jeśli aplikacja nie była uruchamiana przez długi czas.

Element BroadcastReceiver musi być skonfigurowany w jednym z tych 2 sposobów:

  • Dynamicznie zarejestruj wystąpienie klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacji, które są nadal aktywne 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))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

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));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • Zadeklaruj statycznie implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może otrzymywać intencje transmisji, gdy nie jest uruchomiona, i może publikować treści.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      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 zamiary:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Gdy otrzymasz tę intencję, zalecamy rozpoczęcie rozmowy publishRecommendationClusters.
  • com.google.android.engage.action.PUBLISH_FEATURED Gdy otrzymasz ten zamiar, zalecamy rozpoczęcie rozmowy publishFeaturedCluster.
  • com.google.android.engage.action.PUBLISH_CONTINUATION W przypadku otrzymania tego zamiaru zalecamy nawiązanie połączenia publishContinuationCluster.

Proces integracji

Szczegółowy przewodnik dotyczący weryfikacji integracji po jej zakończeniu znajdziesz w artykule Procedura integracji Engage z aplikacją dewelopera.

Najczęstsze pytania

Odpowiedzi na najczęstsze pytania znajdziesz w odpowiedziach na najczęstsze pytania o pakiet SDK dla Agencji.

Kontakt

Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engage-developers@google.com.

Dalsze kroki

Po zakończeniu integracji należy wykonać następujące czynności:

  • Wyślij e-maila na adres engage-developers@google.com i załącz zintegrowany pakiet APK, który jest gotowy do przetestowania przez Google.
  • Google przeprowadza weryfikację i sprawdza integrację wewnętrznie, aby upewnić się, że działa ona zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, Google skontaktuje się z Tobą, podając niezbędne informacje.
  • Gdy testy zostaną zakończone i nie trzeba będzie wprowadzać żadnych zmian, skontaktujemy się z Tobą, aby poinformować, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Sklepie Play.
  • Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, Twoje klastry Rekomendacja, Polecane i Kontynuacja mogą zostać opublikowane i staną się widoczne dla użytkowników.