Engage SDK Listen: instrukcje dotyczące integracji technicznej z usługami innych firm

Zwiększ zaangażowanie w aplikację, docierając do użytkowników tam, gdzie się znajdują. Zintegruj pakiet Engage SDK, aby wyświetlać spersonalizowane rekomendacje i treści kontynuacji 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 dostarczania treści audio (muzyki, podcastów, audiobooków, radia na żywo) na platformy treści angażujących.

Szczegóły integracji

Terminologia

Ta integracja obejmuje 3 typy klastrów: Rekomendacje, KontynuacjaWyróżnione.

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

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

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

      Rysunek 1. Interfejs Entertainment Space z grupą rekomendacji od jednego partnera.
    • Jednostka: obiekt reprezentujący pojedynczy element w klastrze. Elementem może być playlista, audiobook, podcast itp. Listę obsługiwanych typów encji znajdziesz w sekcji Podawanie danych o encjach.

      Rysunek 2. Interfejs Entertainment Space przedstawiający pojedynczy element w ramach klastra rekomendacji jednego z partnerów.
  • Grupa Kontynuacja zawiera treści audio, z którymi użytkownicy ostatnio wchodzili w interakcję, pochodzące od wielu partnerów programistów w jednym układzie interfejsu. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Kontynuacja.

    Rysunek 3. Interfejs przestrzeni rozrywki 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 Entertainment Space 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.5.2'
}

Podsumowanie

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

Dane, które klient może publikować, 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
Polecany klaster Maksymalnie 1 Maksymalnie 20

Krok 1. Podaj dane podmiotu

Pakiet SDK ma zdefiniowane różne elementy reprezentujące każdy typ produktu. W przypadku kategorii Słuchaj obsługujemy te typy:

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

W tabelach poniżej znajdziesz listę dostępnych atrybutów i wymagań dla każdego typu.

MusicAlbumEntity

Obiekt MusicAlbumEntity reprezentuje album muzyczny (np. Midnights Taylor Swift).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł albumu muzycznego.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI strony z informacjami Wymagany

Precyzyjny link do aplikacji dostawcy z informacjami o albumie muzycznym.

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

Wykonawcy Wymagany Lista wykonawców na albumie muzycznym.
Identyfikator URI odtwarzania Opcjonalny

Precyzyjny link, który rozpoczyna odtwarzanie albumu w aplikacji dostawcy.

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

Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Liczba utworów Opcjonalny Liczba utworów na albumie muzycznym.
Gatunki Opcjonalny Lista gatunków na albumie muzycznym.
Format albumu Opcjonalny

ALBUM (w tym LP i podwójny LP)

EP

SINGLE

Składanka

Wytwórnie muzyczne Opcjonalny Lista wytwórni muzycznych powiązanych z albumem.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy album muzyczny jest pobrany na urządzenie.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Data premiery Opcjonalny Data wydania albumu w milisekundach od początku epoki.
Czas działania Opcjonalny Czas trwania albumu w milisekundach.
Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

Procent ukończenia Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji.

Liczba całkowita z zakresu od 0 do 100

MusicArtistEntity

Obiekt MusicArtistEntity reprezentuje wykonawcę muzycznego (np. Adele).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Nazwa wykonawcy muzycznego.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI strony z informacjami Wymagany

Precyzyjny link do aplikacji dostawcy z informacjami o wykonawcy muzycznym.

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

Identyfikator URI odtwarzania Opcjonalny

Precyzyjny link, który rozpoczyna odtwarzanie utworów wykonawcy w aplikacji dostawcy.

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

Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

MusicTrackEntity

Obiekt MusicTrackEntity reprezentuje utwór muzyczny (np. Yellow zespołu Coldplay).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł utworu muzycznego.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI odtwarzania Wymagany

Precyzyjny link, który rozpoczyna odtwarzanie utworu muzycznego w aplikacji dostawcy.

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

Wykonawcy Wymagany Lista wykonawców utworu muzycznego.
Identyfikator URI strony z informacjami Opcjonalny

Precyzyjny link do aplikacji dostawcy, w której znajdziesz szczegółowe informacje o utworze.

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

Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Czas działania Opcjonalny Czas trwania utworu w milisekundach.
Album Opcjonalny Nazwa albumu, do którego należy utwór.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy utwór muzyczny jest pobrany na urządzenie.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

Procent ukończenia Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji.

Liczba całkowita z zakresu od 0 do 100

MusicVideoEntity

Obiekt MusicVideoEntity reprezentuje teledysk (np. The Weeknd – Take My Breath (Official Music Video)).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł teledysku.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI odtwarzania Wymagany

