Engage SDK Makanan: Petunjuk integrasi teknis pihak ketiga

Google membuat platform di perangkat yang mengatur aplikasi pengguna menurut kategori dan memungkinkan pengalaman imersif baru untuk konsumsi dan penemuan konten aplikasi yang dipersonalisasi. Pengalaman layar penuh ini memberi partner developer peluang untuk menampilkan konten lengkap terbaik di saluran khusus di luar aplikasi mereka.

Panduan ini berisi petunjuk bagi partner developer untuk mengintegrasikan konten makanan mereka, dengan menggunakan Engage SDK untuk mengisi area platform baru ini dan platform Google yang ada.

Detail integrasi

Terminologi

Integrasi ini mencakup lima jenis cluster berikut: Rekomendasi, Unggulan, Keranjang Belanja Makanan, Daftar Belanja Makanan, dan Pesan Ulang.

  • Cluster Rekomendasi menampilkan saran terkait makanan yang dipersonalisasi dari setiap partner developer. Rekomendasi ini dapat dipersonalisasi untuk pengguna atau digeneralisasi (misalnya, barang baru yang didiskon). Gunakan untuk menampilkan resep, toko, hidangan, bahan makanan, dan sebagainya sesuai keinginan Anda.

    • Cluster Rekomendasi dapat dibuat dari listingan ProductEntity, StoreEntity, atau RecipeEntity, tetapi tidak dapat berupa campuran berbagai jenis entity.
    Gambar :`ProductEntity`, `StoreEntity`, dan `RecipeEntity`. (*UI hanya untuk ilustrasi)

  • Cluster Unggulan menampilkan pilihan entity dari beberapa partner developer dalam satu pengelompokan UI. Akan ada satu cluster Unggulan yang ditampilkan di dekat bagian atas UI dengan penempatan prioritas di atas semua cluster Rekomendasi. Setiap partner developer akan diizinkan untuk menyiarkan hingga 10 entity di cluster Unggulan.

    Gambar : Cluster unggulan dengan `RecipeEntity`. (*UI hanya untuk ilustrasi)

  • Cluster Keranjang Belanja Makanan menampilkan cuplikan keranjang belanja bahan makanan dari beberapa partner developer dalam satu pengelompokan UI yang meminta pengguna untuk menyelesaikan transaksi yang belum diproses di keranjang mereka. Ada satu cluster Keranjang Belanja Makanan.

    • Cluster Keranjang Belanja Makanan harus menampilkan jumlah total item dalam keranjang dan juga dapat menyertakan gambar untuk item X dalam keranjang pengguna.

      Gambar: Cluster Keranjang Belanja Makanan dari satu partner. (*UI hanya untuk tujuan ilustrasi)

  • Cluster Daftar Belanja Makanan menampilkan cuplikan daftar belanja bahan makanan dari beberapa partner developer dalam satu pengelompokan UI yang mendorong pengguna untuk kembali ke aplikasi yang sesuai guna memperbarui dan melengkapi daftar mereka. Ada satu cluster Daftar Belanja Makanan.

    Gambar: Cluster Daftar Belanja Makanan dari satu partner. (*UI hanya untuk ilustrasi)

  • Cluster Pesan Ulang menampilkan cuplikan pesanan sebelumnya dari beberapa partner developer dalam satu pengelompokan UI, yang meminta pengguna untuk memesan ulang. Ada satu cluster Pesan Ulang.

    • Cluster Pesan Ulang harus menampilkan jumlah total item dalam pesanan sebelumnya oleh pengguna dan juga harus menyertakan salah satu dari berikut ini:

      • Gambar untuk X item dalam pesanan sebelumnya oleh pengguna.
      • Label untuk X item dalam pesanan sebelumnya oleh pengguna.
    Gambar: Cluster Pemesanan Ulang Makanan dari satu partner. (*UI hanya untuk ilustrasi)

Persiapan

Level API minimum: 19

Tambahkan library com.google.android.engage:engage-core ke aplikasi Anda:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Ringkasan

Desain ini didasarkan pada implementasi layanan terikat.

Data yang dapat dipublikasikan klien tunduk pada batas berikut untuk berbagai jenis cluster:

