Engage SDK Social: instrukcje integracji technicznej firm zewnętrznych

Zwiększ zaangażowanie w aplikację, docierając do użytkowników tam, gdzie się znajdują. Zintegruj pakiet Engage SDK, aby wyświetlać spersonalizowane rekomendacje i treści kontynuacji bezpośrednio użytkownikom na różnych platformach na urządzeniu, takich jak Kolekcje, Entertainment Space i Sklep Play. Integracja zwiększa rozmiar średniego pliku APK (skompresowany) o mniej niż 50 KB i zajmuje deweloperom około tygodnia pracy. Więcej informacji znajdziesz na naszej stronie.

Ten przewodnik zawiera instrukcje dla partnerów deweloperów dotyczące dostarczania treści z mediów społecznościowych na platformy treści Engage.

Obsługa kategorii i platformy

Kwalifikacja do korzystania z platformy Engage SDK zależy od kategorii treści aplikacji. W tabeli poniżej możesz sprawdzić, czy kwalifikujesz się do wyświetlania produktów na określonych platformach:

Stan	Kategoria treści lub przypadek użycia	Obsługiwane platformy
Obsługiwane (Kwalifikują się do wyświetlania na wszystkich platformach)	Sieci społecznościowe Obraz / memy klipy wideo / krótkie filmy, spotkania w rzeczywistości, Przechowywanie zdjęć w chmurze	Kolekcje Karta Aplikacje w Sklepie Play Karta Ty w Sklepie Play strona z informacjami o aplikacji w Sklepie Play,
Nieobsługiwane	Czat wideo na żywo czat, udostępnianie obecności w internecie lub dane na żywo; Udostępnianie i pobieranie plików Randki Generatory awatarów

Umiejętności związane z Androidem

Wyświetl na GitHubie

Integracja z pakietem Engage SDK

Użyj umiejętności Androida w pakiecie Engage SDK, aby zintegrować i debugować implementację oraz rozwiązywać problemy z nią związane.

Aby zainstalować umiejętność z interfejsu wiersza poleceń Androida, uruchom:

android skills add engage-sdk-integration

Szczegóły integracji

W sekcji poniżej znajdziesz szczegółowe informacje o integracji.

Terminologia

Rekomendacje to grupy zawierające spersonalizowane sugestie od konkretnego partnera deweloperskiego.

Rekomendacje mają taką strukturę:

Grupa rekomendacji: widok interfejsu zawierający grupę rekomendacji od tego samego partnera deweloperskiego.

Każdy klaster rekomendacji składa się z jednego z tych 2 typów elementów :

• PortraitMediaEntity
• SocialPostEntity

PortraitMediaEntity musi zawierać 1 obraz w orientacji pionowej dla posta. Metadane dotyczące profilu i interakcji są opcjonalne.

• Post

  • obraz w trybie portretowym i sygnaturę czasową lub
  • Obraz w trybie portretowym + treść tekstowa i sygnatura czasowa

• Profil

  • Awatar, nazwa lub nick, dodatkowy obraz

• Interakcje

  • tylko liczenie i oznaczanie etykietami,
  • Liczba i element wizualny (ikona)

SocialPostEntity zawiera metadane związane z profilem, postem i interakcją.

• Profil

  • Awatar, nazwa lub nick, dodatkowy tekst, dodatkowy obraz

• Post

  • tekst i sygnatura czasowa,
  • rich media (obraz lub URL multimediów) i sygnatura czasowa lub
  • tekst i rich media (obraz lub URL rich media) oraz sygnatura czasowa,
  • Podgląd filmu (miniatura i czas trwania) oraz sygnatura czasowa

• Interakcje

  • tylko zliczanie i oznaczanie etykietą,
  • Liczba i element wizualny (ikona)

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.6.0'
}

Podsumowanie

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

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

Typ klastra	Limity klastra	Minimalne limity elementów w klastrze	Maksymalne limity elementów w klastrze
Klastry rekomendacji	Maksymalnie 7	Co najmniej 1 (PortraitMediaEntity lub SocialPostEntity)	Maksymalnie 50 (PortraitMediaEntity lub SocialPostEntity)

