Transactions API tidak akan digunakan lagi mulai 3 Mei 2023, sebelum penghentian Percakapan Percakapan pada 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Action Percakapan.

Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat transaksi digital habis pakai (Dialogflow)

Panduan ini menjelaskan cara menambahkan transaksi digital ke percakapan Tindakan, agar pengguna dapat membeli produk digital habis pakai Anda.

Istilah utama: Produk digital yang dapat dipakai adalah unit penyimpanan persediaan (SKU) yang pengguna dapat menggunakan dan membeli lebih dari sekali, seperti sejumlah mata uang dalam game untuk game Android. Produk digital ini berbeda dengan produk tidak habis pakai produk digital yang hanya dapat dibeli satu kali.

Untuk informasi selengkapnya tentang produk sekali beli yang dapat dikonsumsi, lihat panduan Android dokumentasi tentang fitur khusus produk sekali beli.

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.
1. Memvalidasi persyaratan transaksi: Action Anda menggunakan format digital bantuan dalam persyaratan transaksi di awal alur pembelian untuk memastikan pengguna dapat bertransaksi.
2. 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 dari Google Play Store.
Menangani hasilnya: Action Anda menerima kode status untuk dan memberi tahu pengguna bahwa pembelian berhasil (atau mengambil langkah tambahan).
Buat pembelian dapat diulang: Action Anda menggunakan pembelian digital API untuk "penggunaan" item yang dibeli, sehingga item tersebut tersedia untuk dibeli oleh pengguna tersebut.

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 produk terkelola di Konsol Google Play, yang merupakan produk digital yang dijual dengan Action Anda. Perlu diperhatikan bahwa Anda tidak dapat membuat produk terkelola di konsol Play sebelum menyiapkan Prasyarat aplikasi Android.

Jika Anda belum memiliki produk terkelola, 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 untuk project, seperti com.mycompany.myapp. Jangan biarkan nama ini sebagai {i>default<i}, karena Anda tidak bisa mengunggah paket yang menyertakan com.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:
1. Buka Build, Generate Signed Bundle / APK.
2. Klik Berikutnya.
3. Di bagian Key store path, klik Create new.
4. 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.
5. Klik Berikutnya.
6. Pilih rilis.
7. Pilih V1 (JAR Signature).
8. Klik Selesai.
9. 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 Produk terkelola. Jika Anda melihat peringatan, ikuti petunjuk sebelumnya untuk membuat aplikasi Android atau klik link untuk membuat profil penjual.
Klik Buat Produk terkelola.
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.

Contoh barang habis pakai di konsol Google Play.

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:
1. Klik tombol properti web (</>).
2. 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:
1. Di Konsol Actions, buka Deploy, lalu Verifikasi merek.
2. Klik Hubungkan Aplikasi.
3. 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.
  
  Catatan: Domain web Anda akan muncul di konsol Play sebelum muncul di Konsol Actions. Mungkin perlu waktu beberapa hari untuk konsol Actions untuk memperbarui.
4. Aktifkan Akses pembelian Play.

Gambar yang menampilkan situs dan aplikasi yang terhubung ke project Actions.

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': ['consumable.1']
      },
    }, (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);
  }
});

6. Membuat pembelian dapat diulang

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
  ]
}

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': ['consumable.1']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

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"
        }
      ]
    }
  ],
  ...
}