Jenis cluster Batas cluster Batas maksimum entity dalam cluster
Cluster Rekomendasi Maksimal 5 Maksimal 25 (ProductEntity, RecipeEntity, atau StoreEntity)
Cluster Unggulan Maksimal 1 Maksimal 10 (ProductEntity, RecipeEntity, atau StoreEntity)
Cluster Keranjang Belanja Makanan Maksimal 1 Maksimal 1 ShoppingCartEntity
Cluster Daftar Belanja Makanan Maksimal 1 Maksimal 1 ShoppingListEntity
Cluster Pemesanan Ulang Makanan Maksimal 1 Maksimal 1 ReorderEntity

Langkah 1: Memberikan data entity

SDK telah menentukan entity yang berbeda untuk mewakili setiap jenis item. Kami mendukung entity berikut untuk kategori Makanan:

  1. ProductEntity
  2. StoreEntity
  3. RecipeEntity
  4. FoodShoppingCart
  5. FoodShoppingList
  6. FoodReorderCluster

Diagram di bawah ini menguraikan atribut yang tersedia dan persyaratan untuk setiap jenis.

ProductEntity

Objek ProductEntity mewakili setiap item (seperti item bahan makanan, hidangan dari restoran, atau promosi) yang ingin dipublikasikan oleh partner developer.

Gambar : Atribut ProductEntity

Atribut Persyaratan Deskripsi Format
Gambar poster Wajib Minimal satu gambar harus diberikan. Lihat Spesifikasi Gambar untuk panduan.
URI Tindakan Wajib

Deep link ke halaman di aplikasi yang menampilkan detail produk.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Judul Opsional Nama produk.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 90 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Harga - saat ini Wajib bersyarat

Harga produk saat ini.

Harus diberikan jika harga yang dicoret disediakan.

Teks bebas
Harga - coret Opsional Harga asli entity, yang dicoret di UI. Teks bebas
Keterangan Opsional Keterangan untuk menampilkan promo, acara, atau info terbaru terkait produk, jika tersedia.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Cetak kecil keterangan Opsional Teks cetak kecil untuk keterangan.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Rating (Opsional) - Catatan: Semua rating ditampilkan menggunakan sistem rating bintang standar kami.
Rating - Nilai maks Opsional

Nilai skala rating maksimum.

Harus diberikan jika nilai rating saat ini juga disediakan.

 Angka >= 0,0
Rating - Nilai saat ini Opsional

Nilai skala rating saat ini.

Harus diberikan jika nilai rating maksimum juga disediakan.

 Angka >= 0,0
Rating - Jumlah Opsional

Jumlah rating untuk produk.

Catatan: Berikan kolom ini jika aplikasi Anda mengontrol cara jumlah ditampilkan kepada pengguna. Gunakan string yang ringkas. Misalnya, jika jumlahnya 1.000.000, pertimbangkan untuk menggunakan singkatan seperti 1M agar jumlahnya tidak terpotong pada ukuran tampilan yang lebih kecil.

 String
Rating - Nilai Jumlah Opsional

Jumlah rating untuk produk.

Catatan: Berikan kolom ini jika Anda tidak menangani logika singkatan tampilan sendiri. Jika Jumlah dan Nilai Jumlah ada, Jumlah akan ditampilkan kepada pengguna.

 Panjang
DisplayTimeWindow (Opsional) - Menetapkan periode waktu untuk konten yang akan ditampilkan di platform
Stempel Waktu Awal Opsional

Stempel waktu epoch yang setelahnya konten akan ditampilkan di platform.

Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform.

 Stempel waktu epoch dalam milidetik
Stempel Waktu Akhir Opsional

Stempel waktu epoch setelah konten tidak lagi ditampilkan di platform.

Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform.

 Stempel waktu epoch dalam milidetik

StoreEntity

Objek StoreEntity mewakili setiap toko yang ingin dipublikasikan oleh partner developer, seperti restoran atau minimarket.

Gambar : Atribut StoreEntity

Atribut Persyaratan Deskripsi Format
Gambar poster Wajib Minimal satu gambar harus diberikan. Lihat Spesifikasi Gambar untuk panduan.
URI Tindakan Wajib

Deep link ke halaman di aplikasi yang menampilkan detail toko.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Judul Opsional Nama toko.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Lokasi Opsional Lokasi toko.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Keterangan Opsional Keterangan untuk menampilkan promo, acara, atau info terbaru terkait toko, jika tersedia.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Cetak kecil keterangan Opsional Teks cetak kecil untuk keterangan.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Deskripsi Opsional Deskripsi toko.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 90 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Kategori Opsional

