本指南說明如何在對話中加入數位交易 採取行動，讓使用者能夠購買您的消耗性數位商品。
重要詞彙：「消耗性」數位商品是庫存管理單位 (SKU)， 使用者可以使用並重複購買，例如指定數量的遊戲代幣 那就是 Android 遊戲這項數位商品與非消耗性產品不同 也就是使用者只能購買一次的數位商品
如要進一步瞭解一次性產品，請參閱 Android 說明文件 一次性產品專屬功能。
交易流程
本指南將概述數位商品中發生的所有開發步驟 交易流程當您的動作處理數位商品交易時， 使用下列流程：
- 設定數位購買交易 API 用戶端：您的動作使用數位版 購買 API，以便與 Google Play 庫存和交易通訊。 在您執行其他動作之前，系統會先建立 JWT 用戶端， 服務金鑰來與 Digital Purchases API 通訊
- 收集資訊：您的動作會收集 和 Google Play 廣告空間，為交易做好萬全準備。
- 建立訂單：您的動作會顯示可用的數位商品： 讓使用者選擇要購買的商品。
- 完成購買：您的動作會使用數位購買 API， 在使用者從 Google Play 商店選擇商品時開始購物。
- 處理結果：您的動作會收到 交易，並通知使用者該購買成功 (或 其他步驟)。
- 進行可重複購買的動作：您的動作使用數位交易。 「使用」的 API客戶購買的商品，接著即可購買該商品 該使用者再次使用服務
限制和評論規範
其他政策適用於「含有交易的動作」。這可能需要一些 並考量包含交易的動作 規劃發布時間表為了減輕審查程序，請務必遵守 使用 交易政策與規範 ，再將動作送交審查。
銷售數位商品的動作只能在下列國家/地區部署：
- 澳洲
- 巴西
- 加拿大
- 印尼
- 日本
- 墨西哥
- 俄羅斯
- 新加坡
- 泰國
- 土耳其
- 英國
- 美國
必要條件
將數位交易納入動作之前，您需要具備 幾項先決條件
A 罩杯 開發人員帳戶 和 商家帳戶 管理您在 Google Play 的 Google Play 管理中心：
意即 在 Google Search Console 中完成驗證。 此網域不需要與公開上線的網站相關聯。 只需要參照你的網域即可
具有
com.android.vending.BILLING的 Android 應用程式 權限 。數位商品將設為「應用程式內購」 。您也必須在 Play 管理中心使用這個應用程式建立版本。 如果您不想公開這個版本，可以建立封閉式 Alpha 版測試 版本。
如果您尚未安裝 Android 應用程式，請按照 建立 Android 應用程式操作說明。
Google Cloud 控制台中的一或多項受管理產品 Google Play 管理中心 也就是透過動作販售的數位商品請注意， 您必須完成設定，才能在 Play 管理中心建立納入管理的產品 Android 應用程式必要條件。
如果您沒有受管理的產品，請按照 「建立數位商品」操作說明。
連結 Android 應用程式
如果您還沒有具備帳單權限的 Android 應用程式， Google Play 管理中心，請按照下列步驟操作：
- 在 Android Studio 或 即可建立新專案選擇以下其中一種語言： 專案設定提示會建立一個非常基本的應用程式
- 為專案指定套件名稱，例如
com.mycompany.myapp。 請勿讓此名稱保持預設值，因為您無法上傳 請在 Play 管理中心加入com.example。 - 開啟應用程式的
AndroidManifest.xml檔案。 在
manifest元素中加入這行程式碼：<uses-permission android:name="com.android.vending.BILLING" />您的
AndroidManifest.xml檔案應如下所示：<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>將應用程式建構為已簽署的 APK。在 Android Studio 中，按照下列步驟操作：
- 依序前往「Build」和「Generate Signed Bundle / APK」。
- 點選「下一步」。
- 在「Key store path」下方，點選「Create new」。
- 填寫每個欄位，然後按一下「確定」。請記下「KeyStore」 和金鑰密碼，並將這些密碼儲存在安全的地方，因為 您稍後會用到這些內容
- 點選「下一步」。
- 選取「release」。
- 選取「V1 (JAR Signature)」。
- 按一下 [完成]。
- 幾秒後，Android Studio 會產生
app-release.apk檔案。 找出這個檔案供日後使用。
在 Google Play 管理中心 建立新的應用程式
前往「應用程式版本」。
在「封閉式測試群組」下方，依序前往「管理」和「Alpha 版」。
按一下「Create Release」按鈕。
在「讓 Google 管理及保護簽署金鑰」下方，輸入您的簽署憑證 重要資訊。
上傳 APK 檔案。
按一下 [儲存]。
建立數位商品
如果您在 Play 管理中心目前沒有數位商品，請按照下列指示操作 步驟：
- 在 Google Play 管理中心 依序前往「應用程式內商品」和「受管理的產品」。如果看到警告訊息 請按照前述操作說明建立 Android 應用程式，或按一下連結 即可建立商家檔案。
- 按一下「建立納入管理的產品」。
- 填寫數位產品的欄位。記下產品 ID 這就是你在動作中參照這項產品的方式
- 按一下 [儲存]。
- 針對您要銷售的每項產品，重複執行步驟 2 到 4。
準備 Actions 專案
在 Google Play 管理中心設定數位商品後，您必須啟用 將您的 Actions 專案與 Play 應用程式建立關聯。
設定
如要在 Actions 專案中啟用數位商品交易功能，請按照下列步驟操作 步驟：
- 在 Actions 主控台中開啟專案或建立新專案。
- 依序前往「部署」和「目錄資訊」。
- 在「其他資訊」和「交易」下方，勾選「是」方塊
「您的動作是否使用 Digital Purchase API 執行交易」
數位商品
- 按一下 [儲存]。
建立數位商品 API 金鑰
如要將要求傳送至 Digital Good API，您必須下載 JSON 服務 帳戶金鑰。
如要擷取服務帳戶金鑰，請按照下列步驟操作：
- 在「動作控制台」中，按一下右上角的三點圖示。 和「專案設定」。
- 找出動作的專案 ID。
- 請前往這個連結，取代「
<project_id>」替換為您的專案 ID：https://console.developers.google.com/apis/credentials?project=project_id - 在主要導覽選單中，前往「憑證」。
- 在顯示的頁面中，依序點選「建立憑證」和「服務」。 帳戶金鑰。
- 前往「Service Account」，然後按一下「New Service Account」。
- 為服務帳戶命名，例如數位交易。
- 按一下「建立」。
- 將角色設定為 專案 >擁有者。
- 按一下「繼續」。
- 按一下 [Create Key] (建立金鑰)。
- 選取「JSON」JSON金鑰類型。
- 按一下「建立金鑰」，然後下載 JSON 服務帳戶金鑰。
請將這個服務帳戶金鑰儲存在安全的地方，您將在 的執行要求，建立 Digital Purchase API 的用戶端。
連結至 Play 廣告空間
如要透過 Actions 專案存取您的數位商品，請將 連結為專案的網域和應用程式 連結資源。
如要將 Play 管理中心的網頁網域和應用程式連結至 Actions 專案，請按照下列步驟操作： 步驟如下：
- 在動作控制台中，依序前往「部署」和「品牌驗證」。
如果尚未連結任何資源，請先連結網站：
- 按一下網站資源 (</>) 按鈕。
- 輸入你的網域網址，然後按一下「連結」。
Google 會傳送電子郵件給 進行驗證 Google Search Console。 收到這封電子郵件的使用者完成這些步驟後，網站應該 「品牌驗證」底下。
擁有至少一個連結網站後，請執行下列步驟， 連結您的 Android 應用程式：
- 在動作控制台中，依序前往「部署」和「品牌驗證」。
- 按一下 [連結應用程式]。
在隨即顯示的頁面中，按照操作說明驗證您的網路 網域。選取哪個 Play 應用程式？ 然後輸入「數位商品」中顯示的網域網址 「品牌驗證」頁面。
Google 再次寄送驗證電子郵件給已驗證的擁有者 網域。管理員核准驗證後，您的 Play 應用程式應該就會 「品牌驗證」底下。
啟用「存取 Play 購買項目」。
建立購買流程
備妥 Actions 專案和數位商品清單後，請建立數位 商品購買流程。
1. 設定 Digital Purchases API 用戶端
在對話執行要求 Webhook 中，透過服務建立 JWT 用戶端
帳戶 JSON 金鑰和
https://www.googleapis.com/auth/actions.purchases.digital 範圍。
下列 Node.js 程式碼會建立數位購買 API 的 JWT 用戶端：
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. 收集資訊
動作會在使用者購物前，收集 使用者能否購物，以及他們提供哪些商品 廣告空間。
2. a.驗證數位購買規定
建議您確認使用者帳戶是否已完成設定
才讓他們選擇購買請
轉換至 DigitalPurchaseCheck 場景，確認使用者已通過驗證
是在允許的途徑 (智慧螢幕、
且所在地區支援數位內容
交易可支援。
如要建立數位購物檢查場景，請按照下列步驟操作：
- 在「Scenes」分頁中，新增名稱為
DigitalPurchaseCheck的新場景。 - 按一下「運算單元填充」下方的「+」來新增運算單元。
- 在「選取類型」下方，選取
actions.type.DigitalPurchaseCheckResult做為 版位類型 - 在版位名稱欄位中，為版位命名
DigitalPurchaseCheck。 - 勾選「自訂運算單元值回傳式曝光」核取方塊 (預設為啟用)。
- 按一下 [儲存]。
數位購物調查會產生以下其中一項結果：
- 若符合這些條件，工作階段參數就會設定成功 條件並繼續讓使用者購買數位商品。
- 如果無法滿足一或多項條件，工作階段參數就會是 但不符合失敗條件在這種情況下， 或離開交易體驗
如要處理數位交易的檢查結果，請按照下列步驟操作：
- 在「Scenes」分頁中，選取新建立的
DigitalPurchaseCheck場景。 - 在「條件」下方，按一下「+」新增條件。
在文字欄位中輸入下列條件語法來檢查 成功條件：
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"將滑鼠遊標懸停在剛剛新增的條件上，然後按一下向上箭頭 放在
if scene.slots.status == "FINAL"之前。啟用「傳送提示」，並提供簡單的提示給使用者 請問：
candidates: - first_simple: variants: - speech: >- You are ready to purchase digital goods.在「Transition」下方選取其他場景，可讓使用者繼續操作 並繼續交易。
選取條件
else if scene.slots.status == "FINAL"。啟用「傳送提示」，並提供簡單的提示給使用者 無法進行交易：
candidates: - first_simple: variants: - speech: Sorry you cannot perform a digital purchase.選取「轉換」下方的「結束對話」即可結束對話。
2. b.收集可用的廣告空間
使用 Digital Purchase API 要求你目前使用的 Play 商店 庫存量，然後將該參數建立成 JSON 物件陣列為每個產品建立 您稍後可以參照這個陣列，向使用者顯示可用的選項 購買。
您的每項數位商品都會以 JSON 格式以 SKU 表示。 以下 Node.js 程式碼概述每個 SKU 的預期格式：
body = {
skus: [
skuId: {
skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
id: string,
packageName: string
}
formattedPrice: string,
title: string,
description: string
]
}
傳送 POST 要求至
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
端點，其中 {packageName} 是應用程式在 Google Play 中的套件名稱
控制台 (例如 com.myapp.digitalgoods)，並將結果格式化為
SKU 物件陣列。
如果只想在結果陣列中擷取特定數位商品，請列出產品
數位商品的 ID (顯示在 Google Play 中各項應用程式內產品下方
控制台)，藉此在 body.ids 中開放購買。
下列 Node.js 程式碼會要求數位商品列出可用的商品清單 購買 API 並將結果格式化為 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': conv.session.id,
'skuType': 'SKU_TYPE_IN_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. 建立訂單
如要開始使用者的數位商品，請列出你的數位商品 方便購買您可以使用各式各樣的 多元的回應類型來代表 並提示使用者做出選擇
以下 Node.js 程式碼會讀取 SKU 物件的庫存陣列，並建立 包含以下項目的清單項目：清單回應 每個：
const items = [];
const entries = [];
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
items.push({
key: key
});
entries.push({
name: key,
synonyms: [],
display: {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
}
});
});
conv.session.typeOverrides = [{
name: 'type_name',
mode: 'TYPE_REPLACE',
synonym: {
entries: entries
}
}];
conv.add(new List({
title: 'List title',
subtitle: 'List subtitle',
items: items,
}));
根據所選使用者建立購買交易
使用者選取項目後，您就可以建立訂單。方法是在 與所選項目相關聯的版位，您只要呼叫 Webhook 即可 建立訂單從執行要求中將訂單資料儲存到工作階段 參數。排序物件會在相同工作階段的不同情境中使用。
conv.session.params.purchase = {
"@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
"skuId": {
"skuType": "<SKU_TYPE_IN_APP>",
"id": "<SKU_ID>",
"packageName": "<PACKAGE_NAME>"
},
"developerPayload": ""
};
在 Actions Builder 中，您可以改用 JSON 編輯器設定運算單元
上述訂單物件這兩種導入方式
CompletePurchaseValueSpec，位於
JSON Webhook 酬載參考資料。
4. 完成購買程序
使用者選取商品後，就能完成交易。填寫完 與所選項目相關聯的版位，您應該要轉換至 並實際完成購買程序
建立完整的購買情境
- 在「Scenes」分頁中，新增名稱為
CompletePurchase的新場景。 - 按一下「運算單元填充」下方的「+」來新增運算單元。
- 在「選取類型」下方，將
actions.type.CompletePurchaseValue設為 版位類型。 - 在版位名稱欄位中，為版位命名
CompletePurchase。 - 勾選「自訂運算單元值回傳式曝光」核取方塊 (預設為啟用)。
- 在「設定運算單元」下方的下拉式選單中選取
Use session parameter。 - 在「設定運算單元」下方，輸入要用於
將訂單儲存在文字欄位中 (即
$session.params.purchase)。
- 按一下 [儲存]。
5. 處理結果
採用 actions.type.CompletePurchaseValue 類型的版位可包含下列內容：
結果：
PURCHASE_STATUS_OK：購買成功。交易 就完成了，因此請結束交易流程 或對話。PURCHASE_STATUS_ALREADY_OWNED：交易失敗，因為使用者 已有該項目請查看使用者的上一個 也無法自行調整顯示的商品 回購他們現有的商品PURCHASE_STATUS_ITEM_UNAVAILABLE：交易失敗，因為 無法提供要求的項目。檢查可用空間來避免這個錯誤 更接近購買時間的 SKU。PURCHASE_STATUS_ITEM_CHANGE_REQUESTED：交易失敗，因為 使用者決定購買其他商品時再次提出訂單建立程序 讓使用者可以立即做出決定。PURCHASE_STATUS_USER_CANCELLED：交易失敗，因為使用者 已取消購買流程。由於使用者過早退出流程 詢問使用者是否要重試交易，或是結束交易 以致於可能必須趕在最後一刻 大幅更動專案，甚至將專案全部取消PURCHASE_STATUS_ERROR：交易失敗，原因不明。 請告知使用者交易失敗，並詢問對方是否要再試一次。PURCHASE_STATUS_UNSPECIFIED：交易失敗，原因不明， 導致狀態不明如要處理這個錯誤狀態，請讓 ，並詢問使用者是否想再試一次。
您應該處理 CompletePurchase 場景中的每筆結果。
- 在「Scenes」分頁中，選取新建立的
CompletePurchase場景。 - 在「條件」下方，按一下「+」新增條件。
在文字欄位中輸入下列條件語法來檢查 成功條件：
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"將滑鼠遊標懸停在剛剛新增的條件上，然後按一下向上箭頭 放在
if scene.slots.status == "FINAL"之前。啟用「傳送提示」，並提供簡單的提示給使用者 請問：
candidates: - first_simple: variants: - speech: >- Your purchase was successful.選取「轉換」下方的「結束對話」即可結束對話。
針對您想支援的每種購買結果類型，重複上述步驟。
6. 提供可重複購買的交易
交易成功後，請傳送 POST 要求給數位交易
API 來消耗商品，讓使用者可以再次購買。傳送你的
要求 https://actions.googleapis.com/v3/conversations/{sessionId}/entitlement:consume
端點和工作階段 ID。session.id
您的 POST 要求也必須包括與
使用者的購買，這項資訊就在使用者的要求 JSON 檔案下方
packageEntitlements.entitlements.inAppDetails.inAppPurchaseData.purchaseToken。
以下程式碼會將 consume 要求傳送至 Digital Purchase API，
回報要求是否成功：
request.post(`https://actions.googleapis.com/v3/conversations/${conv.session.id}/entitlement:consume`, {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {
// This purchase token is in both the purchase event and the user's entitlements
// in their request JSON
"purchaseToken": entitlement.purchaseToken
},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
console.log(JSON.stringify(httpResponse));
console.log(JSON.stringify(body));
resolve(body);
});
// Make sure the consume request was successful. In production, don't notify the user; handle failures on the back end
return consumePromise.then(body => {
const consumed = Object.keys(body).length === 0;
if (consumed) {
conv.add(`You successfully consumed ${id}`);
} else {
conv.add(`Failed to consume: ${id}`);
}
});
反映使用者的購買交易
當使用者查詢您的動作時，要求 JSON 的 user 物件會包含
自己的購買交易清單請查看這項資訊，變更動作的
能夠接收回應
以下範例程式碼顯示要求的 user 物件，其中包含
他們過去 packageEntitlements 的應用程式內購
com.digitalgoods.application 套件：
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "example_session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
"packageEntitlements": [
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "non-consumable.1",
"skuType": "SKU_TYPE_IN_APP"
}
{
"sku": "consumable.2",
"skuType": "SKU_TYPE_IN_APP"
}
]
},
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "annual.subscription",
"skuType": "SKU_TYPE_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=="
}
}
]
}
]
}
},
"homeStructure": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
測試專案
測試專案時，你可以在「Actions」主控台啟用沙箱模式 ，即可在不扣款付款方式的情況下測試動作。 如要啟用沙箱模式，請按照下列步驟操作：
- 在動作控制台中，按一下導覽列的「測試」。
- 按一下 [設定]。
- 啟用「Development Sandbox」選項。