Google tworzy interfejs na urządzeniu, który porządkuje aplikacje użytkowników według branży i umożliwia nowe wciągające wrażenia podczas przeglądania i odtwarzania spersonalizowanych treści w 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 audio za pomocą pakietu Engage SDK, aby wypełnić nową platformę i dotychczasowe platformy Google.
Szczegóły integracji
Terminologia
Ta integracja obejmuje 3 typy klasterów: Recommendation (Rekomendacja), Continuation (Kontynuacja) i Featured (Polecane).
Gromadzą rekomendacje, czyli spersonalizowane sugestie dotyczące treści do przeczytania od konkretnego partnera deweloperskiego.
Rekomendacje mają następującą strukturę:
Klaster rekomendacji: widok interfejsu użytkownika zawierający 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. Obiektem może być playlista, audiobook, podcast itp. Listę obsługiwanych typów encji znajdziesz w sekcji Przygotowanie danych encji.
Rysunek 2. Interfejs Entertainment Space pokazujący pojedynczy element w ramach klastra rekomendacji jednego partnera.
Klaster Kontynuacja zawiera treści audio, z których użytkownicy korzystali niedawno, pochodzące od wielu partnerów deweloperów w ramach jednej grupy interfejsu. Każdy partner deweloper będzie mógł nadawać maksymalnie 10 elementów w klastrze kontynuacji.
Rysunek 3. Interfejs Pokoju z rozrywką przedstawiający klaster kontynuacji z nieukończonymi rekomendacjami od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja). Grupa Polecane zawiera wybrane produkty 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 z priorytetowym umieszczeniem nad wszystkimi klastrami rekomendacji. Każdy partner deweloper może przesyłać do klastra polecanych maksymalnie 10 elementów.
Rysunek 4. Interfejs Entertainment Space z klasterem polecanych treści z rekomendacjami 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 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 7 | Maksymalnie 50 |
Continuation | Maksymalnie 1 | Maksymalnie 20 |
Polecany klaster | Maksymalnie 1 | Maksymalnie 20 |
Krok 1. Podaj dane o podmiocie
Pakiet SDK definiuje różne elementy reprezentujące poszczególne typy elementów. W przypadku kategorii Słuchanie obsługujemy te typy jednostek:
MusicAlbumEntity
MusicArtistEntity
MusicTrackEntity
MusicVideoEntity
PlaylistEntity
PodcastSeriesEntity
PodcastEpisodeEntity
LiveRadioStationEntity
AudiobookEntity
W tabelach poniżej znajdziesz dostępne atrybuty i wymagania dotyczące poszczególnych typów.
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 specyfikacji zdjęć. |
Identyfikator URI strony z informacjami | Wymagany |
precyzyjny link do aplikacji dostawcy, który zawiera informacje 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 uruchamia 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 tę wartość, musi ona mieć maksymalnie 200 znaków. |
Liczba utworów | Opcjonalny | Liczba utworów na płycie muzycznej. |
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ądzeniu | Opcjonalny | Wartość logiczna określająca, czy album muzyczny został pobrany na urządzenie. |
Wulgaryzmy | Opcjonalny |
Wartość logiczna wskazująca, czy treść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. 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 zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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ę (np. Adele).
Atrybut | Wymaganie | Uwagi |
---|---|---|
Nazwa | Wymagany | Imię i nazwisko wykonawcy. |
obrazy plakatu, | Wymagany | Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć. |
Identyfikator URI strony z informacjami | Wymagany |
precyzyjny link do aplikacji dostawcy, który zawiera informacje o wykonawcy muzyki; 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 uruchamia 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 tę wartość, musi ona mieć maksymalnie 200 znaków. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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ł ścieżki dźwiękowej. |
obrazy plakatu, | Wymagany | Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć. |
Identyfikator URI odtwarzania | Wymagany |
precyzyjny link, który uruchamia odtwarzanie utworu 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, który zawiera szczegółowe informacje o utworze muzycznym; Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Opis | Opcjonalny | Jeśli podasz tę wartość, musi ona mieć maksymalnie 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ądzeniu | Opcjonalny | Wartość logiczna określająca, czy ścieżka muzyczna została pobrana na urządzenie. |
Wulgaryzmy | Opcjonalny |
Wartość logiczna wskazująca, czy treść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. Treści dla dorosłych są oznaczone tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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 obrazów. |
Identyfikator URI odtwarzania | Wymagany |
precyzyjny link, który uruchamia 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, który zawiera szczegółowe informacje 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 tę wartość, musi ona mieć maksymalnie 200 znaków. |
Pobrane na urządzeniu | Opcjonalny | Wartość logiczna wskazująca, czy teledysk został pobrany na urządzenie. |
Wulgaryzmy | Opcjonalny |
Wartość logiczna wskazująca, czy treść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. Treści dla dorosłych są oznaczone tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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. Top 10 w USA).
Atrybut | Wymaganie | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł playlisty. |
obrazy plakatu, | Wymagany | Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w sekcji Specyfikacja obrazów. |
Identyfikator URI odtwarzania | Wymagany |
precyzyjny link, który uruchamia 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, który zawiera informacje o playlistzie muzycznej; 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 tę wartość, musi ona mieć maksymalnie 200 znaków. |
Pobrane na urządzeniu | Opcjonalny | Wartość logiczna określająca, czy playlista została pobrana na urządzenie. |
Wulgaryzmy | Opcjonalny |
Wartość logiczna wskazująca, czy treść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. Treści dla dorosłych są oznaczone tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania pozycji. W milisekundach od początku epoki |
Procent ukończenia | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Liczba całkowita z zakresu 0–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 specyfikacji zdjęć. |
Identyfikator URI strony z informacjami | Wymagany |
precyzyjny link do aplikacji dostawcy, który zawiera 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 uruchamia odtwarzanie serii podcastu 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 podcastu. |
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ądzeniu | Opcjonalny | Wartość logiczna wskazująca, czy podcast został pobrany na urządzenie. |
Opis | Opcjonalny | Jeśli podasz tę wartość, musi ona mieć maksymalnie 200 znaków. |
Wulgaryzmy | Opcjonalny |
Wartość logiczna wskazująca, czy treść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. Treści dla dorosłych są oznaczone tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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 specyfikacji zdjęć. |
Identyfikator URI odtwarzania | Wymagany |
precyzyjny link, który uruchamia 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 podcastu, do której należy odcinek. |
Czas działania | Wymagany | Czas trwania odcinka podcastu w milisekundach. |
Data publikacji | Wymagany | Data publikacji podcastu (w milisekundach ery) |
Identyfikator URI strony z informacjami | Opcjonalny |
precyzyjny link do aplikacji dostawcy, który zawiera szczegóły dotyczące odcinka 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 odcinek podcastu. |
Gatunki | Opcjonalny | Lista gatunków odcinka podcastu. |
Pobrane na urządzeniu | Opcjonalny | Wartość logiczna wskazująca, czy odcinek podcastu został pobrany na urządzenie. |
Opis | Opcjonalny | Jeśli podasz tę wartość, musi ona mieć maksymalnie 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ść jest jawna. Wartość TRUE należy ustawić dla elementów zawierających treści dla dorosłych lub ostrzeżenie dla rodziców. Treści dla dorosłych są oznaczone tagiem „E”. |
Listen Next Type | Opcjonalny |
Zalecane w przypadku elementów w klastrze kontynuacji TYPE_CONTINUE – wznowienie odtwarzania nieukończonego elementu audio. TYPE_NEXT – kontynuowanie nowej serii. TYPE_NEW – nowo opublikowany. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania 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ą nadającą na żywo (np. 98.1 The Breeze).
Atrybut | Wymaganie | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł stacji radiowej nadającej na żywo. |
obrazy plakatu, | Wymagany | Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć. |
Identyfikator URI odtwarzania | Wymagany |
precyzyjny link, który uruchamia 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, który zawiera informacje 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 nadawana jest stacja radiowa (np. „98,1 FM”). |
Tytuł programu | Opcjonalny | Aktualny program nadawany w danej stacji radiowej. |
Hosty | Opcjonalny | Lista prowadzących stacji radiowej. |
Opis | Opcjonalny | Jeśli podasz tę wartość, musi ona mieć maksymalnie 200 znaków. |
Czas ostatniego zaangażowania | Opcjonalny |
Zalecane w przypadku produktów w klastrze kontynuacji. Może być używany do ustalania pozycji. W milisekundach od początku epoki |
AudiobookEntity
Obiekt AudiobookEntity
reprezentuje audiobook (np. audiobook Becoming Michelle Obama).
Atrybut | Wymaganie | Uwagi |
---|---|---|
Nazwa | Wymagany | |
obrazy plakatu, | Wymagany | Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć. |
Autor | Wymagany | Musisz podać co najmniej 1 nazwę autora. |
Narrator | Wymagany | Musisz podać co najmniej 1 nazwę lektora. |
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 |
Data publikacji | Opcjonalny | W milisekundach od początku epoki, jeśli podano. |
Opis | Opcjonalny | Jeśli podasz tę wartość, musi ona mieć maksymalnie 200 znaków. |
Cena | Opcjonalny | Tekst otwarty |
Czas działania | Opcjonalny | Jeśli jest podana, musi być wartością dodatnią. |
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 jednostek serii | Opcjonalny | Indeks audiobooka w serii, gdzie 1 oznacza pierwszy audiobook w serii. Jeśli na przykład Harry Potter i Więzień Azkabanu jest 3 książką w serii, wartość ta powinna wynosić 3. |
Kontynuuj rezerwację typu | Opcjonalny |
TYPE_CONTINUE – wznowienie nieukończonej książki. TYPE_NEXT – kontynuowanie nowej serii. TYPE_NEW – nowo opublikowany. |
Ostatni czas zaangażowania | Wymagane warunkowo | Należy go podać, gdy produkt znajduje się w klastrze kontynuacji. W milisekundach od początku epoki. |
Postęp – procent ukończenia | Wymagane warunkowo |
Należy go podać, gdy produkt znajduje się w klastrze kontynuacji. *Nowo* zakupione audiobooki mogą być częścią klastra „Kontynuuj czytanie”. Wartość musi być większa niż 0 i mniejsza niż 100. |
DisplayTimeWindow – ustawienie okna czasowego, w którym treści mają być wyświetlane na urządzeniu | ||
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 mogą być wyświetlane na powierzchni. W milisekundach od początku epoki. |
Sygnatura czasowa zakończenia | Opcjonalny |
Znak czasu epoki, po którym treści nie są już wyświetlane na powierzchni. Jeśli nie skonfigurujesz tej zasady, treści mogą być wyświetlane na powierzchni. W milisekundach od początku epoki. |
Specyfikacja obrazu
Wymagania dotyczące komponentów z obrazem:
Format obrazu | Wymaganie | Minimalna liczba pikseli | Zalecany rozmiar w pikselach |
---|---|---|---|
Kwadrat (1 x 1) | Wymagany | 300 x 300 | 1200 x 1200 |
Orientacja pozioma (1,91 x 1) | Opcjonalny | 600 x 314 | 1200 x 628 |
Orientacja pionowa (4 x 5) | 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, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i zaplanowane w sposób regularny lub zależny od zdarzenia (np. za każdym razem, gdy użytkownik otworzy aplikację lub 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 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("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 wykona te działania:
- Istniejące dane
RecommendationCluster
od partnera dewelopera zostaną usunięte. - Dane z zapytania 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() ... .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( new FeaturedCluster.Builder() ... .build()) .build());
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykona te działania:
- Istniejące dane
FeaturedCluster
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( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykona te działania:
- Istniejące dane
ContinuationCluster
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 aplikacji Action (np. przekierowuje na stronę logowania do aplikacji) |
Obraz | Opcjonalnie – jeśli nie zostanie podany, należy podać tytuł. |
Obraz na karcie obrazy w formacie 16 x 9 o rozdzielczości 1264 x 712; |
Tytuł | Opcjonalnie – jeśli nie zostanie podany, należy podać obraz | Tytuł na karcie |
Tekst wezwania do działania | Opcjonalny | Tekst wezwania do działania (np. Zaloguj się) |
Podtytuł | Opcjonalny | Opcjonalny napis 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 wykona 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ła prośba jest odrzucana, a obecny stan jest 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 gdy treści są opublikowane (STATUS = PUBLISHED), jest kluczowe dla wypełniania paneli, które używają tego stanu do przekazywania informacji o stanie i innych danych dotyczących integracji.
- Jeśli nie ma opublikowanych treści, ale integracja nie jest uszkodzona (STATUS = NOT_PUBLISHED), Google może nie uruchamiać alertów na panelach danych dotyczących zdrowia w aplikacji. Potwierdza, że treści nie są publikowane z powodu oczekiwanego stanu 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 wyświetlania :
// 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ła prośba zostaje odrzucona, a istniejący stan jest 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 wyróżnionego klastra. W przypadku błędu cała prośba zostaje odrzucona, a istniejący stan jest zachowany.
deleteContinuationCluster
To 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 istniejący stan jest zachowany.
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, usuwa istniejące dane z klastra UserAccountManagement. 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_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ła prośba jest odrzucana, a istniejący stan jest zachowany.
Obsługa błędów
Zdecydowanie zalecamy odsłuchanie wyniku zadania z interfejsów API do publikowania, aby można było podjąć dalsze działania w celu odzyskania i ponowniego przesłania zadania, które zostało wykonane prawidłowo.
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 w postaci kodu 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 wywoływania interfejsu Content API za pomocą zadania musisz też skonfigurować BroadcastReceiver
, aby odbierać prośby o publikowanie treści.
Intencje przesyłania są przeznaczone głównie do ponownej aktywacji aplikacji i wymuszania synchronizacji danych. Intencje dotyczące transmisji 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 instancję klasy
BroadcastReceiver
za pomocą funkcjiContext.registerReceiver()
. Umożliwia to komunikację z aplikacji, które są nadal aktywne w pamięci.
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 plikuAndroidManifest.xml
. Dzięki temu aplikacja może odbierać intencje przesyłania, gdy nie jest uruchomiona, a takż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 wyśle te intencje:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
W przypadku tej intencji zalecamy rozpoczęcie rozmowypublishRecommendationClusters
.com.google.android.engage.action.PUBLISH_FEATURED
Gdy otrzymasz ten zamiar, zalecamy rozpoczęcie rozmowypublishFeaturedCluster
.com.google.android.engage.action.PUBLISH_CONTINUATION
W przypadku otrzymania tego zamiaru zalecamy rozpoczęcie rozmowypublishContinuationCluster
.
Proces integracji
Szczegółowy przewodnik po weryfikacji integracji po jej zakończeniu znajdziesz w artykule Proces integracji z Engage dla deweloperów.
Najczęstsze pytania
Najczęstsze pytania dotyczące Engage SDK znajdziesz w artykule Najczęstsze pytania dotyczące Engage SDK.
Kontakt
Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engage-developers@google.com. Nasz zespół odpowie tak szybko, jak to możliwe.
Dalsze kroki
Po zakończeniu tej integracji wykonaj te 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 przeprowadzi wewnętrzną weryfikację i sprawdzenie, aby upewnić się, że integracja działa zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, skontaktujemy się z Tobą, aby przekazać 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 Google Play.
- Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, Twoje grupy rekomendacji, polecanych i kontynuacji będą publikowane i widoczne dla użytkowników.