Krok 1. Podaj dane podmiotu

Pakiet SDK definiuje różne encje reprezentujące poszczególne typy produktów. Pakiet SDK obsługuje te encje w kategorii Społecznościowe:

1. PortraitMediaEntity
2. SocialPostEntity

Poniższe tabele zawierają dostępne atrybuty i wymagania dotyczące każdego typu.

PortraitMediaEntity

Atrybut	Wymaganie	Opis	Format
Identyfikator URI działania	Wymagany na wszystkich platformach innych niż Google TV.	Precyzyjny link do elementu w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.	Identyfikator URI
PlatformSpecificPlayback	Wymagany w przypadku platformy Google TV	Precyzyjny link do elementu w aplikacji dostawcy na platformach takich jak Google TV i urządzenia mobilne.	Lista obiektów PlatformSpecificPlayback
Powód rekomendacji	Opcjonalny	Uzasadnienie polecania treści użytkownikowi.	Obiekt RecommendationReason
Podsumowanie komentarzy	Opcjonalny	Podsumowanie komentarzy do posta.	Ciąg znaków
Metadane związane z postem (wymagane)
Zdjęcie(a)	Wymagane	Obrazy powinny mieć pionowy format obrazu. Jeśli podano kilka obrazów, interfejs może wyświetlać tylko 1 obraz. Interfejs może jednak zawierać wizualne wskazówki, że w aplikacji jest więcej obrazów. Jeśli post jest filmem, dostawca powinien udostępnić miniaturę filmu, która będzie wyświetlana jako obraz.	Wskazówki znajdziesz w specyfikacji obrazu.
Zawartość tekstowa	Opcjonalny	Główny tekst posta, aktualizacji itp.	Ciąg znaków (zalecane ograniczenie do 140 znaków)
Sygnatura czasowa	Opcjonalny	Czas opublikowania posta.	Sygnatura czasowa epoki w milisekundach
jest treścią wideo;	Opcjonalny	Czy post jest filmem?	wartość logiczna
Czas trwania wideo	Opcjonalny	Czas trwania filmu w milisekundach.	Długi
Metadane związane z profilem (opcjonalnie)
Nazwa	Wymagane	Nazwa profilu, identyfikator lub nick, np. „Jan Kowalski”, „@TeamPixel”	Ciąg znaków(zalecane maksymalnie 25 znaków)
Awatar	Wymagane	Zdjęcie profilowe lub awatar użytkownika. Obraz kwadratowy (1:1)	Wskazówki znajdziesz w specyfikacji obrazu.
Dodatkowe zdjęcie	Opcjonalny	Odznaka w profilu, np. odznaka „Zweryfikowano” Obraz kwadratowy (1:1)	Wskazówki znajdziesz w specyfikacji obrazu.
Metadane związane z interakcjami (opcjonalnie)
Liczba	Opcjonalny	Wskazuje liczbę interakcji, np. „3,7 mln”. Uwaga: jeśli podasz zarówno liczbę, jak i wartość liczby, użyta zostanie liczba. Uwaga: partnerzy powinni używać elementu Count lub CountWithOptionalLabel.	Ciąg znaków
CountWithOptionalLabel	Opcjonalny	Podaj liczbę interakcji z opcjonalną etykietą, na przykład „3,7 mln polubień”. Uwaga: jeśli podano zarówno CountWithOptionalLabel, jak i Count Value, zostanie użyta jedna z tych wartości. Uwaga: partnerzy powinni używać elementu Count lub CountWithOptionalLabel.	Ciąg znaków
Wartość liczby	Opcjonalny	Liczba interakcji jako wartość. Uwaga: jeśli Twoja aplikacja nie obsługuje logiki optymalizacji dużych liczb pod kątem różnych rozmiarów wyświetlacza, podaj wartość liczby zamiast liczby. Jeśli podano zarówno liczbę, jak i wartość liczby, używana jest liczba.	Długi
Etykieta	Opcjonalny	Wskaż, do czego służy etykieta interakcji. Na przykład „Polubienia”.	Ciąg znaków
Wizualne	Opcjonalny	Wskaż, do czego służy interakcja. Na przykład obraz przedstawiający ikonę polubienia, emotikon. Możesz przesłać więcej niż 1 obraz, ale nie wszystkie mogą być wyświetlane na wszystkich formatach. Uwaga: musi to być obraz kwadratowy (1:1).	Wskazówki znajdziesz w specyfikacji obrazu.
DisplayTimeWindow (opcjonalnie) – ustaw okno czasowe, w którym treści mają być wyświetlane na platformie.
Sygnatura czasowa rozpoczęcia	Opcjonalny	Sygnatura czasowa epoki, po której treści powinny być wyświetlane na danej platformie. Jeśli nie jest ustawiona, treści mogą być wyświetlane na danej platformie.	Sygnatura czasowa epoki w milisekundach
Sygnatura czasowa zakończenia	Opcjonalny	Sygnatura czasowa epoki, po której treści nie są już wyświetlane na danej platformie. Jeśli nie jest ustawiona, treści mogą być wyświetlane na danej platformie.	Sygnatura czasowa epoki w milisekundach