Kategori toko, dalam konteks tempat makan, dapat berupa masakan seperti "Prancis", "Amerika baru", "ramen", "makanan mewah".

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Catatan: Semua rating ditampilkan menggunakan sistem rating bintang standar kami.
Rating - Nilai maks Opsional

Nilai skala rating maksimum.

Harus diberikan jika nilai rating saat ini juga disediakan.

 Angka >= 0,0
Rating - Nilai saat ini Opsional

Nilai skala rating saat ini.

Harus diberikan jika nilai rating maksimum juga disediakan.

 Angka >= 0,0
Rating - Jumlah Opsional

Jumlah rating untuk toko.

Catatan: Berikan kolom ini jika aplikasi Anda ingin mengontrol cara tampilannya kepada pengguna. Berikan string ringkas yang dapat ditampilkan kepada pengguna. Misalnya, jika jumlahnya 1.000.000, pertimbangkan untuk menggunakan singkatan seperti 1M, sehingga tidak akan terpotong pada ukuran tampilan yang lebih kecil.

 String
Rating - Nilai Jumlah Opsional

Jumlah rating untuk toko.

Catatan: Berikan kolom ini jika Anda tidak ingin menangani logika singkatan tampilan sendiri. Jika Count dan Count Value ada, kami akan menggunakan Count untuk ditampilkan kepada pengguna

 Panjang

RecipeEntity

Objek RecipeEntity mewakili item resep yang ingin dipublikasikan oleh partner developer.

Gambar : Atribut RecipeEntity

Atribut Persyaratan Deskripsi Format
Gambar poster Wajib Minimal satu gambar harus diberikan. Lihat Spesifikasi Gambar untuk panduan.
URI Tindakan Wajib

Deep link ke halaman di aplikasi yang menampilkan detail resep.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Judul Opsional Nama resep.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Penulis Opsional Penulis resep.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Waktu Memasak/Persiapan Opsional Waktu memasak resep.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Keterangan Opsional Keterangan yang menampilkan promo, acara, atau info terbaru terkait resep, jika tersedia.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Kategori Opsional Kategori resep.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 45 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Deskripsi Opsional Deskripsi resep.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 90 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Catatan: Semua rating ditampilkan menggunakan sistem rating bintang standar kami.
Rating - Nilai maks Opsional

Nilai skala rating maksimum.

Harus diberikan jika nilai rating saat ini juga disediakan.

 Angka >= 0,0
Rating - Nilai saat ini Opsional

Nilai skala rating saat ini.

Harus diberikan jika nilai rating maksimum juga disediakan.

 Angka >= 0,0
Rating - Jumlah Opsional

Jumlah rating untuk resep.

Catatan: Berikan kolom ini jika aplikasi Anda ingin mengontrol cara tampilannya kepada pengguna. Berikan string ringkas yang dapat ditampilkan kepada pengguna. Misalnya, jika jumlahnya 1.000.000, pertimbangkan untuk menggunakan singkatan seperti 1M, sehingga tidak akan terpotong pada ukuran tampilan yang lebih kecil.

 String
Rating - Nilai Jumlah Opsional

Jumlah rating untuk resep.

Catatan: Berikan kolom ini jika Anda tidak ingin menangani logika singkatan tampilan sendiri. Jika Count dan Count Value ada, kami akan menggunakan Count untuk ditampilkan kepada pengguna

 Panjang

FoodShoppingCart

Gambar: Atribut cluster Keranjang Belanja Makanan.

Atribut Persyaratan Deskripsi Format
URI Tindakan Wajib

Deep link ke keranjang belanja di aplikasi partner.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Jumlah item Wajib

Jumlah item (bukan hanya jumlah produk) di keranjang belanja.

Misalnya: Jika ada 3 jeruk dan 1 apel di keranjang, jumlahnya harus 4.

 Bilangan bulat >= 1
Judul Opsional

Nama keranjang (misalnya, Keranjang Anda).

Jika tidak ada nama yang disediakan oleh developer, opsi Keranjang Anda adalah default.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 25 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Teks Tindakan Opsional

Teks pesan ajakan (CTA) pada tombol di Keranjang Belanja (misalnya, Tas Belanja Anda).

