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

Google tworzy interfejs na urządzeniu, który pozwala użytkownikom porządkować aplikacje według branży i zapewnia nowe wciągające wrażenia podczas przeglądania i odtwarzania spersonalizowanych treści. Tryb pełnoekranowy daje partnerom deweloperom możliwość zaprezentowania swoich najlepszych treści w ramach dedykowanego kanału poza aplikacją.

Ten przewodnik zawiera instrukcje dla partnerów deweloperów dotyczące integracji treści dotyczących jedzenia za pomocą pakietu Engage SDK, aby wypełnić nową powierzchnię reklamową i dotychczasowe powierzchnie Google.

Szczegóły integracji

Terminologia

Ta integracja obejmuje 5 typów klastrów: Recommendation (Rekomendacje), Featured (Polecane), Food Shopping Cart (Koszyk z produktami spożywczymi), Food Shopping List (Lista zakupów z produktami spożywczymi) i Reorder (Ponowne zamawianie).

  • Grupy rekomendacji zawierają spersonalizowane sugestie dotyczące jedzenia od konkretnego partnera deweloperskiego. Te rekomendacje mogą być spersonalizowane dla danego użytkownika lub ogólne (np. nowości w sprzedaży). Używaj ich do wyświetlania przepisów, sklepów, potraw, produktów spożywczych itp. w zależnej od siebie sytuacji.

    • Klastry rekomendacji mogą składać się z kart produktów ProductEntity, StoreEntity lub RecipeEntity, ale nie z różnych typów elementów.
    Ilustracja : typy „ProductEntity”, „StoreEntity” i „RecipeEntity”. (*UI tylko w celu ilustracji)
  • Klaster Polecane zawiera zbiór elementów od wielu partnerów programistów w jednym układzie interfejsu. Będzie jeden wyróżniony klaster, który będzie wyświetlany u góry interfejsu w priorytetowym miejscu nad wszystkimi innymi klastrami rekomendacji. Każdy partner deweloper może przesyłać do 10 elementów w klastrze Polecane.

    Ilustracja : wyróżniony klaster z elementem „RecipeEntity”. (*Interfejs użytkownika tylko do celów poglądowych)
  • Klaster Koszyk na zakupy spożywcze zawiera w jednym układzie elementów interfejsu przegląd różnych koszyków na zakupy spożywcze pochodzących od wielu partnerów deweloperów, a także zachętę do sfinalizowania otwartych koszyków. Występuje jeden klaster koszyka zakupowego dotyczący produktów spożywczych.

    • Grupa produktów spożywczych w koszyku musi zawierać łączną liczbę produktów w koszyku, a także obrazy X produktów w koszyku użytkownika.

      Rysunek: klaster koszyka zakupów produktów spożywczych od jednego partnera. (*UI for illustrative purposes only)
  • Klaster Lista zakupów zawiera w jednym układzie elementów interfejsu przegląd list zakupów od wielu partnerów deweloperów, a także prośbę o powrót do odpowiedniej aplikacji w celu zaktualizowania i uzupełnienia list. Występuje jeden klaster dotyczący listy zakupów spożywczych.

    Rysunek: klaster listy zakupów spożywczych od jednego partnera. (*UI for illustrative purposes only)
  • Klaster Zmień kolejność zawiera podgląd poprzednich zamówień od wielu partnerów deweloperów w jednym układzie interfejsu, aby zachęcić użytkowników do zmiany kolejności. Jest 1 klaster z funkcją porządkowania.

    • Grupa ponownego zamówienia musi zawierać łączną liczbę produktów z poprzedniego zamówienia użytkownika. Musi też zawierać co najmniej jedną z tych informacji:

      • Obrazy X elementów z poprzedniego zamówienia użytkownika.
      • Etykiety X elementów w poprzednim zamówieniu użytkownika.
    Ilustracja: klaster „Zamów ponownie” dotyczący jedzenia od jednego partnera. (*UI for illustrative purposes only)

Przygotowanie

Minimalny poziom interfejsu API: 19

Dodaj bibliotekę com.google.android.engage:engage-core do aplikacji:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Podsumowanie

Projekt jest oparty na implementacji usługi powiązanej.

Dane, które klient może publikować, podlegają tym ograniczeniom w przypadku różnych typów klastrów:

Typ klastra Limity klastra Maksymalne limity elementów w klastrze
Klastry rekomendacji Maksymalnie 5 Maksymalnie 25 (ProductEntity, RecipeEntity lub StoreEntity)
Polecany klaster Maksymalnie 1 Maksymalnie 10 (ProductEntity, RecipeEntity lub StoreEntity)
Grupa zakupów spożywczych Maksymalnie 1 Maksymalnie 1 ShoppingCartEntity
Grupa tematyczna lista zakupów z pokarmem Maksymalnie 1 Maksymalnie 1 ShoppingListEntity
Grupa ponownego zamawiania jedzenia Maksymalnie 1 Maksymalnie 1 ReorderEntity

Krok 1. Podaj dane o entytecie

Pakiet SDK definiuje różne elementy reprezentujące poszczególne typy elementów. W przypadku kategorii Żywność obsługujemy te typy jednostek:

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

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

ProductEntity

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

Ilustracja : atrybuty ProductEntity

Atrybut Wymaganie Opis Format
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI działania Wymagany

Link do strony w aplikacji, na której znajdują się szczegółowe informacje o produkcie.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI
Tytuł Opcjonalny Nazwa produktu.

Tekst otwarty

Zalecana długość tekstu: mniej niż 90 znaków (za długi tekst może być wyświetlany z wielokropem)

Cena – bieżąca Wymagane warunkowo

Obecna cena produktu.

Musi być podana, jeśli podano cenę z przekreśleniem.

Tekst otwarty
Cena – przekreślenie Opcjonalny Pierwotna cena elementu, która jest przekreślona w interfejsie. Tekst otwarty
Objaśnienie Opcjonalny Wskazówka dotycząca promocji, wydarzenia lub aktualizacji produktu (jeśli są dostępne).

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Drobny druk objaśnienia Opcjonalny Drobny druk objaśnienia.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Ocena (opcjonalnie) – uwaga: wszystkie oceny są wyświetlane w standardowym systemie ocen za pomocą gwiazdek.
Ocena – wartość maksymalna Opcjonalny

Maksymalna wartość skali oceny.

Musi być podana, jeśli podana jest też aktualna wartość oceny.

Liczba >= 0,0
Rating - Current value Opcjonalny

Bieżąca wartość skali ocen.

Musi być podana, jeśli podana jest też maksymalna wartość oceny.

Liczba >= 0,0
Rating - Count (Liczba ocen) Opcjonalny

Liczba ocen produktu.

Uwaga: podaj to pole, jeśli Twoja aplikacja kontroluje sposób wyświetlania liczby użytkownikom. Użyj zwięzłego ciągu znaków. Jeśli np. liczba wynosi 1 000 000, rozważ użycie skrótu, np. 1 mln, aby liczba nie została obcięta w mniejszych rozmiarach wyświetlania.

Ciąg znaków
Rating - Count Value Opcjonalny

Liczba ocen produktu.

Uwaga: wypełnij to pole, jeśli nie obsługujesz samodzielnie logiki wyświetlania skrótu. Jeśli występują zarówno właściwości Liczba, jak i Wartość liczby, użytkownikom wyświetlana jest liczba.

Długie
DisplayTimeWindow (opcjonalnie) – ustaw przedział czasu, w którym treści mają być wyświetlane na urządzeniu
Sygnatura czasowa rozpoczęcia Opcjonalny

sygnatura czasowa ery, po której treści powinny być wyświetlane na danej powierzchni;

Jeśli nie jest ustawione, treści mogą być wyświetlane na platformie.

Sygnatura czasowa epoki w milisekundach
Sygnatura czasowa zakończenia Opcjonalny

Znak czasu epoki, po którym treści nie są już wyświetlane na powierzchni.

Jeśli nie skonfigurujesz tej zasady, treści mogą być wyświetlane na powierzchni.

Sygnatura czasowa epoki w milisekundach

StoreEntity

Obiekt StoreEntity reprezentuje pojedynczy sklep, który partnerzy deweloperzy chcą opublikować, np. restaurację lub sklep spożywczy.

Ilustracja : atrybuty StoreEntity

Atrybut Wymaganie Opis Format
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI działania Wymagany

