Panduan ini menjelaskan cara menambahkan transaksi langganan digital ke percakapan Tindakan, agar pengguna dapat membeli langganan Anda.
Istilah utama: Produk digital langganan adalah unit penyimpanan stok (SKU) yang memerlukan tagihan berulang kepada pengguna, seperti majalah {i>online<i}. Ini adalah berbeda dari produk digital yang dapat dipakai, yang harus dilakukan secara manual oleh pengguna pembelian kembali, atau produk digital yang tidak habis pakai yang secara otomatis hanya dibeli sekali.
Untuk informasi selengkapnya tentang langganan digital, lihat panduan Android dokumentasi tentang fitur khusus langganan.
Pembatasan dan panduan peninjauan
Kebijakan tambahan berlaku untuk Tindakan dengan transaksi. Dibutuhkan beberapa minggu untuk meninjau Tindakan yang mencakup transaksi, jadi pertimbangkan waktu tersebut saat merencanakan jadwal rilis. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dengan kebijakan dan panduan untuk transaksi sebelum mengirimkan Action Anda untuk ditinjau.
Action yang menjual produk digital hanya dapat di-deploy di negara-negara berikut:
- Australia
- Brasil
- Kanada
- Indonesia
- Jepang
- Meksiko
- Rusia
- Singapura
- Thailand
- Turki
- Inggris Raya
- Amerika Serikat
Alur transaksi
Panduan ini menguraikan setiap langkah pengembangan saat terjadi pada produk digital untuk seluruh alur transaksi. Ketika Action Anda menangani transaksi untuk produk digital, menggunakan alur berikut:
- Menyiapkan klien API pembelian digital: Action Anda menggunakan klien digital Purchases API untuk berkomunikasi dengan inventaris Google Play Anda dan bertransaksi. Sebelum Action Anda melakukan hal lain, tindakan ini akan membuat klien JWT dengan kunci layanan untuk berkomunikasi dengan Digital Purchases API.
- Kumpulkan informasi: Action Anda mengumpulkan informasi dasar tentang
pengguna dan inventaris Google Play Anda untuk mempersiapkan transaksi.
- Memvalidasi persyaratan transaksi: Action Anda menggunakan format digital bantuan dalam persyaratan transaksi di awal alur pembelian untuk memastikan pengguna dapat bertransaksi.
- Mengumpulkan inventaris yang tersedia: Action Anda memeriksa Google Play Anda inventaris dan mengidentifikasi item apa yang tersedia untuk dibeli saat ini.
- Buat urutan: Action Anda menampilkan produk digital yang tersedia kepada pengguna sehingga mereka dapat memilih produk untuk dibeli.
- Menyelesaikan pembelian: Action Anda menggunakan API pembelian digital untuk memulai pembelian dengan pilihan pengguna ke Google Play Store.
- Menangani hasilnya: Action Anda menerima kode status untuk dan memberi tahu pengguna bahwa pembelian berhasil (atau mengambil langkah tambahan).
Prasyarat
Sebelum menyertakan transaksi digital ke dalam Action, Anda memerlukan prasyarat berikut:
J akun developer dan akun penjual di Google Play, untuk mengelola produk digital Anda di Konsol Google Play.
Domain web yang diverifikasi di Google Search Console. Domain ini tidak perlu dikaitkan dengan situs web yang diluncurkan secara publik, kami hanya perlu mereferensikan domain web Anda.
Aplikasi Android dengan
com.android.vending.BILLING
izin di konsol Google Play. Produk digital Anda akan menjadi "pembelian dalam aplikasi" yang dikaitkan dengan aplikasi ini di Konsol Google Play.Anda juga perlu membuat rilis di konsol Play dengan aplikasi ini, tetapi jika Anda tidak ingin rilis bersifat publik, Anda dapat membuat alfa tertutup rilis.
Jika Anda belum memiliki aplikasi Android, ikuti Kaitkan petunjuk Aplikasi Android.
Satu atau beberapa langganan di Konsol Google Play, yang merupakan produk digital yang dijual dengan Action Anda. Perlu diketahui bahwa Anda tidak dapat membuat langganan di konsol Play sebelum Anda menyiapkan Prasyarat aplikasi Android.
Jika Anda belum memiliki langganan, ikuti Buat petunjuk Produk Digital Anda.
Mengaitkan Aplikasi Android
Jika saat ini Anda tidak memiliki aplikasi Android dengan izin penagihan di Konsol Google Play, ikuti langkah-langkah berikut:
- Di Android Studio atau Android IDE pilihan Anda, buat project baru. Pilih opsi di petunjuk pengaturan proyek untuk membuat aplikasi yang sangat dasar.
- Beri nama paket project, seperti
com.mycompany.myapp
. Jangan biarkan nama ini sebagai {i>default<i}, karena Anda tidak bisa mengunggah paket yang menyertakancom.example
ke konsol Play. - Buka file
AndroidManifest.xml
aplikasi Anda. Tambahkan baris kode berikut di dalam elemen
manifest
:<uses-permission android:name="com.android.vending.BILLING" />
File
AndroidManifest.xml
Anda akan terlihat seperti blok kode berikut:<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" package="com.mycompany.myapp"> <uses-permission android:name="com.android.vending.BILLING" /> <application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:roundIcon="@mipmap/ic_launcher_round" android:supportsRtl="true" android:theme="@style/AppTheme" /> </manifest>
Bangun aplikasi Anda sebagai APK yang ditandatangani. Di Android Studio, ikuti langkah-langkah berikut:
- Buka Build, Generate Signed Bundle / APK.
- Klik Berikutnya.
- Di bagian Key store path, klik Create new.
- Isi setiap kolom, lalu klik OK. Catat Key store Anda sandi dan Sandi kunci, dan menyimpannya di tempat yang aman, karena Anda akan menggunakannya nanti.
- Klik Berikutnya.
- Pilih rilis.
- Pilih V1 (JAR Signature).
- Klik Selesai.
- Setelah beberapa detik, Android Studio akan menghasilkan file
app-release.apk
. Temukan file ini untuk digunakan nanti.
Di kolom Konsol Google Play, membuat aplikasi baru.
Buka Rilis aplikasi.
Di bagian Jalur tertutup, buka Kelola, lalu Alfa.
Klik tombol Buat Rilis.
Di bagian Izinkan Google mengelola dan melindungi kunci penandatanganan Anda, masukkan penandatanganan informasi penting.
Upload file APK Anda.
Klik Simpan.
Membuat Konten Digital
Jika saat ini Anda tidak memiliki produk digital apa pun di konsol Play, ikuti langkah:
- Di kolom Konsol Google Play, buka Produk dalam aplikasi, lalu Langganan. Jika Anda melihat peringatan, ikuti petunjuk sebelumnya untuk membuat aplikasi Android atau klik link untuk membuat profil penjual.
- Klik Buat Langganan.
- Isi kolom untuk produk digital Anda. Catat ID Produk, yaitu cara Anda akan mereferensikan produk ini dari Action Anda.
- Klik Simpan.
- Ulangi langkah 2-4 untuk setiap produk yang ingin Anda jual.
Menyiapkan project Action
Dengan produk digital yang disiapkan di konsol Google Play, Anda harus mengaktifkan transaksi digital dan mengaitkan project Action dengan aplikasi Play.
Untuk mengaktifkan transaksi produk digital dalam project Action Anda, ikuti langkah-langkah berikut langkah:
- Di Konsol Actions, buka project Anda atau buat project baru.
- Buka Deploy, lalu Directory information.
- Di bagian Informasi tambahan dan Transaksi, centang kotak Ya di bagian Apakah Actions Anda menggunakan Digital Purchase API untuk melakukan transaksi produk digital.
- Klik Simpan.
Membuat kunci API barang digital
Untuk mengirim permintaan ke API produk digital, Anda perlu mendownload layanan JSON kunci akun yang terkait dengan project Konsol Actions Anda.
Untuk mengambil kunci akun layanan, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik ikon tiga titik di pojok kanan atas, lalu Project settings.
- Temukan Project ID Action Anda.
- Ikuti link ini, yang menggantikan "
<project_id>
" dengan ID project Anda:https://console.developers.google.com/apis/credentials?project=project_id
- Di navigasi utama, buka Credentials.
- Di halaman yang muncul, klik Create credentials, lalu Service kunci akun.
- Buka Service Account, lalu klik New Service Account.
- Beri nama akun layanan seperti transaksi digital.
- Klik Buat.
- Tetapkan Role ke Project > Pemilik.
- Klik Lanjutkan.
- Klik Buat Kunci.
- Pilih jenis kunci JSON.
- Klik Create key, lalu download kunci akun layanan JSON.
Simpan kunci akun layanan ini di tempat yang aman. Anda akan menggunakan kunci ini di pemenuhan untuk membuat klien untuk API pembelian digital.
Menghubungkan ke inventaris Play
Untuk mengakses produk digital Anda dari project Actions, kaitkan domain web dan aplikasi dengan project Anda properti yang terhubung.
Catatan: Langkah-langkah koneksi mungkin memerlukan waktu hingga 1 minggu untuk diselesaikan selama kami memverifikasi properti Anda. Jika {i>website<i} atau aplikasi Anda tidak ditautkan setelah itu, hubungi dukungan.
Untuk menghubungkan domain web dan aplikasi konsol Play ke project Action Anda, ikuti langkah-langkah berikut:
- Di Konsol Actions, buka Deploy, lalu Verifikasi merek.
Jika Anda belum menghubungkan properti apa pun, hubungkan situs terlebih dahulu:
- Klik tombol properti web (</>).
- Masukkan URL untuk domain web Anda, lalu klik Hubungkan.
Google akan mengirimkan email berisi petunjuk lebih lanjut kepada individu yang diverifikasi untuk domain web tersebut di Google Search Console. Setelah penerima email ini mengikuti langkah-langkah tersebut, situs akan muncul di bagian Verifikasi merek.
Setelah memiliki setidaknya satu situs yang terhubung, lakukan langkah-langkah berikut untuk hubungkan aplikasi Android Anda:
- Di Konsol Actions, buka Deploy, lalu Verifikasi merek.
- Klik Hubungkan Aplikasi.
Di halaman yang muncul, ikuti petunjuk untuk memverifikasi situs Anda domain di Konsol Play. Pilih aplikasi Play yang berisi produk digitalnya, dan masukkan URL domain web persis seperti yang ditampilkan di Halaman Verifikasi merek.
Sekali lagi, Google mengirimkan email verifikasi ke pemilik terverifikasi domain. Setelah mereka menyetujui verifikasi, aplikasi Play Anda akan muncul di bagian Verifikasi merek.
Aktifkan Akses pembelian Play.
Membuat alur pembelian
Dengan menyiapkan project Action dan inventaris produk digital Anda, buat alur pembelian barang di webhook fulfillment percakapan Anda.
1. Menyiapkan klien API pembelian digital
Di webhook fulfillment percakapan Anda, buat klien JWT dengan layanan Anda
kunci JSON akun dan
https://www.googleapis.com/auth/actions.purchases.digital
cakupan.
Kode Node.js berikut membuat klien JWT untuk API pembelian digital:
const serviceAccount = {'my-file.json'};
const request = require('request');
const {google} = require('googleapis');
const jwtClient = new google.auth.JWT(
serviceAccount.client_email, null, serviceAccount.private_key,
['https://www.googleapis.com/auth/actions.purchases.digital'],
null
);
2. Mengumpulkan informasi
Sebelum pengguna dapat melakukan pembelian, Action Anda mengumpulkan informasi tentang kemampuan pengguna untuk melakukan pembelian dan barang apa yang tersedia dari inventaris Anda.
2. a. Memvalidasi persyaratan transaksi
Sebaiknya pastikan akun pengguna disiapkan untuk
transaksi, sebelum memberi mereka
opsi untuk melakukan pembelian. Langkah ini
termasuk memeriksa apakah pengguna telah mengonfigurasi metode pembayaran dan mereka berada di
lokal tempat transaksi digital didukung. Di awal transaksi
alur, gunakan helper DIGITAL_PURCHASE_CHECK
untuk memvalidasi transaksi pengguna
konfigurasi dengan Asisten.
Kode Node.js berikut menggunakan DIGITAL_PURCHASE_CHECK
di awal fungsi
percakapan:
app.intent('Default Welcome Intent', async (conv, { SKU }) => {
// Immediately invoke digital purchase check intent to confirm
// purchase eligibility.
conv.ask(new DigitalPurchaseCheck());
});
Temukan hasil pemeriksaan ini di argumen percakapan sebagai
DIGITAL_PURCHASE_CHECK_RESULT
. Berdasarkan hasil ini, lanjutkan
alur transaksi atau beralih dan meminta mereka untuk memeriksa Google Pay
konfigurasi Anda.
Kode Node.js berikut menangani hasil pemeriksaan persyaratan :
app.intent('Digital Purchase Check', async (conv) => {
const arg = conv.arguments.get('DIGITAL_PURCHASE_CHECK_RESULT');
if (!arg || !arg.resultType) {
conv.close('Digital Purchase check failed. Please check logs.');
return;
}
// User does not meet necessary conditions for completing a digital purchase
if (arg.resultType === 'CANNOT_PURCHASE' || arg.resultType === 'RESULT_TYPE_UNSPECIFIED') {
conv.close(`It looks like you aren't able to make digital purchases. Please check your Google Pay configuration and try again.`);
return;
}
conv.ask('Welcome to the Digital Goods Sample. Would you like to see what I have for sale?');
});
2. b. Mengumpulkan inventaris yang tersedia
Gunakan API pembelian digital untuk meminta Play Store yang saat ini tersedia inventaris, lalu masukkan ke dalam array objek JSON untuk setiap produk. Anda mereferensikan array ini nanti untuk menunjukkan kepada pengguna opsi yang tersedia untuk pembelian.
Setiap produk digital Anda ditampilkan sebagai SKU dalam format JSON. Tujuan kode Node.js berikut menguraikan format yang diharapkan dari setiap SKU:
body = {
skus: [
skuId: {
skuType: one of "APP" or "UNSPECIFIED"
id: string,
packageName: string
}
formattedPrice: string,
title: string,
description: string
]
}
Kirim permintaan POST ke
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
endpoint, dengan {packageName}
adalah nama paket aplikasi Anda di Google Play
Konsol (misalnya, com.myapp.digitalgoods
), lalu format hasilnya menjadi
array objek SKU.
Untuk hanya mengambil produk digital tertentu dalam array yang dihasilkan, cantumkan produk
ID untuk produk digital (seperti yang ditampilkan di setiap produk dalam aplikasi di Google Play
Konsol) yang ingin Anda sediakan untuk dibeli di body.ids
.
Kode Node.js berikut meminta daftar barang yang tersedia dari membeli API dan memformat hasilnya sebagai array SKU:
return jwtClient.authorize((err, tokens) => {
if (err) {
throw new Error(`Auth error: ${err}`);
}
const packageName = 'com.example.projectname';
request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {
'conversationId': conversationId,
'skuType': 'APP',
// This request is filtered to only retrieve SKUs for the following product IDs
'ids': ['annual.subscription']
},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
console.log(JSON.stringify(body));
});
});
});
3. Membuat pesanan
Untuk memulai pembelian digital pengguna, tampilkan daftar produk digital Anda yang tersedia untuk dibeli. Anda dapat menggunakan berbagai jenis respons yang beragam untuk mewakili stok dan meminta pengguna untuk membuat pilihan.
Kode Node.js berikut membaca array inventaris objek SKU dan membuat cantumkan respons dengan satu item daftar untuk masing-masing:
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
list.items[key] = {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
};
});
4. Selesaikan pembelian
Untuk menyelesaikan pembelian, gunakan intent bantuan COMPLETE_PURCHASE
dengan
item yang dipilih pengguna.
Kode Node.js berikut menangani pilihan SKU pengguna dari respons daftar
dan meminta intent COMPLETE_PURCHASE
dengan informasi tersebut:
app.intent('Send Purchase', (conv, params, option) => {
let [skuType, id] = option.split(',');
conv.ask(new CompletePurchase({
skuId: {
skuType: skuType,
id: id,
packageName: <PACKAGE_NAME>,
},
}));
});
5. Menangani hasil
Saat pembelian selesai, pembelian akan memicu actions_intent_COMPLETE_PURCHASE
Peristiwa Dialogflow (atau intent actions.intent.COMPLETE_PURCHASE
Actions SDK) dengan
argumen COMPLETE_PURCHASE_VALUE
yang menjelaskan hasilnya. Membangun intent
dipicu oleh peristiwa ini, yang memberitahukan
hasilnya kepada pengguna.
Tangani kemungkinan hasil pembelian berikut:
PURCHASE_STATUS_OK
: Pembelian berhasil. Transaksi selesai di titik ini, jadi keluarlah dari alur transaksional dan kembali ke percakapan Anda.PURCHASE_STATUS_ALREADY_OWNED
: Transaksi gagal karena pengguna sudah memiliki item tersebut. Hindari error ini dengan memeriksa pembelian dan menyesuaikan item yang ditampilkan sehingga mereka tidak memiliki opsi untuk membeli kembali item yang sudah mereka miliki.PURCHASE_STATUS_ITEM_UNAVAILABLE
: Transaksi gagal karena item yang diminta tidak tersedia. Hindari error ini dengan memeriksa SKU yang mendekati waktu pembelian.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED
: Transaksi gagal karena pengguna memutuskan untuk membeli sesuatu yang lain. Minta ulang dengan membuat pesanan sehingga pengguna dapat segera membuat keputusan lain.PURCHASE_STATUS_USER_CANCELLED
: Transaksi gagal karena pengguna membatalkan alur pembelian. Karena pengguna keluar sebelum waktunya, tanyakan pengguna jika mereka ingin mencoba kembali transaksi atau keluar dari transaksi secara menyeluruh.PURCHASE_STATUS_ERROR
: Transaksi gagal karena alasan yang tidak diketahui. Biarkan pengguna mengetahui bahwa transaksi itu gagal, dan tanyakan apakah mereka ingin mencoba lagi.PURCHASE_STATUS_UNSPECIFIED
: Transaksi gagal karena alasan yang tidak diketahui, yang mengakibatkan status yang tidak diketahui. Tangani status error ini dengan mengizinkan pengguna mengetahui transaksi yang gagal, dan bertanya apakah mereka ingin mencoba lagi.
Kode Node.js berikut membaca argumen COMPLETE_PURCHASE_VALUE
dan
menangani setiap hasil:
app.intent('Purchase Result', (conv) => {
const arg = conv.arguments.get('COMPLETE_PURCHASE_VALUE');
console.log('User Decision: ' + JSON.stringify(arg));
if (!arg || !arg.purchaseStatus) {
conv.close('Purchase failed. Please check logs.');
return;
}
if (arg.purchaseStatus === 'PURCHASE_STATUS_OK') {
conv.close(`Purchase completed! You're all set!`);
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ALREADY_OWNED') {
conv.close('Purchase failed. You already own this item.');
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_UNAVAILABLE') {
conv.close('Purchase failed. Item is not available.');
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_CHANGE_REQUESTED') {
// Reprompt with your item selection dialog
} else {
conv.close('Purchase Failed:' + arg.purchaseStatus);
}
});
Mencerminkan pembelian pengguna
Saat pengguna mengkueri Action Anda, objek user
JSON permintaan akan menyertakan daftar
pembelian mereka. Periksa informasi ini dan ubah respons Action Anda
berdasarkan konten yang
dibayar pengguna.
Kode contoh berikut menunjukkan objek user
permintaan yang menyertakan
packageEntitlements
pembelian dalam aplikasi sebelumnya yang mereka lakukan untuk
Paket com.digitalgoods.application
:
"user": {
"userId": "xxxx",
"locale": "en-US",
"lastSeen": "2018-02-09T01:49:23Z",
"packageEntitlements": [
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "non-consumable.1",
"skuType": "APP"
}
{
"sku": "consumable.2",
"skuType": "APP"
}
]
},
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "annual.subscription",
"skuType": "SUBSCRIPTION",
"inAppDetails": {
"inAppPurchaseData": {
"autoRenewing": true,
"purchaseState": 0,
"productId": "annual.subscription",
"purchaseToken": "12345",
"developerPayload": "HSUSER_IW82",
"packageName": "com.digitalgoods.application",
"orderId": "GPA.233.2.32.3300783",
"purchaseTime": 1517385876421
},
"inAppDataSignature": "V+Q=="
}
}
]
}
]
},
"conversation": {
"conversationId": "1518141160297",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.MAIN",
"rawInputs": [
{
"inputType": "VOICE",
"query": "Talk to My Test App"
}
]
}
],
...
}