Jika tidak ada teks tindakan yang disediakan developer, Lihat Keranjang adalah default.

Atribut ini didukung dalam versi 1.1.0 dan seterusnya.

String
Gambar keranjang Opsional

Gambar setiap produk di keranjang.

Maksimal 10 gambar dapat diberikan sesuai urutan prioritas. Jumlah gambar sebenarnya yang ditampilkan akan bergantung pada faktor bentuk perangkat.

 Lihat Spesifikasi Gambar untuk panduan.
Label item Opsional

Daftar label untuk item di daftar belanja.

Jumlah label sebenarnya yang ditampilkan bergantung pada faktor bentuk perangkat.

Daftar label teks bebas

Ukuran teks yang direkomendasikan: di bawah 20 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
DisplayTimeWindow (Opsional) - Menetapkan periode waktu untuk konten yang akan ditampilkan di platform
Stempel Waktu Awal Opsional

Stempel waktu epoch yang setelahnya konten akan ditampilkan di platform.

Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform.

 Stempel waktu epoch dalam milidetik
Stempel Waktu Akhir Opsional

Stempel waktu epoch setelah konten tidak lagi ditampilkan di platform.

Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform.

 Stempel waktu epoch dalam milidetik

FoodShoppingList

Gambar: Cluster Daftar Belanja Makanan.

Atribut Persyaratan Deskripsi Format
URI Tindakan Wajib

Deep link ke daftar belanja di aplikasi partner.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Jumlah item Wajib Jumlah item dalam daftar belanja. Bilangan bulat >= 1
Judul Opsional

Judul daftar (misalnya, Daftar Belanjaan Anda).

Jika tidak ada judul yang diberikan oleh developer, Daftar belanja adalah default.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 25 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Label item Wajib

Daftar label untuk item di daftar belanja.

Setidaknya 1 label harus disediakan dan maksimal 10 label dapat diberikan sesuai urutan prioritas. Jumlah label sebenarnya yang ditampilkan bergantung pada faktor bentuk perangkat.

Daftar label teks bebas

Ukuran teks yang direkomendasikan: di bawah 20 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)

FoodReorderCluster

Gambar: Cluster Pemesanan Ulang Makanan.

Atribut Persyaratan Deskripsi Format
URI Tindakan Wajib

Deep link untuk memesan ulang di aplikasi partner.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

URI
Teks Tindakan Opsional

Teks pesan ajakan (CTA) tombol di Urutkan Ulang (misalnya, Pesan lagi).

Jika tidak ada teks tindakan yang disediakan developer, Pesan Ulang adalah default.

Atribut ini didukung dalam versi 1.1.0 dan seterusnya.

String
Jumlah item Wajib

Jumlah item (bukan hanya jumlah produk) dalam pesanan sebelumnya.

Misalnya: Jika pesanan sebelumnya adalah 3 kopi kecil dan 1 croissant, jumlahnya harus 4.

Bilangan bulat >= 1
Judul Wajib Judul item pemesanan ulang.

Teks bebas

Ukuran teks yang direkomendasikan: di bawah 40 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Label item

Opsional

(Jika tidak diberikan, gambar poster harus disediakan)

Daftar label item untuk pesanan sebelumnya.

Maksimal 10 label dapat diberikan sesuai urutan prioritas. Jumlah label sebenarnya yang ditampilkan bergantung pada faktor bentuk perangkat.

Daftar teks bebas

Ukuran teks yang direkomendasikan per label: di bawah 20 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Gambar poster

Opsional

(Jika tidak diberikan, label item harus disediakan)

Gambar item dalam pesanan sebelumnya.

Maksimal 10 gambar dapat diberikan sesuai urutan prioritas. Jumlah gambar sebenarnya yang ditampilkan akan bergantung pada faktor bentuk perangkat.

 Lihat Spesifikasi Gambar untuk panduan.

Spesifikasi gambar

Spesifikasi yang diperlukan untuk aset gambar tercantum di bawah ini:

Rasio aspek Piksel minimum Piksel yang direkomendasikan

Persegi (1x1)

Pilihan

 300x300 1200x1200
Lanskap (1,91x1) 600x314 1200x628
Potret (4x5) 480x600 960x1200

Format file

PNG, JPG, GIF statis, WebP

Ukuran file maksimum

5120 KB