Precyzyjny link do strony w aplikacji, na której znajdują się szczegóły dotyczące sklepu.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI
Tytuł Opcjonalny Nazwa sklepu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Lokalizacja Opcjonalny Lokalizacja sklepu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Objaśnienie Opcjonalny Ramka z informacjami o promocji, wydarzeniu lub aktualizacji sklepu (jeśli jest dostępna).

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Drobny druk objaśnienia Opcjonalny Drobny druk objaśnienia.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Opis Opcjonalny Opis sklepu.

Tekst otwarty

Zalecana długość tekstu: mniej niż 90 znaków (za długi tekst może być wyświetlany z wielokropem)

Kategoria Opcjonalny

Kategoria sklepu w kontekście miejsc serwujących jedzenie może być związana z kuchnią, np. „francuska”, „amerykańska”, „ramen”, „wykwintna”.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Uwaga: wszystkie oceny są wyświetlane za pomocą naszego standardowego systemu oceny za pomocą gwiazdek.
Ocena – wartość maksymalna Opcjonalny

Maksymalna wartość skali oceny.

Musi być podana, jeśli podana jest też aktualna wartość oceny.

Liczba >= 0,0
Rating - Current value Opcjonalny

Bieżąca wartość skali ocen.

Musi być podana, jeśli podana jest też maksymalna wartość oceny.

Liczba >= 0,0
Rating - Count (Liczba ocen) Opcjonalny

Liczba ocen sklepu.

Uwaga: wypełnij to pole, jeśli aplikacja ma kontrolować sposób wyświetlania tego elementu użytkownikom. Podaj zwięzły ciąg znaków, który może być wyświetlany użytkownikowi. Jeśli np. liczba wynosi 1 000 000, rozważ użycie skrótu, np. 1 mln, aby nie została ona obcięta w mniejszych rozmiarach wyświetlacza.

Ciąg znaków
Rating - Count Value Opcjonalny

Liczba ocen sklepu.

Uwaga: wypełnij to pole, jeśli nie chcesz samodzielnie obsługiwać logiki wyświetlania skrótów. Jeśli dostępne są zarówno właściwości Liczba, jak i Wartość liczby, użytkownikom wyświetlimy liczbę.

Długie

RecipeEntity

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

Ilustracja : atrybuty RecipeEntity

Atrybut Wymaganie Opis Format
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Więcej informacji znajdziesz w specyfikacji zdjęć.
Identyfikator URI działania Wymagany

Precyzyjny link do strony w aplikacji z informacjami o recepturze.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI
Tytuł Opcjonalny Nazwa przepisu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Autor Opcjonalny Autor przepisu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Czas gotowania/przygotowania Opcjonalny Czas gotowania według przepisu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Objaśnienie Opcjonalny Wskazówka dotycząca promocji, wydarzenia lub aktualizacji przepisu (jeśli są dostępne).

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Kategoria Opcjonalny Kategoria przepisu.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 45 znaków (tekst, który jest za długi, może zawierać wielokropki)

Opis Opcjonalny Opis przepisu.

Tekst otwarty

Zalecana długość tekstu: mniej niż 90 znaków (za długi tekst może być wyświetlany z wielokropem)

Uwaga: wszystkie oceny są wyświetlane za pomocą naszego standardowego systemu oceny za pomocą gwiazdek.
Ocena – wartość maksymalna Opcjonalny

Maksymalna wartość skali oceny.

Musi być podana, jeśli podana jest też aktualna wartość oceny.

Liczba >= 0,0
Rating - Current value Opcjonalny

Bieżąca wartość skali ocen.

Musi być podana, jeśli podana jest też maksymalna wartość oceny.

Liczba >= 0,0
Rating - Count (Liczba ocen) Opcjonalny

Liczba ocen przepisu.

Uwaga: wypełnij to pole, jeśli aplikacja ma kontrolować sposób wyświetlania tego elementu użytkownikom. Podaj zwięzły ciąg znaków, który może być wyświetlany użytkownikowi. Jeśli np. liczba wynosi 1 000 000, rozważ użycie skrótu, np. 1 mln, aby nie została ona obcięta w mniejszych rozmiarach wyświetlacza.

Ciąg znaków
Rating - Count Value Opcjonalny

Liczba ocen przepisu.