SocialPostEntity

Atrybut	Wymaganie	Opis	Format
Identyfikator URI działania	Wymagany	Precyzyjny link do elementu w aplikacji dostawcy. Uwaga: do atrybucji możesz używać precyzyjnych linków. Zapoznaj się z odpowiedziami na najczęstsze pytania.	Identyfikator URI
PlatformSpecificPlayback URIs	Wymagany w przypadku platformy Google TV	Precyzyjny link do elementu w aplikacji dostawcy na platformach takich jak Google TV i urządzenia mobilne.	Lista obiektów PlatformSpecificPlayback
Powód rekomendacji	Opcjonalny	Uzasadnienie polecania treści użytkownikowi.	Obiekt RecommendationReason
Podsumowanie komentarzy	Opcjonalny	Podsumowanie komentarzy do posta.	Ciąg znaków
Metadane związane z postem (wymagane) Wymagany jest co najmniej jeden z tych elementów: TextContent, Image lub WebContent
Zdjęcie(a)	Opcjonalny	Obrazy powinny mieć pionowy format obrazu. Jeśli podano kilka obrazów, interfejs może wyświetlać tylko 1 obraz. Interfejs może jednak zawierać wizualne wskazówki, że w aplikacji jest więcej obrazów. Jeśli post jest filmem, dostawca powinien udostępnić miniaturę filmu, która będzie wyświetlana jako obraz.	Wskazówki znajdziesz w specyfikacji obrazu.
Zawartość tekstowa	Opcjonalny	Główny tekst posta, aktualizacji itp.	Ciąg znaków (zalecane ograniczenie do 140 znaków)
Treści wideo (opcjonalnie)
Czas trwania	Wymagane	Czas trwania filmu w milisekundach.	Długi
Obraz	Wymagane	Podgląd treści wideo.	Wskazówki znajdziesz w specyfikacji obrazu.
Link Preview (Optional)
Podgląd linku – tytuł	Wymagane	Tekst wskazujący tytuł zawartości strony internetowej	Ciąg znaków
Podgląd linku – nazwa hosta	Wymagane	Tekst wskazujący właściciela strony internetowej, np. „OSOBA WTAJEMNICZONA”	Ciąg znaków
Podgląd linku – obraz	Opcjonalny	Baner powitalny treści z internetu	Wskazówki znajdziesz w specyfikacji obrazu.
Sygnatura czasowa	Opcjonalny	Czas opublikowania posta.	Sygnatura czasowa epoki w milisekundach
Metadane związane z profilem (opcjonalnie)
Nazwa	Wymagane	Nazwa profilu, identyfikator lub nick, np. „Jan Kowalski”, „@TeamPixel”.	Ciąg znaków(zalecane maksymalnie 25 znaków)
Dodatkowy tekst	Opcjonalny	Może być używany jako identyfikator profilu, nick lub dodatkowe metadane. Na przykład „@Jan-Kowalski”, „5 mln obserwujących”, „Może Ci się spodobać”, „Na czasie”, „5 nowych postów”	Ciąg znaków(zalecane maksymalnie 40 znaków)
Awatar	Wymagane	Zdjęcie profilowe lub awatar użytkownika. Obraz kwadratowy (1:1)	Wskazówki znajdziesz w specyfikacji obrazu.
Dodatkowe zdjęcie	Opcjonalny	Plakietka profilu, np. plakietka „Zweryfikowano” Obraz kwadratowy (1:1)	Wskazówki znajdziesz w specyfikacji obrazu.
Metadane związane z interakcjami (opcjonalnie)
Liczba	Wymagane	Wskazuje liczbę interakcji, np. „3,7 mln”. Uwaga: partnerzy powinni używać elementu Count lub CountWithOptionalLabel.	Ciąg znaków
CountWithOptionalLabel	Wymagane	Wskaż liczbę interakcji z opcjonalną etykietą, na przykład „3,7 mln polubień”. Uwaga: partnerzy powinni używać elementu Count lub CountWithOptionalLabel.	Ciąg znaków
Etykieta	Opcjonalny Jeśli nie podano, należy podać Visual.	Wskaż, do czego służy interakcja. Na przykład „Polubienia”.	Ciąg tekstowy (zalecana maksymalna liczba znaków dla liczby i etykiety to 20)
Wizualne	Opcjonalny Jeśli nie podano, należy podać Etykietę.	Wskaż, do czego służy interakcja. Na przykład obraz przedstawiający ikonę polubień, emotikon. Możesz przesłać więcej niż 1 obraz, ale nie wszystkie będą wyświetlane na wszystkich formatach. Obraz kwadratowy (1:1)	Wskazówki znajdziesz w specyfikacji obrazu.
DisplayTimeWindow (opcjonalnie) – ustaw okno czasowe, w którym treści mają być wyświetlane na platformie.
Sygnatura czasowa rozpoczęcia	Opcjonalny	Sygnatura czasowa epoki, po której treści powinny być wyświetlane na danej platformie. Jeśli nie jest ustawiona, treści mogą być wyświetlane na danej platformie.	Sygnatura czasowa epoki w milisekundach
Sygnatura czasowa zakończenia	Opcjonalny	Sygnatura czasowa epoki, po której treści nie są już wyświetlane na danej platformie. Jeśli nie jest ustawiona, treści mogą być wyświetlane na danej platformie.	Sygnatura czasowa epoki w milisekundach

