Engage SDK Food: instrukcje dotyczące integracji technicznej innych firm

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 kulinarne za pomocą pakietu SDK Engage (Workspace) do zapełnienia zarówno tej nowej powierzchni, jak i dotychczasowych platform Google.

Szczegóły integracji

Terminologia

Ta integracja obejmuje 5 typów klastrów: Rekomendacja, Polecane, Koszyk na jedzenie, Lista zakupów jedzenia oraz Zmiana kolejności.

  • Klastry rekomendacji wyświetlają spersonalizowane sugestie dotyczące jedzenia od poszczególnych partnerów deweloperów. Te rekomendacje mogą być dostosowane do użytkownika lub ogólne (np. „nowość w wyprzedaży”). Możesz w nich wyświetlać przepisy, sklepy, dania, artykuły spożywcze itd., kiedy uznasz to za stosowne.

    • Klaster rekomendacji może składać się z wersji ProductEntity, StoreEntity lub RecipeEntity, ale nie może być mieszanką różnych typów elementów.

  • Klaster Polecane prezentuje wybrany baner powitalny ProductEntity, StoreEntity lub RecipeEntity od wielu partnerów deweloperskich w jednym grupowaniu UI. U góry interfejsu użytkownika widoczny jest pojedynczy klaster cech o priorytecie wyższym niż klastry rekomendacji. Każdy deweloper może transmitować 1 element obsługiwanego typu w sekcji Polecane, a w grupie Polecane jest wiele elementów (potencjalnie różnych typów) od wielu deweloperów aplikacji.

  • Klaster Koszyk na żywność prezentuje zapowiedź koszyków na artykuły spożywcze wielu partnerów tworzących produkty w jednym, grupowaniu UI, co zachęca użytkowników do uzupełnienia koszyków do uzupełnienia. Mamy tylko jeden klaster koszyków na żywność.

    • Klaster koszyka na jedzenie musi pokazywać łączną liczbę produktów w koszyku. Może też zawierać zdjęcia X produktów w koszyku użytkownika.

  • Klaster Lista zakupów spożywczych to podgląd list zakupów spożywczych przygotowanych przez wielu deweloperów w ramach jednej grupy, co zachęca użytkowników do powrotu do odpowiedniej aplikacji, aby zaktualizować i uzupełnić listy. Mamy jeden klaster z listą zakupów spożywczych.

  • 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'
}

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 (ProductEntity, RecipeEntity lub StoreEntity)
Polecany klaster Maksymalnie 1 Maksymalnie 1 (ProductEntity, RecipeEntity lub StoreEntity)
Klaster koszyka na jedzenie Maksymalnie 1 Maksymalnie 1 ShoppingCartEntity
Klaster listy zakupów jedzenia Maksymalnie 1 Maksymalnie 1 ShoppingListEntity
Klaster do zmiany kolejności żywności Maksymalnie 1 Maksymalnie 1 ReorderEntity

Krok 1. Podaj dane encji

Pakiet SDK ma zdefiniowane różne elementy reprezentujące każdy typ elementu. W kategorii Żywność obsługujemy te podmioty:

  1. ProductEntity
  2. StoreEntity
  3. RecipeEntity
  4. FoodShoppingCart
  5. FoodShoppingList
  6. FoodReorderCluster

W tabelach poniżej znajdziesz dostępne atrybuty i wymagania dla poszczególnych typów.

ProductEntity

Obiekt ProductEntity reprezentuje pojedynczy produkt (np. produkt spożywczy, danie z restauracji lub promocję), który chcą opublikować partnerzy.

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 produkcie.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te 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 - aktualna Wymagane warunkowo

Aktualna cena produktu.

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ę 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 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

StoreEntity

Obiekt StoreEntity reprezentuje pojedynczy sklep, który partnerzy chcą opublikować, na przykład restaurację lub sklep spożywczy.

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 sklepie.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te 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 zawierające informacje o promocji, wydarzeniu lub nowościach w sklepie, 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)
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 w naszym standardowym systemie ocen.
Ocena – wartość maksymalna Wymagane warunkowo