Uwaga: wypełnij to pole, jeśli nie chcesz samodzielnie obsługiwać logiki wyświetlania skrótów. Jeśli dostępne są zarówno właściwości Liczba, jak i Wartość liczby, wyświetlana jest liczba.

Długie

FoodShoppingCart

Ilustracja: atrybuty klastra koszyka Zakupy spożywcze.

Atrybut Wymaganie 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 odpowiedzi na najczęstsze pytania

Identyfikator URI
Liczba elementów Wymagany

Liczba elementów (a nie tylko liczba produktów) w koszyku.

Przykład: jeśli w koszyku są 3 pomarańcze i 1 jabłko, liczba ta powinna wynosić 4.

Liczba całkowita > 1
Tytuł Opcjonalny

Tytuł koszyka (np. Twój koszyk).

Jeśli deweloper nie poda tytułu, domyślnie zostanie użyty tytuł Twój kosz.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 25 znaków (tekst, który jest za długi, może być zastąpiony 3 kropkami)

Tekst wezwania do działania Opcjonalny

Tekst wezwania do działania na przycisku w koszyku (np. Twój koszyk).

Jeśli deweloper nie poda tekstu działania, domyślnie będzie to Wyświetl koszyk.

Ten atrybut jest obsługiwany od wersji 1.1.0.

Ciąg znaków
Obrazy koszyka Opcjonalny

obrazy każdego produktu w koszyku.

Możesz podać maksymalnie 10 obrazów w kolejności priorytetów. Rzeczywista liczba wyświetlanych obrazów zależy od formy urządzenia.

Więcej informacji znajdziesz w specyfikacji zdjęć.
Etykiety elementów Opcjonalny

Lista etykiet produktów na liście zakupów.

Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia.

Lista etykiet w formie tekstu wolnego

Zalecane rozmiary tekstu: poniżej 20 znaków (tekst, który jest za długi, może być zastąpiony 3 kropkami)

DisplayTimeWindow (opcjonalnie) – ustaw przedział czasu, w którym treści mają być wyświetlane na urządzeniu
Sygnatura czasowa rozpoczęcia Opcjonalny

sygnatura czasowa ery, po której treści powinny być wyświetlane na danej powierzchni;

Jeśli nie jest ustawione, treści mogą być wyświetlane na platformie.

Sygnatura czasowa epoki w milisekundach
Sygnatura czasowa zakończenia Opcjonalny

Znak czasu epoki, po którym treści nie są już wyświetlane na powierzchni.

Jeśli nie skonfigurujesz tej zasady, treści mogą być wyświetlane na powierzchni.

Sygnatura czasowa epoki w milisekundach

FoodShoppingList

Ilustracja: klaster dotyczący listy zakupów spożywczych.

Atrybut Wymaganie 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. 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ł Opcjonalny

Tytuł listy (np. Twoja lista zakupów).

Jeśli deweloper nie poda tytułu, domyślnie zostanie wyświetlona lista zakupów.

Tekst otwarty

Zalecane rozmiary tekstu: poniżej 25 znaków (tekst, który jest za długi, może być zastąpiony 3 kropkami)

Etykiety elementów Wymagany

Lista etykiet produktów na liście zakupów.

Należy podać co najmniej 1 etykietę, a maksymalnie 10 etykiet w kolejności priorytetów; rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia.

Lista etykiet w formie tekstu wolnego

Zalecane rozmiary tekstu: poniżej 20 znaków (tekst, który jest za długi, może być zastąpiony 3 kropkami)

FoodReorderCluster

Ilustracja: klaster „Zamów ponownie jedzenie”.

Atrybut Wymaganie Opis Format
Identyfikator URI działania Wymagany

Precyzyjny link do ponownego zamówienia w aplikacji partnera.

Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania

Identyfikator URI
Tekst wezwania do działania Opcjonalny

Tekst wezwania do działania na przycisku „Zamówienie ponownie” (np. Zamówienie ponownie).

Jeśli deweloper nie poda tekstu czynności, domyślnie zostanie wybrana opcja Zmień kolejność.

Ten atrybut jest obsługiwany od wersji 1.1.0.

Ciąg znaków
Liczba elementów Wymagany

Liczba elementów (a nie tylko liczba produktów) w poprzednim zamówieniu.

