Google tworzy platformę na urządzeniu, która porządkuje aplikacje użytkowników według branż i zapewnia nowe, immersyjne środowisko do spersonalizowanego przeglądania i odkrywania treści z aplikacji. Tryb pełnoekranowy daje deweloperom możliwość zaprezentowania swoich najlepszych szczegółowych treści na specjalnym kanale poza aplikacją.
Ten przewodnik zawiera instrukcje dla deweloperów, którzy chcą zintegrować treści dotyczące jedzenia, korzystając z pakietu Engage SDK, aby wypełniać nowe obszary i istniejące platformy Google.
Szczegóły integracji
Terminologia
Ta integracja obejmuje 5 typów klastrów: Rekomendacja, Polecane, Koszyk na zakupy żywności, Lista zakupów spożywczych i Zmień kolejność.
Klastry rekomendacji pokazują spersonalizowane sugestie dotyczące żywności przygotowane przez konkretnego partnera ds. deweloperów. Rekomendacje te mogą być dostosowane do użytkownika lub uogólnione (np. „nowe produkty z wyprzedaży”). Możesz w nich wyświetlać przepisy, sklepy, dania, artykuły spożywcze i inne treści według własnego uznania.
- Klaster rekomendacji może składać się z
ProductEntity
,StoreEntity
lubRecipeEntity
stron, ale nie może zawierać różnych typów elementów.
Rysunek : „ProductEntity”, „StoreEntity” i „RecipeEntity”. (*Interfejs tylko do celów poglądowych) - Klaster rekomendacji może składać się z
Klaster Polecane prezentuje bohatera
ProductEntity
,StoreEntity
lubRecipeEntity
wybranego przez wielu deweloperów deweloperów w jednej grupie UI. U góry interfejsu użytkownika znajduje się pojedynczy klaster cech, który ma priorytet nad wszystkimi klastrami rekomendacji. Każdy partner deweloperów może transmitować 1 element obsługiwanego typu w sekcji Polecane, zawierający wiele elementów (potencjalnie różnych typów) od różnych deweloperów aplikacji w klastrze Polecane.Rysunek : polecany klaster z obiektem „RecipeEntity”. (*Interfejs wyłącznie do celów poglądowych) Klaster Koszyki na zakupy z żywnością pokazuje wersje koszyków na zakupy od różnych deweloperów w jednej grupie UI, co zachęca użytkowników do uzupełnienia wyjątkowych koszyków. Jeden klaster koszyka na zakupy z żywnością.
Klaster koszyka na zakupy żywności musi pokazywać łączną liczbę produktów w koszyku i może również zawierać zdjęcia X produktów w koszyku użytkownika.
Ilustracja: Grupa koszyków na zakupy żywności pochodzi od jednego partnera. (*Interfejs tylko do celów poglądowych)
Klaster Food Shopping List (Listy zakupów spożywczych) wyświetla podgląd list zakupów spożywczych utworzonych przez wielu deweloperów w jednym grupowaniu interfejsu, zachęcając użytkowników do powrotu do odpowiedniej aplikacji w celu zaktualizowania i uzupełnienia list. Jeden zbiór artykułów spożywczych podaje listy zakupów.
Rysunek: 1 partner dostarcza listę zakupów żywnościowych. (*Interfejs tylko do celów ilustracyjnych) Klaster Zmień kolejność pokazuje wcześniejsze zamówienia od kilku partnerów deweloperów w jednej grupie UI, co informuje użytkowników o zmianie kolejności. Jest 1 klaster Zmień kolejność.
Zmień kolejność klastrów musi wyświetlać łączną liczbę elementów w poprzedniej kolejności użytkownika i musi zawierać też jeden z tych elementów:
- Obrazy X produktów w poprzedniej kolejności użytkownika.
- Etykiety X elementów w poprzedniej kolejności użytkownika.
Rysunek: klaster Żywność od jednego partnera. (*Interfejs tylko do celów ilustracyjnych)
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ą następującym limitom dotyczącym różnych typów klastrów:
Typ klastra | Limity klastra | Maksymalne limity encji w klastrze |
---|---|---|
Klastry rekomendacji | Maksymalnie 5 | Maksymalnie 25 (ProductEntity , RecipeEntity lub StoreEntity ) |
Polecany klaster | Maksymalnie 1 | Maksymalnie 1 (ProductEntity , RecipeEntity lub StoreEntity ) |
Klaster koszyka na zakupy spożywcze | Maksymalnie 1 | Maksymalnie 1 ShoppingCartEntity |
Klaster listy zakupów spożywczych | Maksymalnie 1 | Maksymalnie 1 ShoppingListEntity |
Zmiana kolejności jedzenia | Maksymalnie 1 | Maksymalnie 1 ReorderEntity |
Krok 1. Podaj dane encji
Pakiet SDK ma zdefiniowane różne jednostki reprezentujące każdy typ elementu. W przypadku kategorii Jedzenie obsługujemy te podmioty:
ProductEntity
StoreEntity
RecipeEntity
FoodShoppingCart
FoodShoppingList
FoodReorderCluster
Poniższe tabele przedstawiają dostępne atrybuty i wymagania dla każdego typu.
ProductEntity
Obiekt ProductEntity
reprezentuje konkretny produkt (np. produkt spożywczy, danie z restauracji lub promocję), który partnerzy deweloperów chcą opublikować.
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-product-entity.png?hl=pl)
ProductEntity
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Plakat | Wymagany | Musisz przesłać co najmniej 1 obraz. | Wskazówki znajdziesz w specyfikacjach obrazów. |
Identyfikator URI działania | Wymagany |
Precyzyjny link do strony w aplikacji, która wyświetla szczegółowe informacje o produkcie. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Identyfikator URI |
tytuł; | Opcjonalnie | Nazwa produktu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 90 znaków (zbyt długi tekst może zawierać wielokropki) |
Cena - bieżąca | Wymagane warunkowo | Aktualna cena produktu. Jeśli podano przekreśloną cenę, ta wartość jest wymagana. |
Dowolny tekst |
Cena – przekreślenie | Opcjonalnie | Pierwotna cena elementu, przekreślona w interfejsie. | Dowolny tekst |
Objaśnienie | Opcjonalnie | Objaśnienie, które powinno zawierać promocję, wydarzenie lub aktualizację produktu, 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 | Drobny tekst objaśnienia. | 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 ramach naszego standardowego systemu ocen w postaci gwiazdek. | |||
Ocena – wartość maksymalna | Wymagane | Maksymalna wartość skali ocen. Atrybut ten jest wymagany, jeśli podano również bieżącą wartość oceny. |
Liczba >= 0.0 |
Ocena – bieżąca wartość | Wymagane | Bieżąca wartość oceny elementu. Atrybut ten jest wymagany, jeśli podano także maksymalną wartość oceny. |
Liczba >= 0.0 |
Ocena – liczba | Opcjonalnie | Liczba ocen elementu. | Ciąg znaków |
DisplayTimeWindow (opcjonalnie) – ustaw przedział czasu, w którym treści mają być wyświetlane na platformie | |||
Sygnatura czasowa rozpoczęcia | Opcjonalnie |
Sygnatura czasowa epoki, po której treści mają być wyświetlane na powierzchni. Jeśli zasada nie jest skonfigurowana, treści mogą być wyświetlane na platformie. |
Sygnatura czasowa epoki w milisekundach |
Sygnatura czasowa zakończenia | Opcjonalnie |
Sygnatura czasowa epoki, po której treść nie jest już wyświetlana na powierzchni. Jeśli zasada nie jest skonfigurowana, treści mogą być wyświetlane na platformie. |
Sygnatura czasowa epoki w milisekundach |
StoreEntity
Obiekt StoreEntity
reprezentuje konkretny sklep, który partnerzy deweloperów chcą opublikować, np. restaurację lub sklep spożywczy.
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-store-entity.png?hl=pl)
StoreEntity
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Plakat | Wymagany | Musisz przesłać co najmniej 1 obraz. | Wskazówki znajdziesz w specyfikacjach obrazów. |
Identyfikator URI działania | Wymagany | Precyzyjny link do strony w aplikacji, która wyświetla szczegółowe informacje o sklepie. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Identyfikator URI |
tytuł; | Opcjonalnie | Nazwa sklepu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Lokalizacja | Opcjonalnie | Lokalizacja sklepu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Objaśnienie | Opcjonalnie | Objaśnienie, które powinno zawierać promocję, wydarzenie lub aktualizację sklepu, 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 | Drobny tekst objaśnienia. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Opis | Opcjonalnie | Opis sklepu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 90 znaków (zbyt długi tekst może zawierać wielokropki) |
Uwaga: wszystkie oceny są wyświetlane według naszego standardowego systemu ocen. | |||
Ocena – wartość maksymalna | Wymagane warunkowo | Maksymalna wartość skali ocen. Atrybut ten jest wymagany, jeśli podano również bieżącą wartość oceny. |
Liczba >= 0.0 |
Ocena – bieżąca wartość | Wymagane warunkowo | Bieżąca wartość oceny elementu. Atrybut ten jest wymagany, jeśli podano także maksymalną wartość oceny. |
Liczba >= 0.0 |
Ocena – liczba | Opcjonalnie | Liczba ocen elementu. | Ciąg znaków |
RecipeEntity
Obiekt RecipeEntity
reprezentuje element przepisu, który partnerzy programistów chcą opublikować.
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-recipe-entity.png?hl=pl)
RecipeEntity
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Plakat | Wymagany | Musisz przesłać co najmniej 1 obraz. | Wskazówki znajdziesz w specyfikacjach obrazów. |
Identyfikator URI działania | Wymagany | Precyzyjny link do strony w aplikacji, która wyświetla szczegółowe informacje o przepisie. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Identyfikator URI |
tytuł; | Opcjonalnie | Nazwa przepisu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Autor | Opcjonalnie | Autor przepisu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Czas przyrządzania | Opcjonalnie | Czas gotowania według przepisu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Objaśnienie | Opcjonalnie | Objaśnienie, które powinno zawierać promocję, wydarzenie lub aktualizację przepisu, jeśli są dostępne. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Kategoria | Opcjonalnie | Kategoria przepisu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki) |
Opis | Opcjonalnie | Opis przepisu. | Dowolny tekst Zalecany rozmiar tekstu: poniżej 90 znaków (zbyt długi tekst może zawierać wielokropki) |
Uwaga: wszystkie oceny są wyświetlane według naszego standardowego systemu ocen. | |||
Ocena – wartość maksymalna | Wymagane warunkowo | Maksymalna wartość skali ocen. Atrybut ten jest wymagany, jeśli podano również bieżącą wartość oceny. |
Liczba >= 0.0 |
Ocena – bieżąca wartość | Wymagane warunkowo | Bieżąca wartość oceny elementu. Atrybut ten jest wymagany, jeśli podano także maksymalną wartość oceny. |
Liczba >= 0.0 |
Ocena – liczba | Opcjonalnie | Liczba ocen elementu. | Ciąg znaków |
FoodShoppingCart
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-shopping-cart-attributes.png?hl=pl)
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link do koszyka w aplikacji partnera. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Identyfikator URI |
Liczba elementów | Wymagany | Liczba produktów (a nie tylko liczba produktów) w koszyku. Na przykład: jeśli w koszyku są 3 pomarańcze i 1 jabłko, ta liczba powinna wynosić 4. |
Liczba całkowita >= 1 |
tytuł; | Opcjonalnie | Tytuł koszyka (np. Twój koszyk). Jeśli deweloper nie podał tytułu, domyślną wartością będzie Twój koszyk. |
Dowolny tekst Zalecany rozmiar tekstu: poniżej 25 znaków (zbyt długi tekst może zawierać wielokropki) |
Tekst działania | Opcjonalnie |
Tekst wezwania do działania na przycisku na stronie koszyka (np. Twoja torba na zakupy). Jeśli deweloper nie poda tekstu działania, domyślną opcją będzie Wyświetl koszyk. Ten atrybut jest obsługiwany od wersji 1.1.0. |
Ciąg znaków |
Obrazy koszyka | Opcjonalnie | Zdjęcia każdego produktu w koszyku. Można przesłać maksymalnie 10 obrazów w kolejności według priorytetu. Rzeczywista liczba wyświetlanych obrazów zależy od formatu urządzenia. |
Wskazówki znajdziesz w specyfikacjach 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 etykiet dowolnego tekstu Zalecany rozmiar tekstu: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
DisplayTimeWindow (opcjonalnie) – ustaw przedział czasu, w którym treści mają być wyświetlane na platformie | |||
Sygnatura czasowa rozpoczęcia | Opcjonalnie |
Sygnatura czasowa epoki, po której treści mają być wyświetlane na powierzchni. Jeśli zasada nie jest skonfigurowana, treści mogą być wyświetlane na platformie. |
Sygnatura czasowa epoki w milisekundach |
Sygnatura czasowa zakończenia | Opcjonalnie |
Sygnatura czasowa epoki, po której treść nie jest już wyświetlana na powierzchni. Jeśli zasada nie jest skonfigurowana, treści mogą być wyświetlane na platformie. |
Sygnatura czasowa epoki w milisekundach |
FoodShoppingList
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-shopping-list.png?hl=pl)
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link do listy zakupów w aplikacji partnera. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na 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ą będzie 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. Musisz podać co najmniej 1 etykietę i można podać maksymalnie 10 etykiet w kolejności według priorytetu. Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia. |
Lista etykiet dowolnego tekstu Zalecany rozmiar tekstu: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
FoodReorderCluster
![](https://cdn.statically.io/img/developer.android.com/static/images/guide/playcore/engage/food-reorder-cluster.png?hl=pl)
Atrybut | Wymóg | Opis | Format |
---|---|---|---|
Identyfikator URI działania | Wymagany |
Precyzyjny link do zmiany kolejności w aplikacji partnera. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Identyfikator URI |
Tekst działania | Opcjonalnie |
Tekst wezwania do działania na przycisku na karcie Zmień kolejność (np. Zamów ponownie). Jeśli deweloper nie poda tekstu działania, domyślną opcją będzie 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ł produktu, którego dotyczy zmiana. | 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 plakatów) |
Lista etykiet produktów w poprzednim zamówieniu. Można podać maksymalnie 10 etykiet w kolejności według priorytetu. Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia. |
Lista dowolnego tekstu Zalecany rozmiar tekstu na etykietę: poniżej 20 znaków (zbyt długi tekst może zawierać wielokropki) |
Plakat | Opcjonalnie (Jeśli nie podano tej wartości, należy podać etykiety produktów) |
Zdjęcia produktów z poprzedniego zamówienia. Można przesłać maksymalnie 10 obrazów w kolejności według priorytetu. Rzeczywista liczba wyświetlanych obrazów zależy od formatu urządzenia. |
Wskazówki znajdziesz w specyfikacjach 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 |
300x300 | 1200x1200 |
Poziomy (1,91 x 1) | 600x314 | 1200x628 |
Orientacja pionowa (4 x 5) | 480 × 600 | 960x1200 |
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.
- Użyj przezroczystego tła, by obraz wyświetlał się prawidłowo w ustawieniach ciemnego i jasnego motywu.
Krok 2. Podaj dane klastra
Zaleca się, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą narzędzia WorkManager) i zaplanowane w regularnych odstępach czasu lub w określonych zdarzeniach (na przykład za każdym razem, gdy użytkownik otworzy aplikację lub gdy użytkownik właśnie dodał coś do koszyka).
Organizacja AppEngageFoodClient
jest odpowiedzialna za publikowanie klastrów żywności.
Istnieją następujące interfejsy API do publikowania klastrów w kliencie:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishFoodShoppingCart
publishFoodShoppingList
publishReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteFoodShoppingCartCluster
deleteFoodShoppingListCluster
deleteReorderCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
Ten interfejs API służy do sprawdzania, czy usługa jest dostępna do integracji i czy treści mogą być wyświetlane 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 obiektów RecommendationCluster
na liście.
Obiekt RecommendationCluster
może mieć te atrybuty:
Atrybut | Wymóg | Opis |
---|---|---|
Lista ProductEntity, StoreEntity lub RecipeEntity | Wymagany | Lista encji tworzących rekomendacje dla tego klastra rekomendacji. Encje w jednym klastrze muszą być tego samego typu. |
tytuł; | Wymagany | Tytuł klastra rekomendacji (np. Duże oszczędności w menu na Święto Dziękczynienia). Zalecany rozmiar tekstu: poniżej 25 znaków (zbyt długi tekst może zawierać wielokropki) |
Podtytuł | Opcjonalnie | Podtytuł klastra rekomendacji. |
Identyfikator URI działania | Opcjonalnie |
Precyzyjny link do strony w aplikacji partnerskiej, na której użytkownicy mogą zobaczyć pełną listę rekomendacji. Uwaga: na potrzeby atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania |
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build());
Gdy usługa otrzyma żądanie, wykonywane są te działania w ramach jednej transakcji:
- Wszystkie dotychczasowe dane klastra rekomendacji zostaną usunięte.
- Dane z żądania są analizowane i przechowywane w nowych klastrach rekomendacji.
W przypadku błędu żądanie w całości jest odrzucane, a obecny 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, wykonywane są te działania w ramach jednej transakcji:
- Dotychczasowe dane
FeaturedCluster
pochodzące od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym polecanym klastrze.
W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
publishFoodShoppingCart
Ten interfejs API służy do publikowania obiektu FoodShoppingCart
.
Kotlin
client.publishFoodShoppingCart( PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( FoodShoppingCart.Builder() ... .build()) .build())
Java
client.publishFoodShoppingCart( new PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( new FoodShoppingCart.Builder() ... .build()) .build());
Gdy usługa otrzyma żądanie, wykonywane są te działania w ramach jednej transakcji:
- Dotychczasowe dane
FoodShoppingCart
pochodzące od partnera dewelopera zostaną usunięte. - Dane z żądania są przeanalizowane i przechowywane w zaktualizowanym klastrze koszyka na zakupy.
W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
publishFoodShoppingList
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, wykonywane są te działania w ramach jednej transakcji:
- Dotychczasowe dane
FoodShoppingList
pochodzące od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze list zakupów.
W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
publishReorderCluster
Ten interfejs API służy do publikowania obiektu FoodReorderCluster
.
Kotlin
client.publishReorderCluster( PublishReorderClusterRequest.Builder() .setReorderCluster( FoodReorderCluster.Builder() ... .build()) .build())
Java
client.publishReorderCluster( new PublishReorderClusterRequest.Builder() .setReorderCluster( new FoodReorderCluster.Builder() ... .build()) .build());
Gdy usługa otrzyma żądanie, wykonywane są te działania w ramach jednej transakcji:
- Dotychczasowe dane
FoodReorderCluster
pochodzące od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze Zmień kolejność.
W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
publishUserAccountManagementRequest
Ten interfejs API służy do publikowania karty logowania . Logowanie kieruje użytkowników na stronę logowania, aby aplikacja mogła publikować treści (lub udostępniać treści bardziej spersonalizowane)
Te metadane są częścią karty logowania:
Atrybut | Wymóg | Opis |
---|---|---|
Identyfikator URI działania | Wymagane | Precyzyjny link do działania (np. przejście na stronę logowania w aplikacji) |
Obraz | Opcjonalnie – jeśli nie podano, musisz 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ć zdjęcie | Tytuł na karcie |
Tekst działania | Opcjonalnie | Tekst widoczny w wezwaniu do działania (np. „Zaloguj się”) |
Podtytuł | Opcjonalnie | Opcjonalny tytuł 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, wykonywane są te działania w ramach jednej transakcji:
- Dotychczasowe dane
UserAccountManagementCluster
pochodzące od partnera dewelopera zostaną usunięte. - Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze UserAccountManagementCluster.
W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
updatePublishStatus
Jeśli z jakiegokolwiek wewnętrznego powodu biznesowego żaden z klastrów nie został opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikowania przy użyciu interfejsu API updatePublishStatus. To ważne, ponieważ :
- Podanie stanu we wszystkich scenariuszach, nawet po opublikowaniu treści (STATUS == PUBLISHED), ma kluczowe znaczenie przy wypełnianiu paneli, które używają tego stanu wprost do przekazywania danych o stanie i innych wskaźnikach związanych z integracją.
- Jeśli nie zostaną opublikowane żadne treści, ale stan integracji nie jest nieprawidłowy (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów w panelach stanu aplikacji. Potwierdza ono, że treść nie została opublikowana z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
- Pomaga deweloperom 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, aby mógł on wyświetlić zawartość aplikacji lub rozwiązać problem.
Lista kodów stanu odpowiednich 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, Google zaleca opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_PUBLISHED_REQUIRES_SIGN_IN
Kotlin
client.updatePublishStatus( PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build())
Java
client.updatePublishStatus( new PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build());
deleteRecommendationClusters
Ten interfejs API służy do usuwania zawartości klastrów rekomendacji.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.
deleteFeaturedCluster
Ten interfejs API służy do usuwania 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 zostaje odrzucone, a obecny stan zostaje zachowany.
deleteFoodShoppingCartCluster
Ten interfejs API służy do usuwania zawartości klastra koszyków na zakupy spożywcze.
Kotlin
client.deleteFoodShoppingCartCluster()
Java
client.deleteFoodShoppingCartCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastra koszyków na zakupy spożywcze. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.
deleteFoodShoppingListCluster
Ten interfejs API służy do usuwania zawartości klastra listy zakupów żywności.
Kotlin
client.deleteFoodShoppingListCluster()
Java
client.deleteFoodShoppingListCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastra listy zakupów żywności. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.
deleteReorderCluster
Ten interfejs API służy do usuwania zawartości klastra FoodReorderCluster.
Kotlin
client.deleteReorderCluster()
Java
client.deleteReorderCluster();
Po otrzymaniu żądania usługa usuwa istniejące dane z klastra Zmień kolejność. W przypadku błędu całe żądanie zostaje odrzucone, 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 zarządzania kontami użytkowników. W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan zostaje zachowany.
deleteClusters
Ten interfejs API służy do usuwania zawartości klastra określonego typu.
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());
Po otrzymaniu żądania usługa usuwa istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienty mogą przesyłać 1 typ klastra lub wiele z nich. W przypadku błędu żądanie w całości jest odrzucane, a obecny stan zostaje zachowany.
Obsługa błędów
Zdecydowanie zalecamy wsłuchiwanie się w wyniki zadania z interfejsów API do publikowania, aby móc podjąć dalsze działania w celu odzyskania i ponownego przesłania udanego zadania.
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(...)
.build())
.addOnCompleteListener(
task -> {
if (task.isSuccessful()) {
// do something
} else {
Exception exception = task.getException();
if (exception instanceof AppEngageException) {
@AppEngageErrorCode
int errorCode = ((AppEngageException) exception).getErrorCode();
if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
// do something
}
}
}
});
Błąd jest zwracany jako AppEngageException
z przyczyną podaną w kodzie błędu.
Kod błędu | 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 wywołania (np. jest jawnie wyłączona). |
SERVICE_CALL_EXECUTION_FAILURE |
Nie udało się wykonać zadania z powodu problemów z wątkami. W takim przypadku można spróbować jeszcze raz. |
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 |
Dzwonienie do zespołu pomocy jest wykonywane zbyt często. |
Krok 3. Obsługa intencji transmisji
Oprócz wykonywania wywołań interfejsu Publishing Content API za pomocą zadania musisz też skonfigurować BroadcastReceiver
, aby otrzymywać żądanie publikacji treści.
Celem intencji transmisji jest głównie ponowna aktywacja aplikacji i wymuszenie synchronizacji danych. Intencje związane z transmisją nie są przeznaczone do wysyłania zbyt często. Jest wywoływane tylko wtedy, gdy usługa Google dla Agencji ustali, że treść może być nieaktualna (np. sprzed tygodnia). Dzięki temu użytkownicy będą mieli większą pewność, że będą mieli dostęp do nowych treści, nawet jeśli aplikacja nie była uruchamiana od dłuższego czasu.
BroadcastReceiver
trzeba skonfigurować na 2 sposoby:
- Dynamicznie zarejestruj wystąpienie klasy
BroadcastReceiver
za pomocąContext.registerReceiver()
. Umożliwia to komunikację z aplikacji, które wciąż są 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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received
// Trigger shopping list cluster publish when PUBLISH_FOOD_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.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));
// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));
// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));
}
- Statycznie deklaruj implementację z tagiem
<receiver>
w plikuAndroidManifest.xml
. Dzięki temu aplikacja może odbierać intencje transmisji, gdy nie jest uruchomiona, i może publikować treści.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
</receiver>
</application>
Usługa wyśle te zamiary:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Po otrzymaniu tej intencji zalecamy uruchomienie wywołaniapublishRecommendationClusters
.com.google.android.engage.action.PUBLISH_FEATURED
Po otrzymaniu tej intencji zalecamy uruchomienie wywołaniapublishFeaturedCluster
.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART
Po otrzymaniu tej intencji zalecamy uruchomienie wywołaniapublishFoodShoppingCart
.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST
Po otrzymaniu tej intencji zalecamy uruchomienie wywołaniapublishFoodShoppingList
.com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER
Po otrzymaniu tej intencji zalecamy uruchomienie wywołaniapublishReorderCluster
.
Proces integracji
Szczegółowy przewodnik dotyczący weryfikacji integracji po jej zakończeniu znajdziesz w artykule Przepływ pracy związany z integracją dla programistów.
Najczęstsze pytania
Odpowiedzi na najczęstsze pytania znajdziesz w odpowiedziach na najczęstsze pytania o pakiet SDK dla Agencji.
Kontakt
Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engagement-developers@google.com. Nasz zespół odpowie tak szybko, jak to możliwe.
Dalsze kroki
Po zakończeniu integracji należy wykonać następujące czynności:
- Wyślij e-maila na adres Engage-developers@google.com i załącz zintegrowany plik APK, który jest gotowy do testowania przez Google.
- Google przeprowadzi weryfikację i wewnętrznie sprawdzi, czy integracja działa zgodnie z oczekiwaniami. Jeśli zajdzie potrzeba zmian, Google skontaktuje się z Tobą, aby przekazać wszystkie niezbędne informacje.
- Gdy testy zostaną zakończone i nie będą konieczne żadne zmiany, Google skontaktuje się z Tobą, aby powiadomić Cię, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Sklepie Play.
- Gdy Google potwierdzi, że zaktualizowany pakiet APK został opublikowany w Sklepie Play, Twoje klastry Rekomendacja, Polecane, Koszyk, Lista zakupów i Zmień kolejność zostaną opublikowane i będą widoczne dla użytkowników.