Przeczytaj pakiet SDK Engage: instrukcje integracji technicznej z usługami innych firm

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 do czytania (e-booków, audiobooków, komiksów/mangi, blogów, wiadomości i czasopism) 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)
  • eBooki
  • Komiksy i manga
  • Audiobooki
  • Usługi czytania długich treści generowanych przez użytkowników
  • Blogi
  • Kolekcje
  • Entertainment Space
  • Karta Aplikacje w Sklepie Play
  • Karta Ty w Sklepie Play (tylko spersonalizowane rekomendacje i kontynuacja)
  • strona z informacjami o aplikacji w Sklepie Play,
Częściowo obsługiwane
(kwalifikuje się do wyświetlania na niektórych platformach)
  • Wiadomości i czasopisma*
  • Kolekcje
  • Entertainment Space
Nieobsługiwane
  • czytnik e-booków lub plików PDF,
  • Recenzje książek
  • Encyklopedia / słownik
  • Tłumacz
  • Teksty religijne

Serwisy informacyjne

Aplikacje prezentujące wiadomości zawierają różne treści, z których każda podlega unikalnym zasadom kwalifikacji. Treści z pakietu Engage SDK w Sklepie Play są zgodne z płatnymi narzędziami wspierającymi rozwój w Google Play, dlatego artykuły i klipy wideo z aplikacji z wiadomościami nie kwalifikują się do Sklepu Play, ale kwalifikują się do Kolekcji i Entertainment Space. Z kolei nietradycyjne treści informacyjne, takie jak podcasty i przepisy, mogą być dostępne w Sklepie Play:

Typ jednostki Kwalifikuje się do kolekcji Kwalifikuje się do Entertainment Space Kwalifikuje się do Sklepu Play
Artykuł prasowy Tak (karta Czytaj) Tak (karta Czytaj) Nie
Klip wideo Tak (karta Oglądaj) Tak (karta Oglądaj) Nie
Podcast Tak (karta Słuchaj) Tak (karta Słuchaj) Tak
Przepis Tak (karta Jedzenie) Nie Tak

Szczegóły integracji

W tej sekcji znajdziesz szczegółowe informacje o krokach, modelach danych i terminologii wymaganych do integracji z pakietem Engage SDK na potrzeby treści do czytania.

Terminologia

Ta integracja obejmuje 3 typy klastrów: Rekomendacja, Kontynuacja i Polecane.

  • Rekomendacje to grupy zawierające spersonalizowane sugestie dotyczące treści do przeczytania od konkretnego partnera deweloperskiego.

    Rekomendacje mają taką strukturę:

    • Grupa rekomendacji: widok interfejsu zawierający grupę rekomendacji od jednego partnera deweloperskiego.

      Rysunek 1. Interfejs Entertainment Space przedstawiający klaster rekomendacji od jednego partnera.

    • Encja: obiekt reprezentujący pojedynczy element w klastrze. Encją może być e-book, audiobook, seria książek itp. Listę obsługiwanych typów encji znajdziesz w sekcji Podawanie danych encji.

      Rysunek 2. Interfejs Entertainment Space wyświetlający pojedynczy element w grupie rekomendacji jednego partnera.

  • Grupa Kontynuacja zawiera niedokończone książki od wielu partnerów programistów w jednym układzie interfejsu. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Kontynuacja.

    Rysunek 3. Interfejs Przestrzeni rozrywkowej z grupą Kontynuacja zawierającą niedokończone rekomendacje od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja).

  • Grupa Polecane zawiera wybrane elementy od wielu partnerów programistów w jednym układzie interfejsu. Jeden wyróżniony klaster będzie wyświetlany u góry interfejsu w priorytetowym miejscu nad wszystkimi innymi klastrami rekomendacji. Każdy partner deweloper może transmitować maksymalnie 10 elementów w klastrze Polecane.

    Rysunek 4. Interfejs Centrum rozrywki z grupą Polecane zawierającą rekomendacje od wielu partnerów (obecnie widoczna jest tylko jedna rekomendacja).

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 Maksymalne limity elementów w klastrze
Klastry rekomendacji Maksymalnie 7 Maksymalnie 50
Klaster kontynuacji Maksymalnie 1 Maksymalnie 20
Polecana grupa Maksymalnie 1 Maksymalnie 20