Przykład: jeśli w poprzednim zamówieniu były 3 małe kawy i 1 rogalik, liczba ta powinna wynosić 4.

Liczba całkowita > 1
Tytuł Wymagany Tytuł produktu do ponownego zamówienia.

Tekst otwarty

Zalecana długość tekstu: mniej niż 40 znaków (tekst, który jest za długi, może zawierać wielokropki)

Etykiety elementów

Opcjonalny

(jeśli nie ma obrazów plakatu, należy je przesłać)

Lista etykiet elementów z poprzedniego zamówienia.

Możesz podać maksymalnie 10 etykiet w kolejności priorytetów. Rzeczywista liczba wyświetlanych etykiet zależy od formatu urządzenia.

Lista z tekstem dowolnym

Zalecany rozmiar tekstu na etykietę: mniej niż 20 znaków(tekst, który jest zbyt długi, może być wyświetlany w postaci wielokropka)

Obrazy plakatu

Opcjonalny

(jeśli nie podano, należy podać etykiety produktów)

zdjęcia produktów z poprzedniego zamówienia.

Możesz podać maksymalnie 10 obrazów w kolejności priorytetów. Rzeczywista liczba wyświetlanych obrazów zależy od formy urządzenia.

Więcej informacji znajdziesz w specyfikacji zdjęć.

Specyfikacja obrazu

Wymagania dotyczące komponentów z obrazem:

Format obrazu Minimalna liczba pikseli Zalecany rozmiar w pikselach

Kwadrat (1 x 1)

Preferowany

300 x 300 1200 x 1200
Prostokąt w orientacji poziomej (1,91 x 1) 600 x 314 1200 x 628
Orientacja pionowa (4 x 5) 480 x 600 960 x 1200

Formaty plików

PNG, JPG, statyczny GIF, WebP

Maksymalny rozmiar pliku

5120 KB

Dodatkowe rekomendacje

  • Bezpieczny obszar obrazu: ważne treści umieść w środkowych 80% obrazu.
  • Użyj przezroczystego tła, aby obraz był prawidłowo wyświetlany w ustawieniach motywu ciemnego i jasnego.

Krok 2. Podaj dane klastra

Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i zaplanowane regularnie lub w reakcji na zdarzenie (np. za każdym razem, gdy użytkownik otworzy aplikację lub doda coś do koszyka).

AppEngageFoodClient odpowiada za publikowanie klastrów żywności.

Do publikowania klastrów w kliencie służą te interfejsy API:

  • 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 można wyświetlić treści na urządzeniu.

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

Ten interfejs API służy do publikowania listy obiektów RecommendationCluster.

Obiekt RecommendationCluster może mieć te atrybuty:

Atrybut Wymaganie Opis
Lista obiektów ProductEntity, StoreEntity lub RecipeEntity Wymagany Lista elementów, które stanowią rekomendacje w tym klastrze rekomendacji. Elementy w jednym klastrze muszą być tego samego typu.
Tytuł Wymagany

Tytuł klastra rekomendacji (np. Duże oszczędności na menu na Święto Dziękczynienia).

Zalecane rozmiary tekstu: poniżej 25 znaków (tekst, który jest za długi, może być zastąpiony 3 kropkami)

Podtytuł Opcjonalny Podtytuł klastra rekomendacji.
Identyfikator URI działania Opcjonalny

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 odpowiedzi 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, w ramach jednej transakcji wykona te działania:

  • Wszystkie istniejące dane klastra rekomendacji zostaną usunięte.
  • Dane z zapytania są analizowane i przechowywane w ramach nowych klastrów rekomendacji.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishFeaturedCluster

Ten interfejs API służy do publikowania 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 wykona te działania:

  • Istniejące dane FeaturedCluster od partnera dewelopera zostaną usunięte.
  • Dane z zapytania są analizowane i przechowywane w zaktualizowanym gronie polecanych.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest 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 wykona te działania:

  • Istniejące dane FoodShoppingCart od partnera dewelopera zostaną usunięte.
  • Dane z zapytania są analizowane i przechowywane w zaktualizowanym klastrze koszyka z zakupami.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest 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 wykona te działania:

  • Istniejące dane 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ła prośba jest odrzucana, a obecny stan jest 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 wykona te działania:

  • Istniejące dane FoodReorderCluster od partnera dewelopera zostaną usunięte.
  • Dane z zapytania są analizowane i przechowywane w zaktualizowanym klastrze do ponownego uporządkowania.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Działanie logowania kieruje użytkowników na stronę logowania w aplikacji, aby aplikacja mogła publikować treści (lub udostępniać bardziej spersonalizowane treści).

