Ten przewodnik zawiera zestaw wytycznych dotyczących publikowania klastrów, z których deweloperzy mogą korzystać podczas integracji z pakietem Engage SDK.
Klastry rekomendacji
Tytuł klastra
Zalecamy podanie unikalnego i trafnego tytułu klastra, który dostarczy użytkownikom więcej informacji o jego zawartości.
Oto kilka przykładów dobrych tytułów klastrów na podstawie treści:
- Klastry związane z zakupami
- Lightning Deals
- Tygodniowe hity
- W związku z zakupem słuchawek Pixel Buds
- Kalosze damskie
- Klastry książek o zdrowiu
- Zdrowie, umysł i ciało
- Polecane dla Ciebie w kategorii Zdrowie
- Bestsellery w kategorii Fitness
Treści w klastrze
Podczas publikowania klastrów rekomendacji deweloperzy muszą wziąć pod uwagę, czy użytkownik jest zalogowany w aplikacji dewelopera.
Gdy użytkownik jest zalogowany
Jeśli użytkownik jest zalogowany w aplikacji dewelopera, zalecamy publikowanie spersonalizowanych klastrów treści lub klastrów treści generowanych przez użytkowników. Spersonalizowane treści i treści generowane przez użytkowników są bardziej trafne, więc użytkownicy są bardziej zmotywowani do odwiedzania aplikacji dewelopera z poziomu platformy Google.
- Spersonalizowane rekomendacje mogą być publikowane.
- Oto kilka przykładów spersonalizowanych rekomendacji:
- Najlepsze propozycje na podstawie historii oglądania użytkownika.
- Książki podobne do tych, które znajdują się w historii czytania użytkownika.
- Utwory ulubionych wykonawców użytkownika.
- Oto kilka przykładów spersonalizowanych rekomendacji:
- Można publikować biblioteki treści generowanych przez użytkowników.
- Oto kilka przykładów bibliotek treści generowanych przez użytkowników:
- Lista do obejrzenia użytkownika z aplikacji dewelopera.
- Lista ulubionych wykonawców użytkownika zgłoszona przez niego w aplikacji dewelopera.
- Oto kilka przykładów bibliotek treści generowanych przez użytkowników:
| Typ rekomendacji | Strategia dotycząca aktualności treści | Wskazówki dotyczące aktualności treści |
|---|---|---|
| Spersonalizowane rekomendacje | Lenient Zalecamy aktualizowanie rekomendacji raz dziennie, aby użytkownicy codziennie widzieli nowe rekomendacje. |
Użytkownicy nie mają dokładnych oczekiwań co do treści rekomendacji, dlatego strategia dotycząca aktualności treści może być mniej rygorystyczna. |
| Biblioteki treści generowanych przez użytkowników | Strict Zalecamy aktualizowanie biblioteki treści, gdy użytkownicy opuszczają aplikację dewelopera. |
Ważne jest, aby te treści były zsynchronizowane z danymi wyświetlanymi na platformach Google. Wynika to z tego, że w przeciwieństwie do spersonalizowanych rekomendacji użytkownik oczekuje dokładnego zestawu treści. Znaczne opóźnienie w publikacji może wprowadzić użytkowników w błąd. Dlatego strategia dotycząca aktualności treści musi być rygorystyczna. |
Gdy użytkownik nie jest zalogowany
Jeśli użytkownik nie jest zalogowany w aplikacji dewelopera, nadal zalecamy publikowanie klastrów, aby zachęcić użytkowników do odwiedzenia aplikacji dewelopera z platformy Google.
- Niespersonalizowane klastry rekomendacji powinny być publikowane.
- Oto kilka przykładów niespersonalizowanych rekomendacji:
- 10 najlepszych książek przeczytanych w tym roku.
- Nowe filmy.
- Podcasty zyskujące popularność.
- Oto kilka przykładów niespersonalizowanych rekomendacji:
- Opublikuj kartę logowania.
- Aby zachęcić użytkowników do zalogowania się w aplikacji, deweloperzy mogą opublikować kartę logowania wraz z grupą niespersonalizowanych rekomendacji. Więcej informacji o publikowaniu karty logowania znajdziesz w sekcji poniżej.
| Typ rekomendacji | Strategia dotycząca aktualności treści | Wskazówki dotyczące aktualności treści |
|---|---|---|
| Niespersonalizowane rekomendacje | Lenient Zalecamy aktualizowanie rekomendacji raz dziennie. |
Użytkownicy nie mają dokładnych oczekiwań co do treści rekomendacji, dlatego strategia dotycząca aktualności treści może być mniej rygorystyczna. |
| Karta logowania w rekomendacjach | Strict Zalecamy aktualizowanie stanu karty logowania, gdy użytkownicy opuszczają aplikację dewelopera. Po zalogowaniu się użytkowników deweloperzy muszą usunąć kartę, wywołując interfejs API |
Ważne jest, aby stan logowania był zsynchronizowany z platformą Google. Użytkownik może być zdezorientowany, gdy zobaczy kartę logowania na platformie Google, mimo że jest już zalogowany. Dlatego strategia dotycząca aktualności treści musi być rygorystyczna. |
Klastry kontynuacji
Podczas publikowania klastrów kontynuacji deweloperzy muszą wziąć pod uwagę, czy użytkownik jest zalogowany w aplikacji dewelopera.
Gdy użytkownik jest zalogowany
- Klastry kontynuacji wygenerowane przez użytkowników powinny być publikowane.
- Oto kilka przykładów klastrów kontynuacji wygenerowanych przez użytkowników:
- Kontynuuj oglądanie od miejsca, w którym użytkownik przerwał.
- kontynuowanie czytania od miejsca, w którym użytkownik przerwał;
- Oto kilka przykładów klastrów kontynuacji wygenerowanych przez użytkowników:
| Typ kontynuacji | Strategia dotycząca aktualności treści | Wskazówki dotyczące aktualności treści |
|---|---|---|
| Klastry kontynuacji wygenerowane przez użytkowników | Strict Zalecamy aktualizowanie biblioteki treści, gdy użytkownicy opuszczają aplikację dewelopera. |
Ważne jest, aby te treści były zsynchronizowane z danymi wyświetlanymi na platformach Google. Wynika to z tego, że w przeciwieństwie do spersonalizowanych rekomendacji użytkownik oczekuje dokładnego zestawu treści. Znaczne opóźnienie w publikacji może wprowadzić użytkowników w błąd. Dlatego strategia dotycząca aktualności treści musi być rygorystyczna. |
Gdy użytkownik nie jest zalogowany
Ścieżki kontynuacji są przeznaczone głównie dla zalogowanych użytkowników, ale możesz też publikować klastry kontynuacji dla niezalogowanych użytkowników, jeśli Twoja aplikacja obsługuje sesje gościa.
Klaster zarządzania użytkownikami
Głównym celem klastra zarządzania użytkownikami jest zachęcanie użytkowników do wykonywania określonych działań w aplikacji dostawcy. Działanie logowania kieruje użytkowników na stronę logowania w aplikacji, dzięki czemu aplikacja może publikować treści (lub udostępniać bardziej spersonalizowane treści).
Karta logowania
| 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 | Opcjonalny podtytuł 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()
appEngagePublishClient.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();
appEngagePublishClient.publishUserAccountManagementRequest(
new PublishUserAccountManagementRequest.Builder()
.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
.build());
Po zalogowaniu się użytkowników deweloperzy muszą usunąć kartę, wywołując interfejs API deleteUserManagementCluster().
Aktualizowanie stanu publikacji
Jeśli z jakiegoś powodu wewnętrznego ż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 są publikowane 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 odpowiednich 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, zalecamy opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_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());
WorkManager do publikowania w klastrze
Zalecamy używanie biblioteki WorkManager do publikowania klastrów, ponieważ jest to zalecane rozwiązanie do pracy w tle, która musi być wykonywana zarówno oportunistycznie, jak i niezawodnie.
- WorkManager wykonuje pracę w tle tak szybko, jak to możliwe.
- WorkManager obsługuje logikę rozpoczynania pracy w różnych warunkach, nawet jeśli użytkownik opuści aplikację.
Gdy użytkownik opuści aplikację, zalecamy uruchomienie zadania w tle, które publikuje klastry kontynuacji wraz z klastrami rekomendacji. Dobrym miejscem do obsługi tej logiki jest Activity.onStop(), która jest wywoływana, gdy użytkownik opuszcza aplikację.
Zalecamy użycie PeriodicWorkRequest do zaplanowania cyklicznego zadania, które publikuje klastry co 24 godziny. Używając zasady CANCEL_AND_REENQUEUE do wywoływania zadania, deweloperzy mogą mieć pewność, że WorkManager będzie wysyłać zaktualizowane dane za każdym razem, gdy użytkownik opuści aplikację. Pomaga to zapobiegać wyświetlaniu użytkownikom nieaktualnych danych.
Oto przykład:
// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {
public PublishClusters(Context appContext, WorkerParameters workerParams) {
super(appContext, workerParams);
}
@NonNull
@Override
public Result doWork() {
// publish clusters
}
...
}
public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
.addTag("Publish Clusters to Entertainment Space")
.build();
// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
"publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);
}
Obsługa intencji transmisji
Oprócz wywoływania interfejsu API do publikowania treści za pomocą zadania musisz też skonfigurować BroadcastReceiver, aby otrzymywać żądania publikowania treści.
Deweloperzy muszą jednak uważać, aby nie polegać wyłącznie na transmisjach, ponieważ są one wywoływane tylko w określonych sytuacjach – głównie w przypadku ponownej aktywacji aplikacji i wymuszenia synchronizacji danych. Są one wywoływane tylko wtedy, gdy usługa Engage stwierdzi, że treści mogą być nieaktualne. Dzięki temu użytkownik będzie miał dostęp do aktualnych treści, nawet jeśli aplikacja nie była otwierana przez dłuższy czas.
BroadcastReceiver musi być skonfigurowany na 2 sposoby:
- Dynamicznie zarejestruj instancję klasy
BroadcastReceiverza pomocąContext.registerReceiver(). Umożliwia to komunikację z aplikacjami, które nadal działają w pamięci. - Zadeklaruj statycznie implementację za pomocą tagu
<receiver>w plikuAndroidManifest.xml. Dzięki temu aplikacja może odbierać intencje transmisji, gdy nie jest uruchomiona, a także publikować treści.