Krok 1. Podaj dane podmiotu

Pakiet SDK definiuje różne encje reprezentujące poszczególne typy produktów. W kategorii Czytanie obsługujemy te encje:

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

EbookEntity

Obiekt EbookEntity reprezentuje e-booka (np. e-book Becoming Michelle Obamy).

Atrybut Wymaganie Uwagi
Nazwa Wymagany
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu.
Autor Wymagany Musisz podać co najmniej 1 nazwę autora.
Identyfikator URI linku do działania Wymagany

Precyzyjny link do aplikacji dostawcy e-booka.

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

Data publikacji Opcjonalny W milisekundach od początku epoki, jeśli podano.
Opis Opcjonalny Jeśli podasz tę wartość, nie może ona przekraczać 200 znaków.
Cena Opcjonalny Dowolny tekst
Liczba stron Opcjonalny Musi to być dodatnia liczba całkowita (jeśli została podana).
gatunek; Opcjonalny Lista gatunków powiązanych z książką.
Nazwa serii Opcjonalny Nazwa serii, do której należy e-book (np. Harry Potter).
Indeks jednostki serii Opcjonalny Indeks e-booka w serii, gdzie 1 to pierwszy e-book w serii. Jeśli na przykład Harry Potter i więzień Azkabanu to trzecia książka w serii, należy ustawić wartość 3.
Kontynuuj typ książki Opcjonalny

TYPE_CONTINUE – wznów czytanie niedokończonej książki.

TYPE_NEXT – kontynuuj w nowym elemencie serii.

TYPE_NEW – nowo wydane.
Czas ostatniego zaangażowania Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

*Nowo* nabyte e-booki mogą być częścią klastra „Czytaj dalej”.

W milisekundach od początku epoki.
Procent ukończenia postępu Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

Wartość musi być większa niż 0 i mniejsza niż 100.
DisplayTimeWindow – ustawianie przedziału czasowego, w którym treści mają być wyświetlane na danej 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.

W milisekundach od początku epoki.
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.

W milisekundach od początku epoki.

AudiobookEntity

Obiekt AudiobookEntity reprezentuje audiobooka (np. audiobook Becoming Michelle Obamy).

Atrybut Wymaganie Uwagi
Nazwa Wymagany
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu.
Autor Wymagany Musisz podać co najmniej 1 nazwę autora.
Identyfikator URI linku do działania Wymagany

Precyzyjny link do aplikacji dostawcy audiobooka.

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

Narrator Opcjonalny Musisz podać imię i nazwisko co najmniej 1 narratora.
Data publikacji Opcjonalny W milisekundach od początku epoki, jeśli podano.
Opis Opcjonalny Jeśli podasz tę wartość, nie może ona przekraczać 200 znaków.
Cena Opcjonalny Dowolny tekst
Czas trwania Opcjonalny Jeśli podano, musi być wartością dodatnią.
gatunek; Opcjonalny Lista gatunków powiązanych z książką.
Nazwa serii Opcjonalny Nazwa serii, do której należy audiobook (np. Harry Potter).
Indeks jednostki serii Opcjonalny Indeks audiobooka w serii, gdzie 1 to pierwszy audiobook w serii. Jeśli na przykład Harry Potter i więzień Azkabanu to trzecia książka w serii, należy ustawić wartość 3.
Kontynuuj typ książki Opcjonalny

TYPE_CONTINUE – wznów czytanie niedokończonej książki.

TYPE_NEXT – kontynuuj w nowym elemencie serii.

TYPE_NEW – nowo wydane.
Czas ostatniego zaangażowania Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

W milisekundach od początku epoki.
Procent ukończenia postępu Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

*Nowo* nabyte audiobooki mogą być częścią klastra „Czytaj dalej”.

Wartość musi być większa niż 0 i mniejsza niż 100.
DisplayTimeWindow – ustawianie przedziału czasowego, w którym treści mają być wyświetlane na danej 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.

W milisekundach od początku epoki.
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.