Rekomendasi tambahan

  • Area aman gambar: Tempatkan konten penting Anda di 80% bagian tengah gambar.
  • Gunakan latar belakang transparan agar gambar dapat ditampilkan dengan benar di setelan tema Gelap dan Terang.

Langkah 2: Menyediakan data Cluster

Sebaiknya jalankan tugas publikasi konten di latar belakang (misalnya, menggunakan WorkManager) dan dijadwalkan secara berkala atau berbasis peristiwa (misalnya, setiap kali pengguna membuka aplikasi atau saat pengguna menambahkan sesuatu ke keranjangnya).

AppEngageFoodClient bertanggung jawab untuk memublikasikan cluster makanan.

Ada API berikut untuk memublikasikan cluster di klien:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishFoodShoppingCart
  • publishFoodShoppingList
  • publishReorderCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteFoodShoppingCartCluster
  • deleteFoodShoppingListCluster
  • deleteReorderCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

API ini digunakan untuk memeriksa apakah layanan tersedia untuk integrasi, dan apakah konten dapat ditampilkan di perangkat atau tidak.

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

API ini digunakan untuk memublikasikan daftar objek RecommendationCluster.

Objek RecommendationCluster dapat memiliki atribut berikut:

Atribut Persyaratan Deskripsi
Daftar ProductEntity, StoreEntity, atau RecipeEntity Wajib Daftar entity yang membentuk rekomendasi untuk Cluster Rekomendasi ini. Entity dalam satu cluster harus memiliki jenis yang sama.
Judul Wajib

Judul untuk Cluster Rekomendasi (misalnya, Penghematan besar pada menu Thanksgiving).

Ukuran teks yang direkomendasikan: di bawah 25 karakter (Teks yang terlalu panjang dapat menampilkan elipsis)
Subjudul Opsional Subjudul untuk Cluster Rekomendasi.
URI Tindakan Opsional

Deep link ke halaman di aplikasi partner tempat pengguna dapat melihat daftar rekomendasi lengkap.

Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build());

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Semua data Cluster Rekomendasi yang ada akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster Rekomendasi baru.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

publishFeaturedCluster

API ini digunakan untuk memublikasikan objek FeaturedCluster.

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Data FeaturedCluster yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster Unggulan yang diperbarui.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

publishFoodShoppingCart

API ini digunakan untuk memublikasikan objek FoodShoppingCart.

Kotlin

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Data FoodShoppingCart yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster Keranjang Belanja yang diupdate.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

publishFoodShoppingList

API ini digunakan untuk memublikasikan objek FoodShoppingList.

Kotlin

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Data FoodShoppingList yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster Daftar Belanja yang diupdate.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

publishReorderCluster

API ini digunakan untuk memublikasikan objek FoodReorderCluster.

Kotlin

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Data FoodReorderCluster yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster Pesan Ulang yang telah diupdate.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

publishUserAccountManagementRequest

API ini digunakan untuk memublikasikan kartu Login. Tindakan login mengarahkan pengguna ke halaman login aplikasi sehingga aplikasi dapat memublikasikan konten (atau memberikan konten yang lebih dipersonalisasi)

Metadata berikut adalah bagian dari 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()

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

Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:

  • Data UserAccountManagementCluster yang ada dari partner developer akan dihapus.
  • Data dari permintaan akan diuraikan dan disimpan di Cluster UserAccountManagementCluster yang diperbarui.

Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

updatePublishStatus

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, Google merekomendasikan untuk memublikasikan 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());

deleteRecommendationClusters

API ini digunakan untuk menghapus konten Cluster Rekomendasi.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Rekomendasi. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteFeaturedCluster

API ini digunakan untuk menghapus konten Cluster Unggulan.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Unggulan. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteFoodShoppingCartCluster

API ini digunakan untuk menghapus konten Cluster Keranjang Belanja Makanan.

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Keranjang Belanja Makanan. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteFoodShoppingListCluster

API ini digunakan untuk menghapus konten Cluster Daftar Belanja Makanan.

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Daftar Belanja Makanan. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteReorderCluster

API ini digunakan untuk menghapus konten FoodReorderCluster.

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Pesan Ulang. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteUserManagementCluster

API ini digunakan untuk menghapus konten Cluster UserAccountManagement.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster UserAccountManagement. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

deleteClusters