Precyzyjny link, który rozpoczyna odtwarzanie teledysku w aplikacji dostawcy.

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

Identyfikator URI strony z informacjami Opcjonalny

Precyzyjny link do aplikacji dostawcy z informacjami o teledysku.

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

Czas działania Opcjonalny Czas trwania filmu w milisekundach.
Liczba wyświetleń Opcjonalny Liczba wyświetleń filmu w formacie dowolnego tekstu.
Wykonawcy Opcjonalny Lista wykonawców teledysku.
Ocena treści Opcjonalny Lista ocen treści utworu.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy teledysk jest pobrany na urządzenie.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

Procent ukończenia Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji.

Liczba całkowita z zakresu od 0 do 100

PlaylistEntity

Obiekt PlaylistEntity reprezentuje playlistę muzyczną (np. playlistę 10 najpopularniejszych utworów w Stanach Zjednoczonych).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł playlisty.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI odtwarzania Wymagany

Precyzyjny link, który rozpoczyna odtwarzanie playlisty muzycznej w aplikacji dostawcy.

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

Identyfikator URI strony z informacjami Opcjonalny

precyzyjny link do aplikacji dostawcy, w której znajdziesz szczegółowe informacje o playliście.

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

Czas działania Opcjonalny Czas trwania playlisty w milisekundach.
Liczba utworów Opcjonalny Liczba utworów na playliście muzycznej.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy playlista jest pobrana na urządzenie.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

Procent ukończenia Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji.

Liczba całkowita z zakresu od 0 do 100

PodcastSeriesEntity

Obiekt PodcastSeriesEntity reprezentuje serię podcastów (np. This American Life).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł serii podcastów.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI strony z informacjami Wymagany

precyzyjny link do aplikacji dostawcy, w której można znaleźć szczegółowe informacje o serii podcastów;

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

Identyfikator URI odtwarzania Opcjonalny

Precyzyjny link, który rozpoczyna odtwarzanie serii podcastów w aplikacji dostawcy.

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

Liczba odcinków Opcjonalny Liczba odcinków w serii podcastów.
Nazwa produkcji Opcjonalny Nazwa produkcji serii podcastów.
Hosty Opcjonalny Lista prowadzących serię podcastów.
Gatunki Opcjonalny Lista gatunków serii podcastów.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy podcast jest pobrany na urządzenie.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

PodcastEpisodeEntity

Obiekt PodcastEpisodeEntity reprezentuje serię podcastów (np. Spark Bird, odcinek 754: This American Life).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł odcinka podcastu.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI odtwarzania Wymagany

Precyzyjny link, który rozpoczyna odtwarzanie odcinka podcastu w aplikacji dostawcy.

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

Tytuł serii podcastów Wymagany Nazwa serii podcastów, do której należy odcinek.
Czas działania Wymagany Czas trwania odcinka podcastu w milisekundach.
Data opublikowania Wymagany Data publikacji podcastu (w milisekundach epoki)
Identyfikator URI strony z informacjami Opcjonalny

Precyzyjny link do aplikacji dostawcy z informacjami o odcinku podcastu.

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

Nazwa produkcji Opcjonalny Nazwa produkcji serii podcastów.
Indeks odcinków Opcjonalny Indeks odcinka w serii (pierwszy indeks to 1).
Hosty Opcjonalny Lista prowadzących odcinka podcastu.
Gatunki Opcjonalny Lista gatunków odcinka podcastu.
Pobrane na urządzenie Opcjonalny Wartość logiczna wskazująca, czy odcinek podcastu jest pobrany na urządzenie.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Podcast wideo Opcjonalny Wartość logiczna wskazująca, czy odcinek podcastu zawiera treści wideo.
Wulgaryzmy Opcjonalny

Wartość logiczna wskazująca, czy treści są przeznaczone dla dorosłych.

Elementy zawierające materiały dla dorosłych lub ostrzeżenie o treściach nieodpowiednich dla dzieci powinny mieć wartość TRUE. Treści dla dorosłych są oznaczone tagiem „E”.

Typ „Posłuchaj następnego” Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji

TYPE_CONTINUE – wznów odtwarzanie niedokończonego elementu audio.

TYPE_NEXT – kontynuuj w ramach nowej serii.

TYPE_NEW – nowo wydane.

Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki,

Procent ukończenia Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji.

Liczba całkowita z zakresu od 0 do 100

LiveRadioStationEntity

Obiekt LiveRadioStationEntity reprezentuje stację radiową na żywo (np. 98.1 The Breeze).

Atrybut Wymaganie Uwagi
Nazwa Wymagany Tytuł stacji radiowej na żywo.
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazu.
Identyfikator URI odtwarzania Wymagany

