Wskazówki dotyczące publikowania klastra SDK w Google Engage

Ten przewodnik zawiera zestaw wytycznych dotyczących publikowania klastrów, których deweloperzy mogą używać podczas integracji z pakietem SDK dla Agencji.

Klastry rekomendacji

Tytuł klastra

Zalecamy podanie niepowtarzalnej i trafnej nazwy klastra, która daje użytkownikom więcej informacji o jego zawartości.

Oto kilka przykładów dobrych nazw klastrów na podstawie treści:

  • Klastry związane z Zakupami
    • Lightning – okazje
    • Zakupy w ciągu tygodnia
    • Związane z zakupem słuchawek Pixel Buds
    • Damskie kalosze
  • Zbiór książek o tematyce zdrowotnej
    • Zdrowie, umysł i ciało
    • Polecane dla Ciebie w aplikacji Zdrowie
    • Bestsellery w kategorii Fitness

Zawartość klastra

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 opublikowanie klastrów treści spersonalizowanych lub wygenerowanych przez użytkownika. Treści spersonalizowane i generowane przez użytkowników są dla nich bardziej przydatne, co zwiększa motywację do odwiedzenia aplikacji dewelopera z poziomu platformy Google.

  • Spersonalizowane rekomendacje mogą być publikowane.
    • Oto kilka przykładów spersonalizowanych rekomendacji:
      • Najczęściej wybierane na podstawie historii oglądania użytkownika.
      • Książki podobne do książek, które znajdują się w historii czytania użytkownika.
      • Utwory ulubionych wykonawców użytkownika.
  • Biblioteki treści użytkowników można publikować.
    • Oto kilka przykładów bibliotek treści użytkowników:
      • Lista obserwowanych notowań użytkownika z aplikacji dewelopera.
      • Zgłoszona przez użytkownika lista ulubionych wykonawców w aplikacji dla deweloperów.
Typ rekomendacji Strategia dotycząca aktualności treści Wytyczne dotyczące aktualności treści
Spersonalizowane rekomendacje

Wygodny

Zalecamy aktualizowanie rekomendacji raz dziennie, aby użytkownicy mogli codziennie wyświetlać nowe.

 Użytkownicy nie mają dokładnie określonego oczekiwania co do treści rekomendacji, więc strategia dotycząca aktualności treści może być łagodna.
Biblioteki treści użytkowników

Ścisły

Zalecamy aktualizowanie biblioteki treści po zamknięciu aplikacji dewelopera.

 Ważne jest, aby te treści były zsynchronizowane z danymi wyświetlanymi w usługach Google. Dzieje się tak, ponieważ w przeciwieństwie do spersonalizowanych rekomendacji użytkownik oczekuje konkretnego zestawu treści. Znaczne opóźnienie publikacji może wprowadzać użytkowników w błąd. Dlatego strategia dotycząca aktualności treści musi być rygorystyczna.

Gdy użytkownik nie jest zalogowany

Nawet jeśli użytkownik nie jest zalogowany w aplikacji dewelopera, nadal zalecamy publikowanie klastrów, aby zachęcali ich do odwiedzenia aplikacji dewelopera z poziomu interfejsu Google.

  • Klastry niespersonalizowanych rekomendacji powinny zostać opublikowane.
    • Oto kilka przykładów niespersonalizowanych rekomendacji:
      • 10 najpopularniejszych książek w tym roku.
      • Nowo wydane filmy.
      • Podcasty zyskujące popularność.
  • Opublikuj kartę logowania.
    • Aby zachęcić użytkowników do logowania się w aplikacji dewelopera, mogą oni opublikować kartę logowania wraz z grupą niespersonalizowanych rekomendacji. W sekcji poniżej znajdziesz więcej informacji o tym, jak opublikować kartę logowania.
Typ rekomendacji Strategia dotycząca aktualności treści Wytyczne dotyczące aktualności treści
Rekomendacje niespersonalizowane

Wygodny

Zalecamy aktualizowanie rekomendacji raz dziennie.

 Użytkownicy nie mają dokładnie określonego oczekiwania co do treści rekomendacji, więc strategia dotycząca aktualności treści może być łagodna.
Rekomendacje związane z kartą logowania

Ścisły

Zalecamy aktualizowanie stanu karty logowania, gdy użytkownicy wychodzą z aplikacji dewelopera.

Po zalogowaniu się użytkownicy muszą usunąć kartę, wywołując interfejs API deleteUserManagementCluster().

Stan logowania musi być zsynchronizowany z usługami Google. Gdy użytkownik jest już zalogowany, w usługach Google może niepewnie znaleźć kartę logowania. 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

  • Należy opublikować wygenerowane przez użytkownika klastry kontynuacji.
    • Oto kilka przykładów klastrów wygenerowanych przez użytkownika:
      • Oglądanie dalej od miejsca, w którym użytkownik przerwał oglądanie.
      • Czytaj dalej od tego samego miejsca.
Typ kontynuacji Strategia dotycząca aktualności treści Wytyczne dotyczące aktualności treści
Klastry kontynuacji wygenerowane przez użytkownika

Ścisły

