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 z zakupami, korzystając z pakietu SDK dla Agencji do zapełnienia zarówno tej nowej powierzchni, jak i dotychczasowych usług Google, takich jak Entertainment Space.
Szczegóły integracji
Poniżej znajdziesz szczegóły integracji:
Terminologia
Ta integracja obejmuje 5 typów klastrów: Rekomendacja, Polecane, Koszyk, Lista zakupów i Zmiana kolejności.
Klastry rekomendacji wyświetlają spersonalizowane sugestie zakupów od poszczególnych partnerów programistycznych. Te rekomendacje mogą być dostosowane do użytkownika lub uogólnione (np. zyskujące popularność). Możesz za ich pomocą wyświetlać informacje o produktach, wydarzeniach, wyprzedażach, promocjach i subskrypcjach.
Rekomendacje mają taką strukturę:
Klaster rekomendacji: widok interfejsu zawierający grupę rekomendacji od tego samego partnera ds. deweloperów.
ShoppingEntity: obiekt reprezentujący pojedynczy produkt w klastrze.
Klaster Polecane prezentuje w ramach 1 grupy UI wybrany główny motyw
ShoppingEntity
od wielu partnerów deweloperów. U góry interfejsu pojawia się pojedynczy klaster Polecane, który ma priorytet nad wszystkimi klastrami rekomendacji. Każdy partner deweloper może opublikować w grupie Polecane 1 pojedynczy element ShoppingEntity.Klaster Koszyk zapewnia podgląd koszyków na zakupy od wielu deweloperów w ramach jednej grupy, zachęcając użytkowników do uzupełnienia koszyka oczekujących. U góry interfejsu znajduje się pojedynczy koszyk na zakupy, który ma priorytet nad wszystkimi klastrami rekomendacji. Każdy partner deweloper może transmitować 1
ShoppingCart
w klastrze koszyka.Twój koszyk na zakupy ma taką strukturę:
Klaster koszyka na zakupy: widok interfejsu, który zawiera grupę podglądów koszyka na zakupy od wielu partnerów deweloperów.
Koszyk na zakupy: obiekt reprezentujący podgląd koszyka na zakupy dla pojedynczego dewelopera, który będzie wyświetlany w klastrze koszyka.
ShoppingCart
musi pokazywać łączną liczbę produktów w koszyku. Może też zawierać zdjęcia niektórych produktów w koszyku użytkownika.
Klaster z listą zakupów wyświetla podgląd list zakupów od wielu partnerów deweloperów w jednej grupie interfejsu, zachęcając użytkowników do powrotu do odpowiedniej aplikacji, aby zaktualizować i uzupełnić listy. Mamy jeden klaster z listą zakupów.
Klaster Zmiana kolejności umożliwia przeglądanie wcześniejszych zamówień od wielu partnerów deweloperów w jednym grupowaniu w interfejsie, co zachęca użytkowników do zmiany kolejności. Istnieje jeden klaster zmiany kolejności.
Klaster zmiany kolejności musi pokazywać łączną liczbę elementów w poprzednim zamówieniu użytkownika oraz jeden z tych elementów:
- Obrazy dla X elementów w poprzednim zamówieniu użytkownika.
- Etykiety X elementów w poprzedniej kolejności użytkownika.
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'
}
Więcej informacji znajdziesz w artykule o widoczności pakietów w Androidzie 11.
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 25 ShoppingEntity |
Polecany klaster | Maksymalnie 1 | Maksymalnie 1 ShoppingEntity |
Klaster koszyka na zakupy | Maksymalnie 1 | Maksymalnie 1 ShoppingCart |
Klaster listy zakupów | Maksymalnie 1 | Maksymalnie 1 ShoppingListEntity |
Klaster zmiany kolejności zakupów | Maksymalnie 1 | Maksymalnie 1 ReorderEntity |
Krok 1. Podaj dane encji
Pakiet SDK ma zdefiniowane różne elementy reprezentujące każdy typ elementu. W przypadku kategorii Zakupy obsługiwane są te elementy:
ShoppingEntity
ShoppingCart
ShoppingList
Reorder
W tabelach poniżej znajdziesz dostępne atrybuty i wymagania dla poszczególnych typów.
ShoppingEntity
Obiekt ShoppingEntity
reprezentuje produkt, promocję, ofertę, subskrypcję lub wydarzenie, które partnerzy chcą opublikować.
ShoppingEntity
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Obrazy plakatu | Wymagany | Musisz przesłać co najmniej 1 obraz. | Wskazówki znajdziesz w specyfikacji obrazów. |
Identyfikator URI działania | Wymagany |
Precyzyjny link do strony w aplikacji zawierającej szczegółowe informacje o elemencie. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI |
tytuł; | Opcjonalnie | Nazwa elementu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 90 znaków (zbyt długi tekst może zawierać wielokropki) |
Cena - aktualna | Wymagane warunkowo | Aktualna cena elementu. Trzeba go podać, jeśli podano przekreśloną cenę. |
Dowolny tekst |
Cena – przekreślenie | Opcjonalnie | Pierwotna cena elementu, która jest przekreślona w interfejsie. | Dowolny tekst |
Objaśnienie | Opcjonalnie | Objaśnienie zawierające promocję, wydarzenie lub aktualizację elementu, jeśli są dostępne. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Objaśnienie drobnym drukiem | Opcjonalnie | Tekst objaśnienia drobnym drukiem. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Ocena (opcjonalnie) – uwaga: wszystkie oceny są wyświetlane w naszym standardowym systemie ocen. | |||
Ocena – wartość maksymalna | Wymagane | Maksymalna wartość skali ocen. Trzeba podać tę wartość, jeśli podano również bieżącą wartość oceny. |
Liczba >= 0,0 |
Ocena – obecna wartość | Wymagane | Bieżąca wartość oceny jednostki. Trzeba go podać, jeśli podano też maksymalną wartość oceny. |
Liczba >= 0,0 |
Ocena – liczba | Opcjonalnie | Liczba ocen elementu. | Ciąg znaków |
DisplayTimeWindow (opcjonalnie) – 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. |
Sygnatura czasowa epoki w milisekundach |
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. |
Sygnatura czasowa epoki w milisekundach |
ShoppingCart
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link do koszyka w aplikacji partnera. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI |
Liczba elementów | Wymagany | Liczba elementów (a nie tylko liczby produktów) w koszyku. Na przykład: jeśli w koszyku znajdują się 3 identyczne koszule i 1 kapelusz, ta liczba powinna wynosić 4. |
Liczba całkowita >= 1 |
Tekst działania | Opcjonalnie |
Tekst wezwania do działania przycisku w koszyku (np. Twoja torba na zakupy). Jeśli deweloper nie poda tekstu działania, domyślną wartością jest Wyświetl koszyk. Ten atrybut jest obsługiwany od wersji 1.1.0. |
Ciąg znaków |
tytuł; | Opcjonalnie | Tytuł koszyka (na przykład Twoja torba na zakupy). Jeśli programista nie poda tytułu, domyślną wartością jest Twój koszyk. |
Dowolny tekst Zalecany rozmiar tekstu: poniżej 25 znaków (zbyt długi tekst może zawierać wielokropki) |
Obrazy koszyka | Opcjonalnie | Zdjęcia każdego produktu w koszyku. Możesz udostępnić maksymalnie 10 obrazów według priorytetu. Rzeczywista liczba wyświetlanych obrazów zależy od formatu urządzenia. |
Wskazówki znajdziesz w specyfikacji obrazów. |
Etykiety elementów | Opcjonalnie | Lista etykiet produktów na liście zakupów. Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia. |
Lista bezpłatnych etykiet tekstowych Zalecany rozmiar tekstu: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
DisplayTimeWindow (opcjonalnie) – 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. |
Sygnatura czasowa epoki w milisekundach |
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. |
Sygnatura czasowa epoki w milisekundach |
ShoppingList
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link do listy zakupów w aplikacji partnera. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI |
Liczba elementów | Wymagany | Liczba produktów na liście zakupów. | Liczba całkowita >= 1 |
tytuł; | Opcjonalnie |
Tytuł listy (na przykład Twoja lista zakupów). Jeśli deweloper nie poda tytułu, domyślną wartością jest Lista zakupów. |
Dowolny tekst Zalecany rozmiar tekstu: poniżej 25 znaków (zbyt długi tekst może zawierać wielokropki) |
Etykiety elementów | Wymagany | Lista etykiet produktów na liście zakupów. Należy podać co najmniej 1 etykietę i maksymalnie 10 etykiet według priorytetu. Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia. |
Lista bezpłatnych etykiet tekstowych Zalecany rozmiar tekstu: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
ShoppingReorderCluster
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link umożliwiający zmianę kolejności w aplikacji partnera. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Identyfikator URI |
Tekst działania | Opcjonalnie |
Tekst wezwania do działania przycisku zmiany kolejności (np. Zamów ponownie). Jeśli deweloper nie poda tekstu działania, domyślną wartością jest Zmień kolejność. Ten atrybut jest obsługiwany od wersji 1.1.0. |
Ciąg znaków |
Liczba elementów | Wymagany | Liczba produktów (a nie tylko liczba produktów) w poprzednim zamówieniu. Na przykład: jeśli w poprzednim zamówieniu były 3 małe kawy i 1 croissant, ta liczba powinna wynosić 4. |
Liczba całkowita >= 1 |
tytuł; | Wymagany | Tytuł elementu zmiany kolejności. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 40 znaków (zbyt długi tekst może zawierać wielokropki) |
Etykiety elementów | Opcjonalnie (Jeśli nie podano, należy przesłać obrazy plakatu). |
Lista etykiet produktów poprzedniego zamówienia. Można podać do 10 etykiet według priorytetu. Rzeczywista liczba etykiet zależy od formatu urządzenia. |
Lista bezpłatnych tekstów Zalecany rozmiar tekstu na etykietę: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
Obrazy plakatu | Opcjonalnie (Jeśli nie podano, należy podać etykiety produktów) |
Zdjęcia produktów w poprzedniej kolejności. Możesz udostępnić maksymalnie 10 obrazów według priorytetu. Rzeczywista liczba wyświetlanych obrazów zależy od formatu urządzenia. |
Wskazówki znajdziesz w specyfikacji obrazów. |
Specyfikacja obrazu
Poniżej znajdziesz wymagane specyfikacje komponentów z obrazem:
Format obrazu | Minimalny rozmiar w pikselach | Zalecany rozmiar w pikselach |
---|---|---|
Kwadrat (1 x 1) Preferowana w przypadku klastrów niepolecanych |
300 × 300 | 1200x1200 |
Poziomy (1,91 x 1) Preferowana w przypadku klastrów polecanych |
600x314 | 1200x628 |
Orientacja pionowa (4 x 5) | 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.
- Użyj przezroczystego tła, aby obraz był poprawnie wyświetlany w ustawieniach ciemnego i jasnego motywu.
Krok 2. Podaj dane klastra
Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) 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 produktowych odpowiada AppEngageShoppingClient
.
Te interfejsy API są dostępne do publikowania klastrów w kliencie:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingList
publishShoppingReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
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
.
Obiekt RecommendationCluster
może mieć te atrybuty:
Atrybut | Wymóg | Opis |
---|---|---|
Lista ShoppingEntity | Wymagany | Lista obiektów ShoppingEntity, które składają się na rekomendacje dla tego klastra rekomendacji. |
tytuł; | Wymagany | Tytuł klastra rekomendacji. Zalecany rozmiar tekstu: poniżej 25 znaków (zbyt długi tekst może zawierać wielokropki) |
Identyfikator URI działania | Opcjonalnie |
Precyzyjny link do strony w aplikacji partnera, na której użytkownicy mogą zobaczyć pełną listę rekomendacji. Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te najczęstsze pytania |
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Black Friday Deals") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Black Friday Deals") .build()) .build());
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:
- Wszystkie istniejące dane klastra rekomendacji zostaną usunięte.
- Dane z żądania są analizowane i przechowywane w nowych klastrach 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 obiektu 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.
publishShoppingCart
Ten interfejs API służy do publikowania obiektu ShoppingCartCluster
.
Kotlin
client.publishShoppingCart( PublishShoppingCartRequest.Builder() .setShoppingCart( ShoppingCart.Builder() ... .build()) .build())
Java
client.publishShoppingCart( new PublishShoppingCartRequest.Builder() .setShoppingCart( new ShoppingCart.Builder() ... .build()) .build())
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:
- Dotychczasowe dane aplikacji
ShoppingCart
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze koszyka.
W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.
publishShoppingList
Ten interfejs API służy do publikowania obiektu FoodShoppingList
.
Kotlin
client.publishFoodShoppingList( PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( FoodShoppingListEntity.Builder() ... .build()) .build())
Java
client.publishFoodShoppingList( new PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( new FoodShoppingListEntity.Builder() ... .build()) .build());
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:
- Dotychczasowe dane aplikacji
FoodShoppingList
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze listy zakupów.
W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.
publishShoppingReorderCluster
Ten interfejs API służy do publikowania obiektu ShoppingReorderCluster
.
Kotlin
client.publishShoppingReorderCluster( PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( ShoppingReorderCluster.Builder() ... .build()) .build())
Java
client.publishShoppingReorderCluster( new PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( new ShoppingReorderCluster.Builder() ... .build()) .build());
Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:
- Dotychczasowe dane aplikacji
ShoppingReorderCluster
od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze zmiany kolejności.
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.
deleteShoppingCartCluster
Ten interfejs API służy do usuwania zawartości klastra koszyka na zakupy.
Kotlin
client.deleteShoppingCartCluster()
Java
client.deleteShoppingCartCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastra koszyka. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.
deleteShoppingListCluster
Ten interfejs API służy do usuwania zawartości klastra listy zakupów.
Kotlin
client.deleteShoppingListCluster()
Java
client.deleteShoppingListCluster();
Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra listy zakupów. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.
deleteShoppingReorderCluster
Ten interfejs API służy do usuwania zawartości klastra zmiany kolejności zakupów.
Kotlin
client.deleteShoppingReorderCluster()
Java
client.deleteShoppingReorderCluster();
Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra zmiany kolejności w Zakupach Google. 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.
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(..) .build()) .addOnCompleteListener { task -> if (task.isSuccessful) { // do something } else { val exception = task.exception if (exception is AppEngageException) { @AppEngageErrorCode val errorCode = exception.errorCode if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } }
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(...) .build()) .addOnCompleteListener( task -> { if (task.isSuccessful()) { // do something } else { Exception exception = task.getException(); if (exception instanceof AppEngageException) { @AppEngageErrorCode int errorCode = ((AppEngageException) exception).getErrorCode(); if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } });
Błąd jest zwracany jako AppEngageException
, a 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.
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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast // is received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast // is received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is // received } fun registerBroadcastReceivers(context: Context){ var context = context context = context.applicationContext // Register Recommendation Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION)) // Register Featured Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_FEATURED)) // Register Shopping Cart Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART)) // Register Shopping List Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST)) // Register Reorder Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER)) }
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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is // received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is // received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART)); // Register Shopping List Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST)); // Register Reorder Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER)); }
- 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.shopping.PUBLISH_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
</receiver>
</application>
Usługa wysyła te zamiary:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Zalecamy uruchomienie wywołaniapublishRecommendationClusters
po otrzymaniu tej intencji.com.google.android.engage.action.PUBLISH_FEATURED
Zalecamy uruchamianie wywołaniapublishFeaturedCluster
po otrzymaniu tej intencji.com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART
Zalecamy uruchamianie wywołaniapublishShoppingCart
po otrzymaniu tej intencji.com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST
Zalecamy uruchamianie wywołaniapublishShoppingList
po otrzymaniu tej intencji.com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER
Zalecamy uruchamianie wywołaniapublishReorderCluster
po otrzymaniu tej intencji.
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ół odpowiada jak najszybciej.
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 przeprowadza weryfikację i weryfikację wewnętrzną, aby mieć pewność, że integracja działa zgodnie z oczekiwaniami. Jeśli potrzebne będą zmiany, Google skontaktuje się z Tobą, aby przekazać Ci niezbędne informacje.
- Gdy testy zostaną ukończone i nie będą wymagane żadne zmiany, Google skontaktuje się z Tobą, aby powiadomić Cię, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pakietu APK w Sklepie Play.
- Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, klastry Rekomendacja, Polecane i Koszyk mogą zostać opublikowane i widoczne dla użytkowników.