Precyzyjny link, który rozpoczyna odtwarzanie stacji radiowej w aplikacji dostawcy.

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

Identyfikator URI strony z informacjami Opcjonalny

Precyzyjny link do aplikacji dostawcy z informacjami o stacji radiowej.

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

Częstotliwość Opcjonalny Częstotliwość, na której nadaje stacja radiowa (np. „98,1 FM”).
Tytuł programu Opcjonalny Aktualny program nadawany w stacji radiowej.
Hosty Opcjonalny Lista gospodarzy stacji radiowej.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Czas ostatniego działania związanego z zaangażowaniem Opcjonalny

Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do określania pozycji.

w milisekundach od początku epoki.

AudiobookEntity

Obiekt AudiobookEntity reprezentuje audiobooka (np. audiobook Becoming Michelle Obamy).

Atrybut Wymaganie Uwagi
Nazwa Wymagany
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacje obrazu.
Autor Wymagany Musisz podać co najmniej 1 imię i nazwisko autora.
Identyfikator URI linku do działania Wymagany

Precyzyjny link do aplikacji dostawcy audiobooka.

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

Narrator Opcjonalny Musisz podać co najmniej 1 imię i nazwisko lektora.
Data publikacji Opcjonalny Jeśli podano wartość, jest ona wyrażona w milisekundach od początku epoki.
Opis Opcjonalny Jeśli podasz opis, nie może on przekraczać 200 znaków.
Cena Opcjonalny Dowolny tekst
Czas działania Opcjonalny Jeśli wartość jest podana, musi być dodatnia.
Gatunek Opcjonalny Lista gatunków powiązanych z książką.
Nazwa serii Opcjonalny Nazwa serii, do której należy audiobook (np. Harry Potter).
Indeks jednostki serii Opcjonalny Indeks audiobooka w serii, gdzie 1 oznacza pierwszy audiobook w serii. Jeśli np. Harry Potter i więzień Azkabanu to 3 książka w serii, wartość powinna wynosić 3.
Typ kontynuacji książki Opcjonalny

TYPE_CONTINUE – wznowienie czytania niedokończonej książki.

TYPE_NEXT – kontynuuj w ramach nowej serii.

TYPE_NEW – nowo wydane.

Czas ostatniego działania związanego z zaangażowaniem Wymagane warunkowo

Musisz podać tę wartość, jeśli produkt znajduje się w klastrze kontynuacji.

W milisekundach od początku epoki.

Procent ukończenia Wymagane warunkowo

Musisz podać tę wartość, jeśli produkt znajduje się w klastrze kontynuacji.

*Nowo* zakupione audiobooki mogą być częścią grupy „Kontynuuj czytanie”.

Wartość musi być większa niż 0 i mniejsza niż 100.

DisplayTimeWindow – ustawianie przedziału czasu, w którym treści mają być wyświetlane na platformie
Sygnatura czasowa rozpoczęcia Opcjonalny

Sygnatura czasowa epoki, po której treści powinny być wyświetlane na danej platformie.

Jeśli nie skonfigurujesz tej zasady, treści będą mogły być wyświetlane na danej platformie.

W milisekundach od początku epoki.

Sygnatura czasowa zakończenia Opcjonalny

Sygnatura czasowa epoki, po której treści nie są już wyświetlane na danej platformie.

Jeśli nie skonfigurujesz tej zasady, treści będą mogły być wyświetlane na danej platformie.

W milisekundach od początku epoki.

Specyfikacja obrazu

Wymagane specyfikacje komponentów z obrazem są wymienione poniżej:

Format obrazu Wymaganie Minimalny rozmiar w pikselach Zalecany rozmiar w pikselach
Kwadrat (1:1) Wymagany 300 x 300 1200 x 1200
Poziomy (1,91 x 1) Opcjonalny 600 x 314 1200 x 628
Orientacja pionowa (4x5) Opcjonalny 480 x 600 960 x 1200

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łady

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();
AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

Krok 2. Podaj dane klastra