API ini digunakan untuk menghapus konten jenis cluster tertentu.

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

Saat menerima permintaan tersebut, layanan akan menghapus data yang ada dari semua cluster yang cocok dengan jenis cluster yang ditentukan. Klien dapat memilih untuk meneruskan satu atau beberapa jenis cluster. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.

Penanganan error

Sangat disarankan untuk memproses hasil tugas dari API publikasi sehingga tindakan lanjutan dapat diambil untuk memulihkan dan mengirim ulang tugas yang berhasil.

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

Error akan ditampilkan sebagai AppEngageException dengan penyebab disertakan sebagai kode error.

Kode error Nama error Catatan
1 SERVICE_NOT_FOUND Layanan tidak tersedia di perangkat yang ditentukan.
2 SERVICE_NOT_AVAILABLE Layanan tersedia di perangkat tertentu, tetapi tidak tersedia pada saat panggilan (misalnya, dinonaktifkan secara eksplisit).
3 SERVICE_CALL_EXECUTION_FAILURE Eksekusi tugas gagal karena masalah threading. Dalam hal ini, tindakan tersebut dapat dicoba lagi.
4 SERVICE_CALL_PERMISSION_DENIED Pemanggil tidak diizinkan untuk melakukan panggilan layanan.
5 SERVICE_CALL_INVALID_ARGUMENT Permintaan berisi data yang tidak valid (misalnya, lebih dari jumlah cluster yang diizinkan).
6 SERVICE_CALL_INTERNAL Terjadi error di sisi layanan.
7 SERVICE_CALL_RESOURCE_EXHAUSTED Panggilan layanan terlalu sering dilakukan.

Langkah 3: Menangani intent siaran

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

Tujuan intent siaran terutama untuk pengaktifan kembali aplikasi dan memaksa sinkronisasi data. Intent siaran tidak didesain untuk dikirim terlalu sering. Intent itu hanya dipicu jika Layanan Engage menyimpulkan bahwa konten mungkin sudah tidak berlaku (misalnya, seminggu yang lalu). Dengan demikian, pengguna menjadi lebih yakin bahwa mereka dapat memiliki pengalaman konten baru meskipun aplikasi tidak dijalankan dalam waktu yang lama.

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.
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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received

// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));

}
  • 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.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
   </receiver>
</application>

Intent berikut akan dikirimkan oleh layanan:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Sebaiknya mulai panggilan publishRecommendationClusters saat menerima intent ini.
  • com.google.android.engage.action.PUBLISH_FEATURED Sebaiknya mulai panggilan publishFeaturedCluster saat menerima intent ini.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART Sebaiknya mulai panggilan publishFoodShoppingCart saat menerima intent ini.
  • com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST Sebaiknya mulai panggilan publishFoodShoppingList saat menerima intent ini.
  • com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER Sebaiknya mulai panggilan publishReorderCluster saat menerima intent ini.

Alur kerja integrasi

Untuk panduan langkah demi langkah cara memverifikasi integrasi Anda setelah selesai, lihat Alur kerja integrasi developer untuk Engage.

FAQ

Lihat Pertanyaan Umum tentang Engage SDK untuk mengetahui FAQ.

Kontak

Hubungi engage-developers@google.com jika ada pertanyaan selama proses integrasi. Tim kami akan membalas sesegera mungkin.

Langkah berikutnya

Setelah menyelesaikan integrasi ini, langkah-langkah Anda berikutnya adalah sebagai berikut:

  • Kirim email ke engage-developers@google.com dan lampirkan APK terintegrasi yang siap diuji oleh Google.
  • Google akan melakukan verifikasi dan meninjau secara internal untuk memastikan integrasi berfungsi seperti yang diharapkan. Jika perlu perubahan, Google akan menghubungi Anda dengan detail yang diperlukan.
  • Setelah pengujian selesai dan tidak ada perubahan yang diperlukan, Google akan menghubungi Anda untuk memberi tahu bahwa Anda dapat mulai memublikasikan APK yang diupdate dan terintegrasi ke Play Store.
  • Setelah Google mengonfirmasi bahwa APK yang diupdate telah dipublikasikan ke Play Store, cluster Rekomendasi, Unggulan, Keranjang Belanja, Daftar Belanja, dan Pesan Ulang akan dipublikasikan dan terlihat oleh pengguna.