Specyfikacja obrazu

Obrazy muszą być hostowane w publicznych sieciach CDN, aby Google miało do nich dostęp.

Formaty plików

PNG, JPG, statyczny GIF, WebP

Maksymalny rozmiar pliku

5120 KB

Dodatkowe zalecenia

• Zawsze widoczny 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 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 było zaplanowane regularnie lub na podstawie zdarzenia (np. za każdym razem, gdy użytkownik otwiera aplikację lub gdy zaczyna obserwować nowe konto).

AppEngageSocialClient odpowiada za publikowanie klastrów społecznościowych.

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

• isServiceAvailable
• publishRecommendationClusters
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• 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.

Pakiet Engage SDK w wersji 1.6.0 lub nowszej (zalecany)

Umiejętności związane z Androidem

Wyświetl na GitHubie

Integracja z pakietem Engage SDK

Aby zainstalować umiejętność z interfejsu wiersza poleceń Androida, uruchom:

android skills add engage-sdk-integration

Jeśli Twój zespół korzysta z narzędzi do kodowania opartych na AI (takich jak Gemini w Android Studio), możesz zautomatyzować tę migrację, prosząc asystenta AI o pomoc:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

Możesz sprawdzić dostępność usługi dla każdego typu klastra, który chcesz opublikować. Interfejs API isServiceAvailable akceptuje obiekt żądania ServiceAvailabilityRequest, który zawiera typy klastrów, dla których należy sprawdzić dostępność usługi. Wartości typu wyliczeniowego ClusterType wymagane w przypadku ServiceAvailabilityRequest znajdziesz w tabeli poniżej.