Zalecamy wykonywanie zadania publikowania treści w tle (np. za pomocą WorkManager) i regularne planowanie go lub planowanie go na podstawie zdarzeń (np. za każdym razem, gdy użytkownik otwiera aplikację lub gdy właśnie dodał coś 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 treść może być wyświetlana 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("Trending music")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

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

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

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

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

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

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

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(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

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

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

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

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Działanie logowania przekierowuje użytkowników na stronę logowania aplikacji, aby mogła ona 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. przejście do strony logowania w aplikacji)
Obraz Opcjonalny – jeśli nie zostanie podany, należy podać tytuł

Obraz wyświetlany na karcie

Obrazy o formacie 16:9 i rozdzielczości 1264 x 712

Tytuł Opcjonalny – jeśli nie zostanie podany, należy podać obraz Tytuł na karcie
Tekst działania Opcjonalny Tekst wyświetlany w wezwaniu do działania (np. Zaloguj się)
Podtytuł Opcjonalny Opcjonalny podtytuł 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 zostaną wykonane 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 całe żądanie jest odrzucane, a dotychczasowy stan jest zachowywany.

updatePublishStatus

Jeśli z jakiegokolwiek powodu wewnętrznego żadna z grup nie jest opublikowana, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu updatePublishStatus API. Jest to ważne, ponieważ :

  • Podawanie stanu we wszystkich scenariuszach, nawet gdy treść jest opublikowana (STATUS == PUBLISHED), jest kluczowe do wypełniania paneli, które używają tego jawnego stanu do przekazywania informacji o kondycji i innych danych integracji.
  • Jeśli żadne treści nie są publikowane, ale stan integracji nie jest uszkodzony (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów na panelach stanu aplikacji. Potwierdza, że treści nie są publikowane z powodu przewidywanej sytuacji z punktu widzenia dostawcy.
  • Pomaga deweloperom określać, kiedy dane są publikowane, a kiedy nie.
  • Google może używać kodów stanu, aby zachęcać użytkownika do podejmowania określonych działań w aplikacji, dzięki którym będzie mógł wyświetlić 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());

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 dotychczasowe dane z klastrów rekomendacji. W przypadku błędu cała prośba jest odrzucana i zachowywany jest dotychczasowy stan.

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 dotychczasowe dane z wyróżnionego klastra. W przypadku błędu cała prośba jest odrzucana i zachowywany jest dotychczasowy stan.

deleteContinuationCluster

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

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 jest odrzucana i zachowywany jest dotychczasowy stan.

deleteUserManagementCluster

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

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, a dotychczasowy stan jest zachowywany.

deleteClusters

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

Kotlin

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

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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, a dotychczasowy stan pozostaje bez zmian.

Obsługa błędów

Zdecydowanie zalecamy odsł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ę niepowodzeniem.

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 obiekt 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 w momencie połączenia jest niedostępna (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 ponowić próbę.
4 SERVICE_CALL_PERMISSION_DENIED Element wywołujący nie ma uprawnień do wykonania 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 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 transmisji

Oprócz wykonywania wywołań interfejsu API publikowania treści za pomocą zadania musisz też skonfigurować BroadcastReceiver, aby otrzymywać prośby o publikowanie treści.

Celem intencji rozgłaszania jest głównie ponowna aktywacja aplikacji i wymuszenie synchronizacji danych. Intencje transmisji nie są przeznaczone do wysyłania zbyt często. Jest ona wywoływana tylko wtedy, gdy usługa Engage uzna, że treść może być nieaktualna (np. ma tydzień). Dzięki temu użytkownik może mieć pewność, że będzie korzystać z najnowszych treści, nawet jeśli aplikacja nie była uruchamiana przez dłuższy czas.

BroadcastReceiver musi być skonfigurowany na 2 sposoby:

  • Dynamiczne rejestrowanie instancji klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacjami, 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),
                           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);

}
  • Statycznie zadeklaruj 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 będzie wysyłać te intencje:

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

Przepływ pracy integracji

Szczegółowe instrukcje weryfikacji integracji po jej zakończeniu znajdziesz w artykule Przepływ pracy integracji z platformą Engage dla programistów.

Najczęstsze pytania

Odpowiedzi na najczęstsze pytania znajdziesz w sekcji Najczęstsze pytania dotyczące pakietu Engage SDK.

Kontakt

Jeśli podczas procesu integracji pojawią się pytania, skontaktuj się z nami.engage-developers@google.com Nasz zespół odpowie tak szybko, jak to możliwe.

Dalsze kroki

Po zakończeniu integracji wykonaj te czynności:

  • Wyślij e-maila na adres engage-developers@google.com i załącz zintegrowany pakiet APK gotowy do testowania przez Google.
  • Google przeprowadzi weryfikację i sprawdzi wewnętrznie, czy integracja działa zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, skontaktujemy się z Tobą i podamy niezbędne szczegóły.
  • Gdy testy zostaną zakończone i nie będą potrzebne żadne zmiany, skontaktujemy się z Tobą, aby poinformować Cię, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Sklepie Play.
  • Gdy potwierdzimy, że zaktualizowany pakiet APK został opublikowany w Sklepie Play, klastry Rekomendacja, WyróżnioneKontynuacja będą opublikowane i widoczne dla użytkowników.