W milisekundach od początku epoki.

BookSeriesEntity

Obiekt BookSeriesEntity reprezentuje serię książek (np. serię książek o Harrym Potterze, która składa się z 7 pozycji).

Atrybut Wymaganie Uwagi
Nazwa Wymagany
Obrazy plakatu Wymagany Musisz podać co najmniej 1 obraz. Wskazówki znajdziesz w specyfikacji obrazu.
Autor Wymagany Musi być podane co najmniej jedno imię i nazwisko autora.
Identyfikator URI linku do działania Wymagany

Precyzyjny link do aplikacji dostawcy audiobooka lub e-booka.

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

Liczba książek Wymagany Liczba książek z serii.
Opis Opcjonalny Jeśli podasz tę wartość, nie może ona przekraczać 200 znaków.
gatunek; Opcjonalny Lista gatunków powiązanych z książką.
Kontynuuj typ książki Opcjonalny

TYPE_CONTINUE – wznów czytanie niedokończonej książki.

TYPE_NEXT – kontynuuj w nowym elemencie serii.

TYPE_NEW – nowo wydane.
Czas ostatniego zaangażowania Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

W milisekundach od początku epoki.
Procent ukończenia postępu Wymagane warunkowo

Należy podać, gdy element znajduje się w klastrze kontynuacji.

*Nowo* nabyte serie książek mogą być częścią grupy „Czytaj dalej”.

Wartość musi być większa niż 0 i mniejsza niż 100.
DisplayTimeWindow – ustawianie przedziału czasowego, w którym treści mają być wyświetlane na danej 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.

W milisekundach od początku epoki.
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.

W milisekundach od początku epoki.

Specyfikacja obrazu

W tabeli poniżej znajdziesz wymagane specyfikacje komponentów z obrazem:

Format obrazu Obsługiwane klastry Minimalny rozmiar w pikselach Zalecany rozmiar w pikselach
Kwadrat (1 x 1) Wszystkie klastry 300 x 300 1200 x 1200
Poziomy (1,91 x 1) Polecane i kontynuacja 600 x 314 1200 x 628
Orientacja pionowa (4 x 5) Rekomendacja 480 x 600 960 x 1200

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.

Przykład

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

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 właśnie dodał coś do koszyka).

AppEngagePublishClient odpowiada za klastry publikujące. W kliencie dostępne są te interfejsy API:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • 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.

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 Twoja aplikacja korzysta z przetwarzania przerywanego:

  • Klastry kontynuacji (takie jak Czytaj dalej) pozostają domyślnie włączone na wszystkich obsługiwanych urządzeniach.
  • Inne typy klastrów (np. rekomendacje) są włączane i wyłączane okresowo.

Jeśli ta domyślna konfiguracja nie odpowiada Twoim potrzebom, skontaktuj się z nami pod adresem engage-developers@google.com.

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

publishRecommendationClusters

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

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

Ten interfejs API służy do publikowania listy obiektów 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 zostaną wykonane te działania:

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

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

publishContinuationCluster

Ten interfejs API służy do publikowania obiektu ContinuationCluster.

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

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

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

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

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.

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.

deleteFeaturedCluster

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

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

deleteContinuationCluster

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

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastra kontynuacji. 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.

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.

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ł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
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION 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)

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

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           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

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION 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);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         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>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </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.
  • com.google.android.engage.action.PUBLISH_FEATURED Po otrzymaniu tej intencji zalecamy rozpoczęcie połączenia publishFeaturedCluster.
  • com.google.android.engage.action.PUBLISH_CONTINUATIONIt is recommended to start apublishContinuationCluster` po otrzymaniu tej intencji.

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 engage-developers@google.com. 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 engage-developers@google.com i załącz zintegrowany plik APK, który jest gotowy do przetestowania przez Google.
  • Google przeprowadzi weryfikację i sprawdzi wewnętrznie, czy integracja działa zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, Google skontaktuje się z Tobą i poda niezbędne szczegóły.
  • Gdy testy zostaną zakończone 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, klastry Polecane, Wyróżnione i Kontynuacja zostaną opublikowane i będą widoczne dla użytkowników.