Typ klastra	Stała typu klastra	Wartość w formie liczby całkowitej
Nieznany	TYPE_UNKNOWN	0
Klaster rekomendacji	TYPE_RECOMMENDATION	1
Polecana grupa	TYPE_FEATURED	2
Klaster kontynuacji	TYPE_CONTINUATION	3
Klaster zarządzania użytkownikami	TYPE_ENGAGEMENT	8
Klaster subskrypcji	TYPE_SUBSCRIPTION	12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

Funkcja warunkowej dostępności usługi

Niektóre zintegrowane aplikacje wymagają specjalnej konfiguracji, która okresowo włącza i wyłącza usługę Engage, aby obniżyć koszty wyświetlania. Jednak ta strategia przerywanego przetwarzania treści negatywnie wpływa na wrażenia użytkowników: nieaktualne treści nie będą wyświetlane, a niektóre platformy nie będą obsługiwane.

Od wersji 1.6.0 pakiet Engage SDK umożliwia sprawdzanie dostępności określonych typów klastrów. Jeśli chcesz włączyć tę funkcję w przypadku dowolnego typu klastra, skontaktuj się z nami pod adresem [e-mail].

Wersje pakietu SDK starsze niż 1.6.0 (wycofane)

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.
    }
});

Uwaga: zdecydowanie zalecamy, aby zadanie okresowe było nadal uruchamiane i sprawdzało, czy usługa stanie się dostępna w późniejszym czasie. Dostępność usługi może się zmieniać wraz z aktualizacjami wersji Androida, aktualizacjami aplikacji, instalacjami i odinstalowaniami. Dzięki okresowemu sprawdzaniu zadań w określonych odstępach czasu dane mogą być publikowane, gdy tylko usługa stanie się dostępna.

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 SocialPostEntity lub PortraitMediaEntity	Wymagany	Lista elementów, które składają się na rekomendacje dla tego klastra rekomendacji. Encje w jednym klastrze muszą być tego samego typu.
Tytuł	Wymagany	Tytuł klastra rekomendacji (np. Najnowsze od znajomych). Zalecane rozmiary tekstu: poniżej 25 znaków (tekst, który jest za długi, może zawierać wielokropek)
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. Zapoznaj się z odpowiedziami na najczęstsze pytania.

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treści, ponieważ interfejsy API do publikowania robią to automatycznie.

Ważne: w przypadku aplikacji społecznościowych bardzo ważne jest aktualizowanie rekomendacji po każdym użyciu aplikacji. Użytkownicy aplikacji społecznościowych są bardziej zainteresowani najnowszymi rekomendacjami i najlepiej, gdyby widzieli dany post najwyżej raz.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

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

• Wszystkie dotychczasowe 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 i zachowywany jest dotychczasowy stan.

publishUserAccountManagementRequest

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

Karta logowania zawiera te metadane:

Atrybut	Wymaganie	Opis
Identyfikator URI działania	Wymagane	Precyzyjny link do działania (np. przekierowuje na stronę logowania w aplikacji)
Obraz	Opcjonalny – jeśli nie zostanie podany, należy podać tytuł	Obraz wyświetlany na karcie obrazy o formacie obrazu 16:9 i rozdzielczości 1264 x 712,
Tytuł	Opcjonalny – jeśli nie zostanie podany, należy podać obraz	Tytuł na karcie
Tekst z opcją działania	Opcjonalny	Tekst wyświetlany w wezwaniu do działania (np. Zaloguj się)
Podtytuł	Opcjonalny	Opcjonalne napisy na karcie

Ważne: interfejsy API do publikowania to interfejsy API typu upsert, które zastępują istniejące treści. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie.

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 zostaną wykonane te działania:

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

W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

updatePublishStatus

Jeśli z jakiegoś powodu żaden z klastrów nie zostanie opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu API updatePublishStatus. To ważne, ponieważ :

• Podawanie stanu we wszystkich scenariuszach, nawet gdy treść jest opublikowana (STATUS == PUBLISHED), ma kluczowe znaczenie dla wypełniania paneli, które używają tego stanu do przekazywania informacji o stanie i innych danych dotyczących integracji.
• Jeśli nie opublikowano żadnych treści, ale stan integracji nie jest uszkodzony (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów w panelach stanu aplikacji. Potwierdza, że treści nie zostały opublikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
• Pomaga deweloperom dostarczać 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 czemu będzie on mógł zobaczyć jej zawartość lub rozwiązać problem.

Lista kwalifikujących się 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());