Te metadane są częścią karty logowania:

Atrybut Wymaganie Opis
Identyfikator URI działania Wymagane Precyzyjny link do działania (np. przejście na stronę logowania w aplikacji)
Obraz Opcjonalnie – jeśli nie zostanie podany, należy podać tytuł.

Obraz na karcie

obrazy w formacie 16 x 9 o rozdzielczości 1264 x 712;

Tytuł Opcjonalnie – jeśli nie zostanie podany, należy podać obraz Tytuł na karcie
Tekst wezwania do działania Opcjonalny Tekst wyświetlany w wezwaniu do działania (np. Zaloguj się)
Podtytuł Opcjonalny Opcjonalny tekst na karcie

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykona te działania:

  • Dotychczasowe dane UserAccountManagementCluster od partnera dewelopera zostaną usunięte.
  • Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze UserAccountManagementCluster.

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

updatePublishStatus

Jeśli z jakiegokolwiek wewnętrznego powodu biznesowego żaden z tych klastrów nie został opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu updatePublishStatus API. Jest to ważne, ponieważ :

  • Podanie stanu we wszystkich scenariuszach, nawet gdy treści są opublikowane (STATUS = PUBLISHED), jest kluczowe dla wypełniania paneli, które używają tego stanu do wyświetlania stanu i innych danych integracji.
  • Jeśli nie ma opublikowanych treści, ale integracja nie jest uszkodzona (STATUS = NOT_PUBLISHED), Google może nie uruchamiać alertów na panelach danych dotyczących zdrowia w aplikacji. Potwierdza, że treści nie są publikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
  • Pomaga deweloperom uzyskać informacje o tym, kiedy dane są publikowane, a kiedy nie.
  • Google może używać kodów stanu, aby zachęcić użytkownika do wykonania określonych działań w aplikacji, dzięki którym będzie on mógł zobaczyć jej zawartość lub je pokonać.

Lista prawidłowych kodów stanu 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 są publikowane, 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 treści z grup rekomendacji.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Gdy usługa otrzyma prośbę, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu cała prośba zostaje odrzucona, a istniejący stan jest zachowany.

deleteFeaturedCluster

Ten interfejs API służy do usuwania treści z wyróżnionego klastra.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra wyróżnionego. W przypadku błędu cała prośba zostaje odrzucona, a obecny stan jest zachowany.

deleteFoodShoppingCartCluster

Ten interfejs API służy do usuwania treści z grupy koszyków na zakupy z pokarmem.

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

Gdy usługa otrzyma żądanie, usuwa istniejące dane z grupy zakupów spożywczych. W przypadku błędu cała prośba zostaje odrzucona, a obecny stan jest zachowany.

deleteFoodShoppingListCluster

Ten interfejs API służy do usuwania treści z klastra listy zakupów z pokarmem.

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

Gdy usługa otrzyma prośbę, usuwa istniejące dane z klastra listy zakupów z pokarmem. W przypadku błędu cała prośba zostaje odrzucona, a obecny stan jest zachowany.

deleteReorderCluster

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

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra ponownego uporządkowania. W przypadku błędu cała prośba zostaje odrzucona, a obecny stan jest zachowany.

deleteUserManagementCluster

Ten interfejs API służy do usuwania treści z klastra UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Gdy usługa otrzyma żądanie, usuwa istniejące dane z klastra UserAccountManagement. W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

deleteClusters

Ten interfejs API służy do usuwania treści danego typu klastra.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

Gdy usługa otrzyma żądanie, usunie istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienci mogą przekazywać jeden lub wiele typów klastrów. W przypadku błędu cała prośba jest odrzucana, a istniejący stan jest zachowany.

Obsługa błędów

Zdecydowanie zalecamy odsłuchanie wyniku zadania z interfejsów API do publikowania, aby można było podjąć dalsze działania w celu odzyskania i ponowniego przesłania zadania.

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Błąd jest zwracany jako AppEngageException, a jego przyczyna jest podana w kodzie błędu.

