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 belanja mereka, menggunakan Engage SDK untuk mengisi area platform baru ini dan platform Google yang ada seperti Entertainment Space.
Detail integrasi
Terminologi
Integrasi ini mencakup lima jenis cluster berikut: Rekomendasi, Unggulan, Keranjang Belanja, Daftar Belanja, Pesan Ulang, dan Pelacakan Pesanan Belanja.
Cluster Rekomendasi menampilkan saran belanja yang dipersonalisasi dari setiap partner developer. Rekomendasi ini dapat dipersonalisasi untuk pengguna atau digeneralisasi (misalnya item yang sedang trending). Gunakan keduanya untuk menampilkan produk, acara, penjualan, promo, langganan sesuai kebutuhan.
Rekomendasi Anda menggunakan struktur berikut:
Cluster Rekomendasi: Tampilan UI yang berisi kelompok rekomendasi dari partner developer yang sama.
ShoppingEntity: Objek yang mewakili satu item dalam cluster.
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.
Cluster Keranjang Belanja menampilkan cuplikan keranjang belanja dari banyak partner developer dalam satu pengelompokan UI, yang mendorong pengguna untuk menyelesaikan keranjang mereka yang belum terselesaikan. Ada satu cluster Keranjang Belanja yang ditampilkan di dekat bagian atas UI, dengan penempatan prioritas di atas semua cluster Rekomendasi. Setiap partner developer diizinkan untuk menyiarkan hingga 3 instance
ShoppingCart
di cluster Keranjang Belanja.Keranjang Belanja Anda menggunakan struktur berikut:
Cluster Keranjang Belanja: Tampilan UI yang berisi kelompok pratinjau keranjang belanja dari banyak partner developer.
ShoppingCart: Objek yang mewakili pratinjau keranjang belanja untuk satu partner developer, yang akan ditampilkan di cluster Keranjang Belanja.
ShoppingCart
harus menampilkan jumlah total item di keranjang serta dapat menyertakan gambar untuk beberapa item di keranjang pengguna.
Cluster Daftar Belanja menampilkan cuplikan daftar belanja 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.
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.
Cluster Pelacakan Pesanan Belanja menampilkan cuplikan pesanan belanja yang tertunda atau baru saja selesai dari banyak partner developer dalam satu pengelompokan UI, yang memungkinkan pengguna melacak pesanan mereka.
Ada satu cluster ShoppingOrderTracking yang ditampilkan di dekat bagian atas UI, dengan penempatan prioritas di atas semua cluster Rekomendasi. Setiap partner developer diizinkan untuk menyiarkan beberapa item ShoppingOrderTrackingEntity di cluster Pelacakan Pesanan Belanja.
ShoppingOrderTrackingCluster Anda menggunakan struktur berikut:
- Cluster ShoppingOrderTracking: Tampilan UI yang berisi kelompok pratinjau pelacakan pesanan dari banyak partner developer
- ShoppingOrderTrackingEntity: Objek yang mewakili pratinjau pelacakan pesanan belanja untuk satu partner developer, yang akan ditampilkan di cluster Pelacakan Pesanan Belanja. ShoppingOrderTrackingEntity harus menampilkan status pesanan dan waktu pesanan. Sebaiknya isi waktu pengiriman yang diharapkan untuk ShoppingOrderTrackingEntity, karena ditampilkan kepada pengguna saat diberikan.
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'
}
Untuk informasi selengkapnya, lihat Visibilitas paket di Android 11.
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 ShoppingEntity |
Cluster Unggulan | Maksimal 1 | Maksimal 10 ShoppingEntity |
Cluster Keranjang Belanja | Maksimal 1 | Maksimal 3 ShoppingCart
Beberapa keranjang hanya diharapkan untuk aplikasi dengan keranjang terpisah per penjual. |
Cluster Daftar Belanja | Maksimal 1 | Maksimal 1 ShoppingListEntity |
Cluster Pesan Ulang Belanja | Maksimal 1 | Maksimal 1 ReorderEntity |
Cluster Pelacakan Pesanan Belanja | Maksimal 3 | Maksimal 3 ShoppingOrderTrackingEntity |
Langkah 1: Memberikan data entity
SDK telah menentukan entity yang berbeda untuk mewakili setiap jenis item. Entity berikut didukung untuk kategori Belanja:
ShoppingEntity
ShoppingCart
ShoppingList
Reorder
ShoppingOrderTracking
Diagram di bawah ini menguraikan atribut dan persyaratan yang tersedia untuk setiap jenis.
ShoppingEntity
Objek ShoppingEntity
mewakili produk, promosi, transaksi, langganan,
atau acara yang ingin dipublikasikan oleh partner developer.
ShoppingEntity
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 tentang entity. Catatan: Anda dapat menggunakan deep link untuk atribusi. Lihat FAQ ini |
URI |
Judul | Opsional | Nama entity. | Teks bebas Ukuran teks yang direkomendasikan: di bawah 90 karakter (Teks yang terlalu panjang dapat menampilkan elipsis) |
Harga - saat ini | Wajib bersyarat |
Harga entity 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 entity, 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 entity. 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 entity. Catatan: Berikan kolom ini jika Anda tidak menangani logika singkatan tampilan sendiri. Jika Jumlah dan Nilai Jumlah ada, Jumlah 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 yang setelahnya konten tidak lagi ditampilkan di platform. Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform. |
Stempel waktu epoch dalam milidetik |
ShoppingCart
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 kemeja yang sama persis dan 1 topi di keranjang, jumlahnya harus 4. |
Bilangan bulat >= 1 |
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 |
Judul | Opsional | Nama keranjang (misalnya, Tas Belanja Anda). Jika tidak ada nama yang disediakan oleh developer, opsi Keranjang Anda adalah default. Jika partner developer memublikasikan keranjang terpisah per penjual, sertakan nama penjual dalam judul. |
Teks bebas Ukuran teks yang direkomendasikan: di bawah 25 karakter (Teks yang terlalu panjang dapat menampilkan elipsis) |
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) |
Stempel waktu interaksi pengguna terakhir | Opsional | Jumlah milidetik yang berlalu dari epoch, yang mengidentifikasi waktu terakhir
saat pengguna berinteraksi dengan keranjang.
Nilai ini akan diteruskan sebagai input oleh partner developer yang memublikasikan keranjang terpisah per penjual dan mungkin digunakan untuk peringkat. |
Stempel waktu epoch dalam milidetik |
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 yang setelahnya konten tidak lagi ditampilkan di platform. Jika tidak disetel, konten akan memenuhi syarat untuk ditampilkan di platform. |
Stempel waktu epoch dalam milidetik |
ShoppingList
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 disediakan 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) |
ShoppingReorderCluster
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) pada tombol di Pesan 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. |
ShoppingOrderTrackingCluster
Atribut | Persyaratan | Deskripsi | Format |
---|---|---|---|
Judul | Wajib |
Judul singkat paket/item yang dilacak atau nomor pelacakan. |
Teks bebas Ukuran teks yang direkomendasikan: 50 karakter (Teks yang terlalu panjang akan menampilkan elipsis) |
Jenis Pesanan | Wajib |
Judul singkat paket/item yang dilacak atau nomor pelacakan. |
Enum: IN_STORE_PICKUP, SAME_DAY_DELIVERY, MULTI_DAY_DELIVERY |
Status | Wajib |
Status pesanan saat ini. Misalnya: "Terlambat", "Dalam pengiriman", "Tertunda", "Terkirim", "Diterima", "Kehabisan stok", "Pesanan siap" |
Teks bebas Ukuran teks yang direkomendasikan: 25 karakter (Teks yang terlalu panjang akan menampilkan elipsis) |
Waktu Pesanan | Wajib |
Stempel waktu epoch dalam milidetik saat pesanan dilakukan. Waktu pemesanan akan ditampilkan jika periode waktu pengiriman yang diperkirakan tidak ada |
Stempel waktu epoch dalam milidetik |
URI Tindakan | Wajib |
Deep link ke pelacakan pesanan di aplikasi partner. |
URI |
OrderDeliveryTimeWindow (Opsional) - Tetapkan periode waktu untuk pesanan yang sedang dilacak dari saat pesanan dilakukan hingga waktu pengiriman yang diharapkan/aktual. | |||
OrderDeliveryTimeWindow - Start Time | Opsional |
Stempel waktu epoch dalam milidetik pada/setelahnya pesanan akan dikirimkan atau siap diambil. |
Stempel waktu epoch dalam milidetik |
OrderDeliveryTimeWindow - End Time | Opsional |
Stempel waktu epoch dalam milidetik pada/sebelum pesanan akan dikirim atau siap diambil. |
Stempel waktu epoch dalam milidetik |
Gambar poster | Opsional | Gambar satu item/produk yang merupakan bagian dari pesanan. Rasio aspek yang direkomendasikan adalah 1:1 |
Lihat Spesifikasi Gambar untuk panduan. |
Jumlah item | Opsional | Jumlah item dalam pesanan. | Bilangan bulat >= 1 |
Deskripsi | Opsional | Satu paragraf teks untuk menjelaskan item dalam pesanan. Catatan: Deskripsi atau daftar subtitel akan ditampilkan kepada pengguna, bukan keduanya. |
Teks bebas Ukuran teks yang direkomendasikan: 180 karakter |
Daftar subtitel | Opsional | Hingga 3 subtitel, dengan setiap subtitel hanya terdiri dari satu baris teks. Catatan: Deskripsi atau daftar subtitel akan ditampilkan kepada pengguna, bukan keduanya. |
Teks bebas Ukuran teks yang direkomendasikan untuk setiap subtitel: maksimal 50 karakter |
Nilai Pesanan - CurrentPrice | Opsional | Nilai pesanan saat ini. | Teks bebas |
Nomor pesanan | Opsional | Nomor/ID pesanan yang dapat digunakan untuk mengidentifikasi pesanan secara unik. |
Teks bebas Ukuran teks yang direkomendasikan: maks. 25 karakter |
Nomor pelacakan | Opsional | Nomor pelacakan untuk pengiriman pesanan/paket jika pesanan memerlukan pengiriman. |
Teks bebas Ukuran teks yang direkomendasikan: maks. 25 karakter |
Spesifikasi gambar
Spesifikasi yang diperlukan untuk aset gambar tercantum di bawah ini:
Rasio aspek | Piksel minimum | Piksel yang direkomendasikan |
---|---|---|
Persegi (1x1) Lebih cocok untuk cluster non-unggulan |
300x300 | 1200x1200 |
Lanskap (1,91x1) Lebih cocok untuk cluster unggulan |
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).
AppEngageShoppingClient
bertanggung jawab untuk memublikasikan cluster belanja.
API berikut diekspos untuk memublikasikan cluster di klien:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingCarts
publishShoppingList
publishShoppingReorderCluster
publishShoppingOrderTrackingCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
deleteShoppingOrderTrackingCluster
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 ShoppingEntity | Wajib | Daftar objek ShoppingEntity yang membentuk rekomendasi untuk Cluster Rekomendasi ini. |
Judul | Wajib | Judul untuk Cluster Rekomendasi. 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("Black Friday Deals") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Black Friday Deals") .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.
publishShoppingCart
API ini digunakan untuk memublikasikan objek ShoppingCartCluster
.
Kotlin
client.publishShoppingCart( PublishShoppingCartRequest.Builder() .setShoppingCart( ShoppingCart.Builder() ... .build()) .build())
Java
client.publishShoppingCart( new PublishShoppingCartRequest.Builder() .setShoppingCart( new ShoppingCart.Builder() ... .build()) .build())
Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:
- Data
ShoppingCart
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.
publishShoppingCarts
API ini digunakan untuk memublikasikan beberapa objek ShoppingCart
. Hal ini
berlaku untuk partner developer yang memublikasikan keranjang terpisah per penjual. Sertakan
nama penjual dalam judul saat menggunakan API ini.
Kotlin
client.publishShoppingCarts( PublishShoppingCartClustersRequest.Builder() .addShoppingCart( ShoppingCart.Builder() ... .build()) .build())
Java
client.publishShoppingCarts( new PublishShoppingCartClustersRequest.Builder() .addShoppingCart( new ShoppingCart.Builder() ... .build()) .build())
Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:
- Data
ShoppingCart
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.
publishShoppingList
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.
publishShoppingReorderCluster
API ini digunakan untuk memublikasikan objek ShoppingReorderCluster
.
Kotlin
client.publishShoppingReorderCluster( PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( ShoppingReorderCluster.Builder() ... .build()) .build())
Java
client.publishShoppingReorderCluster( new PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( new ShoppingReorderCluster.Builder() ... .build()) .build());
Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:
- Data
ShoppingReorderCluster
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.
publishShoppingOrderTrackingCluster
API ini digunakan untuk memublikasikan objek ShoppingOrderTrackingCluster
.
Kotlin
client.publishShoppingOrderTrackingCluster( PublishShoppingOrderTrackingClusterRequest.Builder() .setShoppingOrderTrackingCluster( ShoppingOrderTrackingCluster.Builder() ... .build()) .build())
Java
client.publishShoppingOrderTrackingCluster( new PublishShoppingOrderTrackingClusterRequest.Builder() .setShoppingOrderTrackingCluster( new ShoppingOrderTrackingCluster.Builder() ... .build()) .build());
Saat layanan menerima permintaan tersebut, tindakan berikut akan terjadi dalam satu transaksi:
- Data
ShoppingOrderTrackingCluster
yang ada dari partner developer akan dihapus. - Data dari permintaan akan diuraikan dan disimpan di Cluster Pelacakan Pesanan Shopping 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.
deleteShoppingCartCluster
API ini digunakan untuk menghapus konten Cluster Keranjang Belanja
Kotlin
client.deleteShoppingCartCluster()
Java
client.deleteShoppingCartCluster();
Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Keranjang Belanja. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.
deleteShoppingListCluster
API ini digunakan untuk menghapus konten Cluster Daftar Belanja.
Kotlin
client.deleteShoppingListCluster()
Java
client.deleteShoppingListCluster();
Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Daftar Belanja. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.
deleteShoppingReorderCluster
API ini digunakan untuk menghapus konten Cluster Pesan Ulang Belanja.
Kotlin
client.deleteShoppingReorderCluster()
Java
client.deleteShoppingReorderCluster();
Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Pesan Ulang Belanja. Jika terjadi error, seluruh permintaan akan ditolak dan status yang ada dipertahankan.
deleteShoppingOrderTrackingCluster
API ini digunakan untuk menghapus konten Cluster Pelacakan Pesanan Belanja.
Kotlin
client.deleteShoppingOrderTrackingCluster()
Java
client.deleteShoppingOrderTrackingCluster();
Saat menerima permintaan, layanan akan menghapus data yang ada dari Cluster Pelacakan Pesanan Belanja. 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.
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(..) .build()) .addOnCompleteListener { task -> if (task.isSuccessful) { // do something } else { val exception = task.exception if (exception is AppEngageException) { @AppEngageErrorCode val errorCode = exception.errorCode if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } }
Java
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 menggunakanContext.registerReceiver()
. Hal ini memungkinkan komunikasi dari aplikasi yang masih aktif dalam memori.
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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast // is received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast // is received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is // received // Trigger shopping order tracking cluster publish when // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER 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)) // Register Featured Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_FEATURED)) // Register Shopping Cart Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART)) // Register Shopping List Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST)) // Register Reorder Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER)) // Register Shopping Order Tracking Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER)) }
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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is // received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is // received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is // received // Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART)); // Register Shopping List Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST)); // Register Reorder Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER)); // Register Shopping Order Tracking Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER)); }
- Deklarasikan penerapan secara statis dengan tag
<receiver>
di fileAndroidManifest.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.shopping.PUBLISH_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER" />
</intent-filter>
</receiver>
</application>
Intent berikut dikirim oleh layanan:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Sebaiknya mulai panggilanpublishRecommendationClusters
saat intent ini diterima.com.google.android.engage.action.PUBLISH_FEATURED
Sebaiknya mulai panggilanpublishFeaturedCluster
saat intent ini diterima.com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART
Sebaiknya mulai panggilanpublishShoppingCart
saat intent ini diterima.com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST
Sebaiknya mulai panggilanpublishShoppingList
saat intent ini diterima.com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER
Sebaiknya mulai panggilanpublishReorderCluster
saat intent ini diterima.com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER
Sebaiknya mulai panggilanpublishShoppingOrderTrackingCluster
saat intent ini diterima.
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 melakukan verifikasi dan peninjauan secara internal untuk memastikan integrasi berfungsi seperti yang diharapkan. Jika diperlukan perubahan, Google akan menghubungi Anda dengan menyertakan 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, Cluster Pesan Ulang, dan Cluster Pelacakan Pesanan Belanja dapat dipublikasikan dan terlihat oleh pengguna.