Pedoman publikasi Cluster Engage SDK

Panduan ini mencakup serangkaian pedoman untuk publikasi cluster yang dapat digunakan developer saat berintegrasi dengan Engage SDK.

Cluster rekomendasi

Judul Cluster

Sebaiknya berikan judul cluster yang unik dan relevan untuk memberikan lebih banyak insight kepada pengguna tentang konten cluster.

Berikut ini beberapa contoh judul cluster yang baik berdasarkan konten:

  • Cluster terkait Belanja
    • Promo Terbatas
    • Wajib beli untuk mingguan
    • Terkait pembelian Pixel Buds Anda
    • Sepatu bot hujan untuk wanita
  • Kumpulan buku tentang kesehatan
    • Kesehatan, pikiran & tubuh
    • Direkomendasikan untuk Anda dalam Kesehatan
    • Terlaris dalam Kebugaran

Konten Cluster

Saat memublikasikan cluster rekomendasi, developer harus mempertimbangkan apakah pengguna login ke aplikasi developer atau tidak.

Saat pengguna login

Jika pengguna login ke aplikasi developer, sebaiknya publikasikan cluster konten buatan pengguna atau yang dipersonalisasi. Konten yang dipersonalisasi dan konten buatan pengguna lebih relevan bagi pengguna, sehingga mereka lebih termotivasi untuk mengunjungi aplikasi developer dari platform Google.

  • Rekomendasi yang dipersonalisasi dapat dipublikasikan.
    • Berikut ini beberapa contoh rekomendasi yang dipersonalisasi:
      • Pilihan terbaik berdasarkan histori tontonan pengguna.
      • Buku yang serupa dengan buku yang ada di histori bacaan pengguna.
      • Lagu oleh artis favorit pengguna.
  • Library konten buatan pengguna dapat dipublikasikan.
    • Berikut ini beberapa contoh library konten buatan pengguna:
      • Daftar tontonan pengguna dari aplikasi developer.
      • Daftar artis favorit pengguna yang dilaporkan secara mandiri dari aplikasi developer.
Jenis rekomendasi Strategi keaktualan konten Pedoman keaktualan konten
Rekomendasi yang dipersonalisasi

Longgar

Sebaiknya perbarui rekomendasi ini sekali sehari agar pengguna dapat melihat rekomendasi baru setiap hari.

 Karena pengguna tidak memiliki ekspektasi yang pasti tentang konten rekomendasi, strategi keaktualan konten dapat menjadi longgar.
Library konten buatan pengguna

Ketat

Sebaiknya perbarui library konten saat pengguna keluar dari aplikasi developer.

 Konten ini harus disinkronkan dengan data yang ditampilkan di platform Google. Hal ini karena tidak seperti rekomendasi yang dipersonalisasi, pengguna mengharapkan serangkaian konten yang persis. Keterlambatan yang signifikan dalam publikasi akan membingungkan pengguna. Oleh karena itu, strategi keaktualan konten harus ketat.

Jika pengguna tidak login

Jika pengguna tidak login ke aplikasi developer, sebaiknya tetap publikasikan cluster agar pengguna terdorong untuk mengunjungi aplikasi developer dari platform Google.

  • Cluster rekomendasi yang tidak dipersonalisasi harus dipublikasikan.
    • Berikut ini beberapa contoh rekomendasi yang tidak dipersonalisasi:
      • 10 buku teratas yang dibaca tahun ini.
      • Film yang baru dirilis.
      • Podcast yang sedang trending.
  • Memublikasikan kartu login.
    • Untuk mendorong pengguna agar login ke aplikasi developer, developer dapat memilih untuk memublikasikan kartu login bersama dengan cluster rekomendasi yang tidak dipersonalisasi. Baca bagian di bawah untuk detail selengkapnya tentang cara memublikasikan Kartu Login.
Jenis rekomendasi Strategi keaktualan konten Pedoman keaktualan konten
Rekomendasi yang tidak dipersonalisasi

Longgar

Sebaiknya perbarui rekomendasi sekali per hari.

 Karena pengguna tidak memiliki ekspektasi yang pasti tentang konten rekomendasi, strategi keaktualan konten dapat menjadi longgar.
Kartu login di rekomendasi

Ketat

Sebaiknya perbarui status kartu login saat pengguna keluar dari aplikasi developer.

Setelah pengguna login, developer harus menghapus kartu dengan memanggil deleteUserManagementCluster() API.

Status login harus disinkronkan dengan platform Google. Sangat membingungkan bagi pengguna jika mereka melihat kartu login di platform Google padahal mereka sudah login. Oleh karena itu, strategi keaktualan konten harus ketat.

Cluster lanjutan

Saat memublikasikan cluster lanjutan, developer harus mempertimbangkan apakah pengguna login ke aplikasi developer atau tidak.

Saat pengguna login

  • Cluster lanjutan buatan pengguna harus dipublikasikan.
    • Berikut ini beberapa contoh cluster lanjutan buatan pengguna:
      • Lanjutkan Menonton dari bagian terakhir yang ditonton pengguna.
      • Lanjutkan Membaca dari bagian terakhir yang dibaca pengguna.
Jenis lanjutan Strategi keaktualan konten Pedoman keaktualan konten
Cluster lanjutan buatan pengguna

Ketat

Sebaiknya perbarui library konten saat pengguna keluar dari aplikasi developer.

 Konten ini harus disinkronkan dengan data yang ditampilkan di platform Google. Hal ini karena tidak seperti rekomendasi yang dipersonalisasi, pengguna mengharapkan serangkaian konten yang persis. Keterlambatan yang signifikan dalam publikasi akan membingungkan pengguna. Oleh karena itu, strategi keaktualan konten harus ketat.