Kod błędu Nazwa błędu Uwaga:
1 SERVICE_NOT_FOUND Usługa jest niedostępna na danym urządzeniu.
2 SERVICE_NOT_AVAILABLE Usługa jest dostępna na danym urządzeniu, ale nie jest dostępna w momencie połączenia (na przykład jest wyraźnie wyłączona).
3 SERVICE_CALL_EXECUTION_FAILURE Nie udało się wykonać zadania z powodu problemów z wątkami. W takim przypadku możesz spróbować ponownie.
4 SERVICE_CALL_PERMISSION_DENIED Dzwoniący nie ma uprawnień do zgłaszania zgłoszeń serwisowych.
5 SERVICE_CALL_INVALID_ARGUMENT Żądanie zawiera nieprawidłowe dane (np. więcej niż dozwoloną liczbę klastrów).
6 SERVICE_CALL_INTERNAL Po stronie usługi wystąpił błąd.
7 SERVICE_CALL_RESOURCE_EXHAUSTED wywołanie usługi jest wykonywane zbyt często.

Krok 3. Obsługa intencji przesyłania

Oprócz wywoływania interfejsu API publikowania treści za pomocą zadania musisz też skonfigurować interfejs BroadcastReceiver, aby odbierać żądania publikowania treści.

Intencje przesyłania strumieniowego służą głównie do ponownego aktywowania aplikacji i wymuszania synchronizacji danych. Intencje dotyczące transmisji nie są przeznaczone do wysyłania bardzo często. Jest ona wywoływana tylko wtedy, gdy usługa Engage stwierdzi, że treści mogą być nieaktualne (np. mają tydzień). Dzięki temu użytkownik ma pewność, że będzie mieć dostęp do aktualnych treści, nawet jeśli aplikacja nie była uruchamiana przez długi czas.

Element BroadcastReceiver musi być skonfigurowany w jednym z tych 2 sposobów:

  • Dynamicznie zarejestruj instancję klasy BroadcastReceiver za pomocą funkcji Context.registerReceiver(). Umożliwia to komunikację z aplikacji, które są nadal aktywne w pamięci.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger 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));

}

  • Zadeklaruj statycznie implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać intencje przesyłania, gdy nie jest uruchomiona, a także publikować treści.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.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 intencje:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Gdy otrzymasz tę intencję, zalecamy rozpoczęcie rozmowy publishRecommendationClusters.
  • com.google.android.engage.action.PUBLISH_FEATURED W przypadku otrzymania tego zamiaru zalecamy rozpoczęcie rozmowy publishFeaturedCluster.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART W przypadku otrzymania tego zamiaru zalecamy nawiązanie połączenia publishFoodShoppingCart.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST W przypadku otrzymania tego zamiaru zalecamy nawiązanie połączenia publishFoodShoppingList.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER Gdy otrzymasz ten zamiar, zalecamy rozpoczęcie rozmowy publishReorderCluster.

Proces integracji

Szczegółowy przewodnik dotyczący weryfikacji integracji po jej zakończeniu znajdziesz w artykule Procedura integracji Engage z usługami deweloperów.

Najczęstsze pytania

Najczęstsze pytania dotyczące Engage SDK znajdziesz w artykule Najczęstsze pytania dotyczące Engage SDK.

Kontakt

Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engage-developers@google.com. Nasz zespół odpowie tak szybko, jak to możliwe.

Dalsze kroki

Po zakończeniu tej integracji wykonaj te czynności:

  • Wyślij e-maila na adres engage-developers@google.com i załącz zintegrowany plik APK, który jest gotowy do przetestowania przez Google.
  • Google przeprowadzi wewnętrzną weryfikację i sprawdzenie, aby upewnić się, że integracja działa zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, skontaktujemy się z Tobą, aby przekazać niezbędne informacje.
  • Gdy testy zostaną zakończone i nie trzeba będzie wprowadzać żadnych zmian, skontaktujemy się z Tobą, aby poinformować, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Google Play.
  • Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, Twoje grupy Rekomendacja, Polecane, Koszyk, Lista zakupówPonowne zamówienie będą opublikowane i widoczne dla użytkowników.