deleteRecommendationsClusters

Ten interfejs API służy do usuwania zawartości klastrów rekomendacji.

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie zostanie odrzucone i zostanie zachowany dotychczasowy stan.

deleteUserManagementCluster

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

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra UserAccountManagement. W przypadku błędu całe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

deleteClusters

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

Ważne: interfejsy API do usuwania należy wywoływać tylko wtedy, gdy nie ma treści do opublikowania. Nie wywołuj interfejsów API do usuwania i publikowania, aby zastąpić treść, ponieważ interfejsy API do publikowania robią to automatycznie. Zanim użyjesz interfejsów API do usuwania, skontaktuj się z [e-mail].

Kotlin

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

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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łe żądanie jest odrzucane i zachowywany jest dotychczasowy stan.

Obsługa błędów

Zdecydowanie zalecamy nasłuchiwanie wyniku zadania z interfejsów API publikowania, aby można było podjąć działania następcze w celu odzyskania i ponownego przesłania zadania, które się nie powiodło.

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 jako kod 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 wywołania (np. 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żna spróbować ponownie.
4	SERVICE_CALL_PERMISSION_DENIED	Wywołujący nie ma uprawnień do wywołania usługi.
5	SERVICE_CALL_INVALID_ARGUMENT	Żądanie zawiera nieprawidłowe dane (np. więcej klastrów niż dozwolona liczba).
6	SERVICE_CALL_INTERNAL	Wystąpił błąd po stronie usługi.
7	SERVICE_CALL_RESOURCE_EXHAUSTED	Wywołanie usługi jest wykonywane zbyt często.

Krok 3. Obsługa intencji rozgłaszania

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

Celem intencji rozgłaszania jest głównie reaktywacja aplikacji i wymuszenie synchronizacji danych. Intencje rozgłaszania nie są przeznaczone do częstego wysyłania. Jest wywoływana tylko wtedy, gdy usługa Engage określi, że treści mogą być nieaktualne (np. mają tydzień). Dzięki temu użytkownik może mieć pewność, że zobaczy aktualne treści, nawet jeśli aplikacja nie była uruchamiana przez dłuższy czas.

BroadcastReceiver należy skonfigurować na 2 sposoby:

• Zarejestruj dynamicznie instancję klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacjami, które są nadal aktywne w pamięci.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);
}

• Zadeklaruj statycznie implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać intencje transmisji, gdy nie jest uruchomiona, a także publikować treści.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
   </receiver>
</application>

Usługa będzie wysyłać te intencje:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Po otrzymaniu tej intencji zalecamy rozpoczęcie połączenia publishRecommendationClusters.

Przepływ pracy integracji

Szczegółowe instrukcje dotyczące weryfikacji integracji po jej zakończeniu znajdziesz w artykule Proces integracji dla deweloperów Engage.

Najczęstsze pytania

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

Kontakt

Jeśli masz pytania dotyczące procesu integracji, skontaktuj się z [e-mail]. Nasz zespół odpowie tak szybko, jak to możliwe.

Dalsze kroki

Po zakończeniu integracji wykonaj te czynności:

• Wyślij e-maila na adres [e-mail] i załącz zintegrowany plik APK, który jest gotowy do przetestowania przez Google.
• Google przeprowadza weryfikację i sprawdza wewnętrznie, czy integracja działa zgodnie z oczekiwaniami. Jeśli konieczne będą zmiany, Google skontaktuje się z Tobą i poda niezbędne informacje.
• Jeśli testy zakończą się pomyślnie i nie będą potrzebne żadne zmiany, Google skontaktuje się z Tobą, aby poinformować, że możesz zacząć publikować zaktualizowany i zintegrowany pakiet APK w Sklepie Play.
• Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, Twoje grupy rekomendacji zostaną opublikowane i będą widoczne dla użytkowników.