Zalecamy aktualizowanie biblioteki treści po zamknięciu aplikacji dewelopera.

 Ważne jest, aby te treści były zsynchronizowane z danymi wyświetlanymi w usługach Google. Dzieje się tak, ponieważ w przeciwieństwie do spersonalizowanych rekomendacji użytkownik oczekuje konkretnego zestawu treści. Znaczne opóźnienie publikacji może wprowadzać użytkowników w błąd. Dlatego strategia dotycząca aktualności treści musi być rygorystyczna.

Gdy użytkownik nie jest zalogowany

Kolejne ścieżki są przeznaczone przede wszystkim dla zalogowanych użytkowników. Jeśli jednak Twoja aplikacja obsługuje sesje gościa, możesz też publikować klastry kontynuacji dla niezalogowanych użytkowników.

Klaster zarządzania użytkownikami

Głównym celem klastra zarządzania użytkownikami jest zachęcanie użytkowników do wykonania określonych działań w aplikacji dostawcy. Czynność logowania kieruje użytkowników na stronę logowania w aplikacji, gdzie aplikacja może publikować treści (lub wyświetlać bardziej spersonalizowane treści).

Karta logowania

Atrybut Wymóg Opis
Identyfikator URI działania Wymagane Precyzyjny link do działania (np. do strony logowania w aplikacji)
Obraz Opcjonalnie – jeśli nie podano tytułu, należy podać tytuł

Obraz widoczny na karcie

obrazy o współczynniku proporcji 16 x 9 i rozdzielczości 1264 x 712,
tytuł; Opcjonalnie – jeśli nie podano, należy przesłać obraz. Tytuł na karcie
Tekst działania Opcjonalnie Tekst wyświetlany w wezwaniu do działania (np. „Zaloguj się”)
Podtytuł Opcjonalnie Opcjonalne napisy na karcie

Kotlin


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

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żytkownicy muszą usunąć kartę, wywołując interfejs API deleteUserManagementCluster().

Zaktualizuj stan publikowania

Jeśli z jakichkolwiek wewnętrznych powodów biznesowych nie zostanie opublikowany żaden z klastrów, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu API updatePublishStatus. To ważne, ponieważ :

  • Podanie stanu we wszystkich scenariuszach, nawet po opublikowaniu treści (STAN == OPUBLIKOWANO), ma kluczowe znaczenie przy wypełnianiu paneli, które korzystają z tego jednoznacznego stanu do przekazywania informacji o stanie i innych wskaźnikach integracji.
  • Jeśli treści nie są opublikowane, ale stan integracji nie jest uszkodzony (STATUS == NOT_OpublikujED), Google może uniknąć aktywowania alertów w panelach stanu aplikacji. Jest to potwierdzenie, że treści nie zostały opublikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
  • Dzięki temu deweloperzy mogą określić, kiedy dane są publikowane, a kiedy nie.
  • Google może używać kodów stanu, aby skłonić użytkownika do wykonania określonych działań w aplikacji, co pozwoli mu zobaczyć zawartość aplikacji lub ją przezwyciężyć.

Lista kodów stanu kwalifikującego się do publikacji :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Jeśli treści nie zostały opublikowane, ponieważ użytkownik nie jest zalogowany, zalecamy opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_OpublikujED_REQUIRES_SIGN_IN.

Kotlin


client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java


client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

WorkManager na potrzeby publikowania klastra

Do publikowania klastrów zalecamy korzystanie z narzędzia WorkManager, ponieważ jest to zalecane rozwiązanie w przypadku pracy w tle, w której wykonanie musi być zarówno oportunistyczne, jak i gwarantowane.

  • WorkManager wykonywał pracę w tle tak szybko, jak to możliwe.
  • WorkManager obsługuje logikę, aby rozpocząć pracę w różnych warunkach, nawet jeśli użytkownik wyjdzie z aplikacji.

Gdy użytkownik opuści aplikację, zalecamy uruchomienie zadania w tle, które publikuje klastry kontynuacji razem z klastrami rekomendacji. Dobrym miejscem do obsługi tej logiki jest kod Activity.onStop(), który jest wywoływany, gdy użytkownik opuści aplikację.

Zalecamy użycie PeriodicWorkRequest do planowania zadania cyklicznego, które będzie publikować klastry co 24 godziny. Używając zasady CANCEL_AND_REENQUEUE do aktywowania pracy, deweloperzy mogą mieć pewność, że WorkManager będzie wysyłać zaktualizowane dane za każdym razem, gdy użytkownik opuści aplikację. Dzięki temu użytkownicy nie będą widzieć 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 związanych z transmisją

Oprócz wykonywania wywołań interfejsu Content API w zadaniu musisz też skonfigurować BroadcastReceiver, aby odbierać żądanie opublikowania treści.

Deweloperzy muszą jednak uważać, aby nie polegać wyłącznie na transmisjach, ponieważ są one uruchamiane tylko w niektórych sytuacjach – głównie przy ponownej aktywacji aplikacji i wymuszeniu synchronizacji danych. Są wyzwalane tylko wtedy, gdy usługa Google dla Agencji ustali, że treści mogą być nieaktualne. Dzięki temu masz większą pewność, że użytkownik będzie mógł korzystać z nowych treści, nawet jeśli aplikacja nie była używana przez dłuższy czas.

BroadcastReceiver należy skonfigurować na dwa sposoby:

  • Dynamicznie zarejestruj instancję klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacji, które wciąż są zapisane w pamięci.
  • Statycznie zadeklaruj implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać komunikaty, gdy nie jest uruchomiona, oraz publikować treści.