Jika pengguna tidak login

Perjalanan kelanjutan terutama ditujukan untuk pengguna yang login. Namun, Anda juga dapat memublikasikan cluster kelanjutan untuk pengguna yang logout jika aplikasi Anda mendukung sesi tamu.

Cluster Pengelolaan Pengguna

Tujuan utama dari Cluster Pengelolaan Pengguna adalah mendorong pengguna untuk melakukan tindakan tertentu di aplikasi penyedia. Tindakan login mengarahkan pengguna ke halaman login aplikasi sehingga aplikasi dapat memublikasikan konten (atau memberikan konten yang lebih dipersonalisasi)

Kartu Login

Atribut Persyaratan Deskripsi
URI Tindakan Wajib Deeplink ke Tindakan (yaitu membuka halaman login aplikasi)
Gambar Opsional - Jika tidak diberikan, Judul harus diberikan

Gambar Ditampilkan pada Kartu

Gambar rasio aspek 16x9 dengan resolusi 1264x712
Judul Opsional - Jika tidak diberikan, Gambar harus diberikan Judul pada Kartu
Teks Tindakan Opsional Teks yang Ditampilkan pada CTA (yaitu Login)
Subjudul Opsional Subjudul Opsional pada Kartu

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());

Setelah pengguna login, developer harus menghapus kartu dengan memanggil deleteUserManagementCluster() API.

Memperbarui Status Publikasi

Jika untuk alasan bisnis internal apa pun, tidak ada cluster yang dipublikasikan, sebaiknya perbarui status publikasi menggunakan API updatePublishStatus. Hal ini penting karena:

  • Memberikan status dalam semua skenario, bahkan saat konten dipublikasikan (STATUS == PUBLISHED), sangat penting untuk mengisi dasbor yang menggunakan status eksplisit ini untuk menyampaikan kondisi dan metrik integrasi Anda yang lain.
  • Jika tidak ada konten yang dipublikasikan, tetapi status integrasi tidak rusak (STATUS == NOT_PUBLISHED), Google dapat menghindari pemicuan pemberitahuan di dasbor kondisi aplikasi. Fitur ini mengonfirmasi bahwa konten tidak dipublikasikan karena situasi yang diharapkan dari sudut pandang penyedia.
  • Hal ini membantu developer memberikan analisis tentang kapan data dipublikasikan atau tidak.
  • Google dapat menggunakan kode status untuk mendorong pengguna melakukan tindakan tertentu dalam aplikasi sehingga mereka dapat melihat konten aplikasi atau mengatasinya.

Daftar kode status publikasi yang memenuhi syarat adalah:

// 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

Jika konten tidak dipublikasikan karena pengguna tidak login, sebaiknya publikasikan Kartu Login. Jika karena alasan apa pun penyedia tidak dapat memublikasikan Kartu Login, sebaiknya panggil API updatePublishStatus dengan kode status 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 untuk publikasi cluster

Sebaiknya gunakan WorkManager untuk memublikasikan cluster, karena itu adalah solusi yang direkomendasikan untuk pekerjaan latar belakang yang eksekusinya harus bersifat oportunistik dan dijamin.

  • WorkManager melakukan pekerjaan latar belakang Anda sesegera mungkin.
  • WorkManager menangani logika untuk memulai pekerjaan dalam berbagai kondisi, meskipun pengguna keluar dari aplikasi Anda.

Saat pengguna keluar dari aplikasi, sebaiknya mulai tugas latar belakang yang memublikasikan cluster lanjutan bersama dengan cluster rekomendasi. Tempat yang baik untuk menangani logika ini adalah Activity.onStop(), yang dipanggil saat pengguna keluar dari aplikasi.

Sebaiknya gunakan PeriodicWorkRequest untuk menjadwalkan tugas berulang yang memublikasikan cluster setiap 24 jam. Dengan menggunakan kebijakan CANCEL_AND_REENQUEUE untuk memicu pekerjaan, developer dapat memastikan bahwa WorkManager mengirimkan data yang diperbarui setiap kali pengguna keluar dari aplikasi. Hal ini membantu mencegah pengguna melihat data yang tidak berlaku lagi.

Contoh berikut menunjukkan hal tersebut:

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

}

Menangani intent siaran

Selain melakukan panggilan API publikasi konten melalui tugas, Anda juga harus menyiapkan BroadcastReceiver untuk menerima permintaan publikasi konten.

Namun, developer harus berhati-hati agar tidak hanya mengandalkan siaran, karena siaran hanya dipicu dalam skenario tertentu—terutama untuk pengaktifan kembali aplikasi dan memaksa sinkronisasi data. Siaran hanya dipicu saat Layanan Engage menyimpulkan bahwa konten mungkin tidak berlaku lagi. Dengan demikian, pengguna menjadi lebih yakin bahwa mereka akan mendapatkan pengalaman konten baru, meskipun aplikasi sudah lama tidak dibuka.

BroadcastReceiver harus disiapkan dengan dua cara berikut:

  • Daftarkan instance class BroadcastReceiver secara dinamis menggunakan Context.registerReceiver(). Hal ini memungkinkan komunikasi dari aplikasi yang masih aktif dalam memori.
  • Deklarasikan penerapan secara statis dengan tag <receiver> di file AndroidManifest.xml Anda. Hal ini memungkinkan aplikasi menerima intent siaran ketika tidak sedang berjalan, dan juga memungkinkan aplikasi untuk memublikasikan konten.