Google tworzy platformę na urządzeniu, która porządkuje aplikacje użytkowników według kategorii i zapewnia nowe, atrakcyjne możliwości związane z oglądaniem i odkrywaniem treści aplikacji w spersonalizowany sposób. Dzięki temu partnerzy mogą prezentować swoje najlepsze treści na specjalnym kanale poza aplikacją.
Ten przewodnik zawiera instrukcje dla deweloperów, którzy chcą zintegrować swoje treści audio, korzystając z pakietu SDK dla Agencji do zapełnienia zarówno tej nowej powierzchni, jak i dotychczasowych platform Google.
Szczegóły integracji
Terminologia
Ta integracja obejmuje 3 typy klastrów: Rekomendacja, Kontynuacja i Polecane.
Klastry rekomendacji wyświetlają spersonalizowane sugestie dotyczące treści od danego partnera ds. deweloperów.
Rekomendacje mają taką strukturę:
Klaster rekomendacji: widok interfejsu zawierający grupę rekomendacji od tego samego partnera ds. deweloperów.
Encja: obiekt reprezentujący pojedynczy element w klastrze. Elementem może być np. playlista, audiobook czy podcast. Listę obsługiwanych typów encji znajdziesz w sekcji Podaj dane encji.
Klaster Kontynuacja pokazuje w jednej grupie UI treści audio, w których ostatnio zaangażowali się użytkownicy z wielu partnerów ds. deweloperów. Każdy partner deweloper będzie mógł transmitować maksymalnie 10 encji w klastrze kontynuacji.
Klaster Polecane zawiera elementy pochodzące od różnych deweloperów, które są grupowane w ramach jednego interfejsu. U góry interfejsu pojawi się pojedynczy klaster Polecane, który będzie miał priorytet nad wszystkimi klastrami rekomendacji. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Polecane.
Przygotowanie
Minimalny poziom interfejsu API: 19
Dodaj bibliotekę com.google.android.play:engage
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.4.0'
}
Podsumowanie
Projekt opiera się na implementacji powiązanej usługi.
Dane, które klient może publikować, podlegają tym ograniczeniom w przypadku różnych typów klastrów:
Typ klastra | Limity klastrów | Maksymalne limity encji w klastrze |
---|---|---|
Klastry rekomendacji | Maksymalnie 5 | Maksymalnie 50 |
Klaster kontynuacji | Maksymalnie 1 | Maksymalnie 10 |
Polecany klaster | Maksymalnie 1 | Maksymalnie 10 |
Krok 1. Podaj dane encji
Pakiet SDK ma zdefiniowane różne elementy reprezentujące każdy typ elementu. W kategorii Posłuchaj obsługujemy te elementy:
MusicAlbumEntity
MusicArtistEntity
MusicTrackEntity
MusicVideoEntity
PlaylistEntity
PodcastSeriesEntity
PodcastEpisodeEntity
LiveRadioStationEntity
AudiobookEntity
W tabelach poniżej znajdziesz dostępne atrybuty i wymagania dla poszczególnych typów.
MusicAlbumEntity
Obiekt MusicAlbumEntity
reprezentuje album muzyczny (np. Midnights wykonawcy Taylor Swift).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł albumu muzycznego. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI strony z informacjami | Wymagany |
Precyzyjny link do aplikacji dostawcy, który zawiera szczegółowe informacje o albumie muzycznym. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Wykonawcy | Wymagany | Lista wykonawców występujących w albumie muzycznym. |
Identyfikator URI odtwarzania | Opcjonalnie |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania albumu w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Liczba utworów | Opcjonalnie | Liczba utworów w albumie muzycznym. |
Gatunki | Opcjonalnie | Lista gatunków z albumu muzycznego. |
Format albumu | Opcjonalnie |
ALBUM (w tym LP i podwójny LP) Minialbum POJEDYNKI Składanka |
Wytwórnie muzyczne | Opcjonalnie | Lista wytwórni muzycznych powiązanych z albumem. |
Pobrane na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy album muzyczny został pobrany na urządzenie. |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Data premiery | Opcjonalnie | Data wydania albumu w milisekundach epoki. |
Czas działania | Opcjonalnie | Czas trwania albumu w milisekundach. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
Procent postępu ukończenia | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Liczba całkowita między 0 a 100 |
MusicArtistEntity
Obiekt MusicArtistEntity
reprezentuje arist muzyczną (np. Adele).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Imię i nazwisko lub nazwa wykonawcy. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI strony z informacjami | Wymagany |
Precyzyjny link do aplikacji dostawcy, gdzie znajdziesz szczegółowe informacje o wykonawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI odtwarzania | Opcjonalnie |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania utworów wykonawcy w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
MusicTrackEntity
Obiekt MusicTrackEntity
reprezentuje utwór muzyczny (np. Yellow firmyColdplay).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł utworu muzycznego. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI odtwarzania | Wymagany |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania utworu w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI strony z informacjami | Opcjonalnie |
Precyzyjny link do aplikacji dostawcy zawierającej szczegółowe informacje o utworze muzycznym. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Czas działania | Opcjonalnie | Czas trwania ścieżki w milisekundach. |
Album | Opcjonalnie | Tytuł albumu, do którego należy utwór. |
Wykonawcy | Wymagany | Lista wykonawców związanych z utworem. |
Pobrane na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy utwór został pobrany na urządzenie. |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
Procent postępu ukończenia | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Liczba całkowita między 0 a 100 |
MusicVideoEntity
Obiekt MusicVideoEntity
reprezentuje teledysk (np. The Weeknd – Take My Breath (Official Music Video)).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł teledysku. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI odtwarzania | Wymagany |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania teledysku w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI strony z informacjami | Opcjonalnie |
precyzyjny link do aplikacji dostawcy, który zawiera szczegółowe informacje o teledysku. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Czas działania | Opcjonalnie | Czas trwania filmu w milisekundach. |
liczbę wyświetleń; | Opcjonalnie | Liczba wyświetleń filmu w formacie dowolnego tekstu. |
Wykonawcy | Opcjonalnie | Lista wykonawców teledysku. |
Ocena treści | Opcjonalnie | Lista ocen treści utworu. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Pobrane na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy teledysk został pobrany na urządzenie. |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
Procent postępu ukończenia | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Liczba całkowita między 0 a 100 |
PlaylistEntity
Obiekt PlaylistEntity
reprezentuje playlistę muzyczną (np. playlistę 10 najlepszych utworów w Stanach Zjednoczonych).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł playlisty. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI odtwarzania | Wymagany |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania playlisty muzycznej w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI strony z informacjami | Opcjonalnie |
Precyzyjny link do aplikacji dostawcy, gdzie znajdziesz szczegółowe informacje o playliście muzycznej. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Czas działania | Opcjonalnie | Czas trwania playlisty w milisekundach. |
Liczba utworów | Opcjonalnie | Liczba utworów na playliście muzycznej. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Pobrane na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy playlista została pobrana na urządzenie. |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
Procent postępu ukończenia | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Liczba całkowita między 0 a 100 |
PodcastSeriesEntity
Obiekt PodcastSeriesEntity
reprezentuje serię podcastów (na przykład This American Life).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł serii podcastów. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI strony z informacjami | Wymagany |
Precyzyjny link do aplikacji dostawcy, gdzie znajdziesz szczegółowe informacje o serii podcastów. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI odtwarzania | Opcjonalnie |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania serii podcastów w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Liczba odcinków | Opcjonalnie | Liczba odcinków serii podcastów. |
Nazwa produkcji | Opcjonalnie | Nazwa produkcji serii podcastów. |
Organizatorzy | Opcjonalnie | Lista gospodarzy serii podcastów. |
Gatunki | Opcjonalnie | Lista gatunków podcastów. |
Pobrano na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy podcast został pobrany na urządzenie. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
PodcastEpisodeEntity
Obiekt PodcastEpisodeEntity
reprezentuje serię podcastów (na przykład Spark Bird, odcinek 754: This American Life).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Tytuł odcinka podcastu. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI odtwarzania | Wymagany |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania odcinka podcastu w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Tytuł serii produkcyjnej | Wymagany | Nazwa serii podcastów, do której należy odcinek. |
Czas działania | Wymagany | Czas trwania odcinka podcastu w milisekundach. |
Data publikacji | Wymagany | Data publikacji podcastu (w milisekundach epoki) |
Identyfikator URI strony z informacjami | Opcjonalnie |
Precyzyjny link do aplikacji dostawcy, gdzie znajdziesz szczegółowe informacje o odcinku podcastu. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Nazwa produkcji | Opcjonalnie | Nazwa produkcji serii podcastów. |
Indeks odcinka | Opcjonalnie | Indeks odcinka serialu (pierwszy indeks to 1). |
Organizatorzy | Opcjonalnie | Lista gospodarzy odcinka podcastu. |
Gatunki | Opcjonalnie | Lista gatunków, w których dostępny jest odcinek podcastu. |
Pobrano na urządzenie | Opcjonalnie | Wartość logiczna wskazująca, czy odcinek podcastu został pobrany na urządzenie. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Podcast wideo | Opcjonalnie | Wartość logiczna wskazująca, czy odcinek podcastu zawiera treści wideo |
Wulgaryzmy | Opcjonalnie |
Wartość logiczna wskazująca, czy treść jest jawna, czy nie Elementy, które zawierają treści dla dorosłych lub mają ostrzeżenie ze wskazówkami rodziców, powinny mieć wartość TRUE. Elementy dla pełnoletnich są wyświetlane z tagiem „E”. |
Następny typ nasłuchiwania | Opcjonalnie |
Zalecane w przypadku elementów w klastrze kontynuacji TYPE_FOLLOW – wznawianie w przypadku niedokończonego elementu audio. TYPE_NEXT – kontynuuj tworzenie nowego elementu z serii. TYPE_NEW – nowo wydany. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
Procent postępu ukończenia | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Liczba całkowita między 0 a 100 |
LiveRadioStationEntity
Obiekt LiveRadioStationEntity
reprezentuje stację radiową na żywo (na przykład 98.1 The Breeze).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | Nazwa stacji radiowej na żywo. |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu. |
Identyfikator URI odtwarzania | Wymagany |
Precyzyjny link, który powoduje rozpoczęcie odtwarzania stacji radiowej w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI strony z informacjami | Opcjonalnie |
Precyzyjny link do aplikacji dostawcy zawierającej szczegółowe informacje o stacji radiowej. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Częstotliwość | Opcjonalnie | Częstotliwość nadawania stacji radiowej (np. „98,1 FM”). |
Tytuł programu | Opcjonalnie | Bieżący program odtwarzany w radiu. |
Organizatorzy | Opcjonalnie | Lista gospodarzy stacji radiowej. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Czas ostatniego zaangażowania | Opcjonalnie |
Zalecany w przypadku elementów w klastrze kontynuacji. Może być używany do określania pozycji w rankingu. W milisekundach epoki |
AudiobookEntity
Obiekt AudiobookEntity
reprezentuje audiobooka (np. audiobooka Becoming Michelle Obamy).
Atrybut | Wymóg | Uwagi |
---|---|---|
Nazwa | Wymagany | |
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazów. |
Autor | Wymagany | Musisz podać co najmniej jedno imię i nazwisko autora. |
Narrator | Wymagany | Musisz podać co najmniej 1 imię i nazwisko lektora. |
Identyfikator URI linku do działania | Wymagany |
Precyzyjny link do aplikacji dostawcy audiobooka. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Data publikacji | Opcjonalnie | W milisekundach epoki, jeśli podano. |
Opis | Opcjonalnie | Nazwa nie może przekraczać 200 znaków. |
Cena | Opcjonalnie | Dowolny tekst |
Czas działania | Opcjonalnie | Jeśli została podana, musi być wartością dodatnią. |
Gatunek | Opcjonalnie | Lista gatunków powiązanych z książką. |
Nazwa serii | Opcjonalnie | Nazwa serii, do której należy audiobook (na przykład Harry Potter). |
Indeks jednostek serii | Opcjonalnie | Indeks audiobooka z serii, gdzie 1 to pierwszy audiobook z serii. Jeśli np. Harry Potter i więzień Azkabanu jest trzecią książką w serii, należy ustawić wartość 3. |
Kontynuuj typ książki | Opcjonalnie |
TYPE_continue – wznawianie w przypadku niedokończonej książki. TYPE_NEXT – kontynuuj tworzenie nowego elementu z serii. TYPE_NEW – nowo wydany. |
Czas ostatniego zaangażowania | Wymagane warunkowo | Należy je podać, gdy element znajduje się w klastrze kontynuacji. W milisekundach w epoce. |
Procent postępu ukończenia | Wymagane warunkowo | Należy je podać, gdy element znajduje się w klastrze kontynuacji. *Nowo* pozyskane audiobooki mogą stać się częścią grupy czytających dalej. Wartość musi być większa niż 0 i mniejsza niż 100. |
DisplayTimeWindow – ustaw przedział czasu dla treści wyświetlanej na platformie | ||
Sygnatura czasowa rozpoczęcia | Opcjonalnie |
Sygnatura czasowa epoki, po której treść ma się pojawić na powierzchni. Jeśli zasada jest nieskonfigurowana, treści mogą się wyświetlać na tej platformie. W milisekundach w epoce. |
Sygnatura czasowa zakończenia | Opcjonalnie |
Sygnatura czasowa epoki, po której treści nie wyświetlają się już na powierzchni. Jeśli zasada jest nieskonfigurowana, treści mogą się wyświetlać na tej platformie. W milisekundach w epoce. |
Specyfikacja obrazu
Poniżej znajdziesz wymagane specyfikacje komponentów z obrazem:
Format obrazu | Wymóg | Minimalny rozmiar w pikselach | Zalecany rozmiar w pikselach |
---|---|---|---|
Kwadrat (1 x 1) | Wymagany | 300 × 300 | 1200x1200 |
Poziomy (1,91 x 1) | Opcjonalnie | 600x314 | 1200x628 |
Orientacja pionowa (4 x 5) | Opcjonalnie | 480 × 600 | 960x1200 |
Formaty plików
PNG, JPG, statyczne pliki GIF, WebP
Maksymalny rozmiar pliku
5120 KB
Dodatkowe zalecenia
- 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ą narzędzia WorkManager) i planowane regularnie lub na podstawie zdarzeń (np. za każdym razem, gdy użytkownik otworzy aplikację lub gdy tylko doda coś do koszyka).
Za publikowanie klastrów odpowiada AppEngagePublishClient
. Klient udostępnia te interfejsy API:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
Ten interfejs API służy do sprawdzania, czy usługa jest dostępna do integracji i czy treści można zaprezentować 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 wykonywane są te działania:
- Dotychczasowe dane aplikacji
RecommendationCluster
od partnera 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 istniejący stan zostaje 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 wykonywane są te działania:
- Dotychczasowe dane aplikacji
FeaturedCluster
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze Polecane.
W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje 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 wykonywane są te działania:
- Dotychczasowe dane aplikacji
ContinuationCluster
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze kontynuacji.
W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.
publishUserAccountManagementRequest
Ten interfejs API służy do publikowania karty logowania . Użytkownicy są kierowani na stronę logowania w aplikacji, na której mogą publikować treści (lub udostępniać im bardziej spersonalizowane treści).
Te metadane są częścią karty logowania –
Atrybut | Wymóg | Opis |
---|---|---|
Identyfikator URI działania | Wymagane | Precyzyjny link do działania (np. do strony logowania w aplikacji) |
Obraz | Opcjonalnie – jeśli nie podano tytułu, należy podać tytuł |
Obraz widoczny na karcie obrazy o współczynniku proporcji 16 x 9 i rozdzielczości 1264 x 712, |
tytuł; | Opcjonalnie – jeśli nie podano, należy przesłać obraz. | Tytuł na karcie |
Tekst działania | Opcjonalnie | Tekst wyświetlany w wezwaniu do działania (np. „Zaloguj się”) |
Podtytuł | Opcjonalnie | Opcjonalne napisy 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 całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.
updatePublishStatus
Jeśli z jakichkolwiek wewnętrznych powodów biznesowych nie zostanie opublikowany żaden z klastrów, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu API updatePublishStatus. To ważne, ponieważ :
- Podanie stanu we wszystkich scenariuszach, nawet po opublikowaniu treści (STAN == OPUBLIKOWANO), ma kluczowe znaczenie przy wypełnianiu paneli, które korzystają z tego jednoznacznego stanu do przekazywania informacji o stanie i innych wskaźnikach integracji.
- Jeśli treści nie są opublikowane, ale stan integracji nie jest uszkodzony (STATUS == NOT_OpublikujED), Google może uniknąć aktywowania alertów w panelach stanu aplikacji. Jest to potwierdzenie, że treści nie zostały opublikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
- Dzięki temu deweloperzy mogą określić, kiedy dane są publikowane, a kiedy nie.
- Google może używać kodów stanu, aby skłonić użytkownika do wykonania określonych działań w aplikacji, co pozwoli mu zobaczyć zawartość aplikacji lub ją przezwyciężyć.
Lista kodów stanu kwalifikującego się do 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 zostały opublikowane, ponieważ użytkownik nie jest zalogowany, zalecamy opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_OpublikujED_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 zawartości klastrów rekomendacji.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
Gdy usługa otrzyma żądanie, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.
deleteFeaturedCluster
Ten interfejs API służy do usuwania zawartości polecanego klastra.
Kotlin
client.deleteFeaturedCluster()
Java
client.deleteFeaturedCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z polecanego klastra. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.
deleteContinuationCluster
Ten interfejs API służy do usuwania zawartości 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łe żądanie jest odrzucane, a obecny stan zostaje zachowany.
deleteUserManagementCluster
Ten interfejs API służy do usuwania zawartości klastra UserAccountManagement.
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastra UserAccountManagement. W przypadku błędu całe żądanie jest odrzucane, a bieżący stan zostaje zachowany.
deleteClusters
Ten interfejs API służy do usuwania treści określonego 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 otrzymuje żądanie, usuwa istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienty mogą przekazywać 1 lub wiele typów klastrów. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.
Obsługa błędów
Zdecydowanie zalecamy wsłuchiwanie się w wynik zadania z interfejsów API publikowania, aby można było podjąć dalsze działania w celu odzyskania udanego zadania i ponownego przesłania go.
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 przyczyna jest podana w postaci kodu błędu.
Kod błędu | Uwaga: |
---|---|
SERVICE_NOT_FOUND |
Usługa jest niedostępna na danym urządzeniu. |
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). |
SERVICE_CALL_EXECUTION_FAILURE |
Nie udało się wykonać zadania z powodu problemów z wątkiem. W takim przypadku można spróbować ponownie. |
SERVICE_CALL_PERMISSION_DENIED |
Rozmówca nie może nawiązać połączenia z usługą. |
SERVICE_CALL_INVALID_ARGUMENT |
Żądanie zawiera nieprawidłowe dane (na przykład więcej niż dozwolona liczba klastrów). |
SERVICE_CALL_INTERNAL |
Po stronie usługi wystąpił błąd. |
SERVICE_CALL_RESOURCE_EXHAUSTED |
Wywoływanie usługi jest wykonywane zbyt często. |
Krok 3. Obsługuj intencje transmisji
Oprócz wykonywania wywołań interfejsu Content API w zadaniu musisz też skonfigurować BroadcastReceiver
, aby odbierać żądanie opublikowania treści.
Intencje dotyczące przesyłania służą głównie do reaktywacji aplikacji i wymuszania synchronizacji danych. Intencje transmisji nie są przeznaczone do wysyłania zbyt często. Jest wywoływane tylko wtedy, gdy usługa dla Agencji stwierdzi, że treści mogą być nieaktualne (np. sprzed tygodnia). Dzięki temu zyska on większą pewność, że użytkownik będzie mógł korzystać z nowych treści, nawet jeśli aplikacja nie była uruchamiana od dłuższego czasu.
BroadcastReceiver
należy skonfigurować na dwa sposoby:
- Dynamicznie zarejestruj instancję klasy
BroadcastReceiver
za pomocąContext.registerReceiver()
. Umożliwia to komunikację z aplikacji, które wciąż są zapisane 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));
}
- Statycznie zadeklaruj implementację za pomocą tagu
<receiver>
w plikuAndroidManifest.xml
. Dzięki temu aplikacja może odbierać komunikaty, gdy nie jest uruchomiona, oraz 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 będzie wysyłać te zamiary:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Zalecamy uruchomienie wywołaniapublishRecommendationClusters
przy odbieraniu tej intencji.com.google.android.engage.action.PUBLISH_FEATURED
Zalecamy uruchomienie wywołaniapublishFeaturedCluster
po otrzymaniu tej intencji.com.google.android.engage.action.PUBLISH_CONTINUATION
Gdy odbierasz tę intencję, zalecamy uruchomienie wywołaniapublishContinuationCluster
.
Przepływ pracy w integracji
Szczegółowy przewodnik dotyczący weryfikowania integracji po jej zakończeniu znajdziesz w artykule o procesie integracji programistycznej Google Workspace.
Najczęstsze pytania
Zapoznaj się z odpowiedziami na najczęstsze pytania dotyczące pakietu SDK dla Agencji.
Kontakt
Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engagement-developers@google.com. Nasz zespół odpowie tak szybko, jak to będzie 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, który jest gotowy do przetestowania przez Google.
- Google przeprowadzi weryfikację i weryfikację wewnętrzną, aby sprawdzić, czy integracja działa zgodnie z oczekiwaniami. Jeśli konieczne będą zmiany, Google skontaktuje się z Tobą, aby przekazać Ci wszystkie niezbędne informacje.
- Gdy testy zostaną zakończone i nie będą wymagane żadne zmiany, Google skontaktuje się z Tobą, aby poinformować, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pakietu APK w Sklepie Play.
- Gdy Google potwierdzi, że zaktualizowany plik APK zostanie opublikowany w Sklepie Play, klastry Rekomendacja, Polecane i Kontynuacja zostaną opublikowane i będą widoczne dla użytkowników.