Maksymalna wartość skali ocen.

Trzeba podać tę wartość, jeśli podano również bieżącą wartość oceny.

 Liczba >= 0,0
Ocena – obecna wartość Wymagane warunkowo

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

RecipeEntity

Obiekt RecipeEntity reprezentuje element przepisu, który partnerzy chcą opublikować.

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 przepisie.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Przeczytaj te 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 pieczenia/przygotowywania Opcjonalnie Czas gotowania przepisu.

Dowolny tekst

Zalecany rozmiar tekstu: poniżej 45 znaków (zbyt długi tekst może zawierać wielokropki)
Objaśnienie Opcjonalnie Objaśnienie zawierające 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 w naszym standardowym systemie ocen.
Ocena – wartość maksymalna Wymagane warunkowo

Maksymalna wartość skali ocen.

Trzeba podać tę wartość, jeśli podano również bieżącą wartość oceny.

 Liczba >= 0,0
Ocena – obecna wartość Wymagane warunkowo

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

FoodShoppingCart

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.

Jeśli na przykład w koszyku masz 3 pomarańcze i 1 jabłko, ta liczba powinna wynosić 4.

 Liczba całkowita >= 1
tytuł; Opcjonalnie

Tytuł koszyka (na przykład Twój koszyk).

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)
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
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

FoodShoppingList

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)

FoodReorderCluster

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

 300 × 300 1200x1200
Poziomy (1,91 x 1) 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 żywności odpowiada AppEngageFoodClient.

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 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 właściwości ProductEntity, StoreEntity i RecipeEntity Wymagany Lista encji, które składają się na rekomendacje dla tego klastra rekomendacji. Encje w pojedynczym klastrze muszą być tego samego typu.
tytuł; Wymagany

Tytuł klastra rekomendacji (na przykład 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)
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("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, 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.

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, w ramach jednej transakcji wykonywane są te działania:

  • Dotychczasowe dane aplikacji FoodShoppingCart 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.

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, 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.

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, w ramach jednej transakcji wykonywane są te działania:

  • Dotychczasowe dane aplikacji FoodReorderCluster 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.

deleteFoodShoppingCartCluster

Ten interfejs API służy do usuwania zawartości klastra koszyka na jedzenie.

Kotlin


client.deleteFoodShoppingCartCluster()

Java


client.deleteFoodShoppingCartCluster();

Po otrzymaniu żądania usługa usuwa istniejące dane z klastra koszyka na zakupy. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.

deleteFoodShoppingListCluster

Ten interfejs API służy do usuwania zawartości klastra listy zakupów spożywczych.

Kotlin


client.deleteFoodShoppingListCluster()

Java


client.deleteFoodShoppingListCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra listy zakupów spożywczych. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.

deleteReorderCluster

Ten interfejs API służy do usuwania zawartości FoodReorderCluster.

Kotlin


client.deleteReorderCluster()

Java


client.deleteReorderCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra zmiany kolejności. 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 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 zadeklaruj implementację za pomocą tagu <receiver> w pliku AndroidManifest.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.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 będzie wysyłać te zamiary:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Zalecamy uruchomienie wywołania publishRecommendationClusters przy odbieraniu tej intencji.
  • com.google.android.engage.action.PUBLISH_FEATURED Zalecamy uruchomienie wywołania publishFeaturedCluster po otrzymaniu tej intencji.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART Zalecamy uruchomienie wywołania publishFoodShoppingCart po otrzymaniu tej intencji.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST Zalecamy uruchomienie wywołania publishFoodShoppingList po otrzymaniu tej intencji.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER Gdy odbierasz tę intencję, zalecamy uruchomienie wywołania publishReorderCluster.

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, Koszyk, Lista zakupów oraz Zmień kolejność zostaną opublikowane i będą widoczne dla użytkowników.