本指南說明如何在數位動作中加入數位訂閱交易，讓使用者能夠購買您的訂閱項目。
重要詞彙：「訂閱」數位商品是一種存留單位 (SKU)，需要向使用者定期收費，例如線上雜誌。這與使用者必須手動重新購買的「消耗性」數位商品不同，或是只會自動購買一次的「非消耗性」數位商品不同。
若要進一步瞭解數位訂閱，請參閱有關訂閱專屬功能的 Android 說明文件。
交易流程
本指南概略說明在數位商品交易流程中發生的開發步驟。當動作處理數位商品的交易時，它會使用以下流程：
- 設定數位購買 API 用戶端：您的動作會使用數位購買 API 與 Google Play 庫存和交易內容通訊。在動作未執行任何動作之前，會先建立具有服務金鑰的 JWT 用戶端，以便與數位購買 API 進行通訊。
- 收集資訊：您的動作會收集使用者和 Google Play 廣告空間的相關基本資訊，為交易做好準備。
- 建立訂單：您的動作會向使用者顯示可用的數位商品，讓使用者選擇要購買的商品。
- 完成購買：您的動作使用數位購買 API，可在使用者前往 Google Play 商店時進行購買交易。
- 處理結果：您的動作會收到交易的狀態碼，並通知使用者購買交易成功 (或採取其他步驟)。
限制和審查規範
且適用於具有交易的動作。我們可能需要數週的時間來審查含有交易的動作，因此在規劃發布時間表時，請將時間納入考量。為了簡化審查程序，請先確認您遵守交易政策和規範，再將動作送交審查。
銷售數位商品的行動僅限在以下國家/地區進行部署：
- 澳洲
- 巴西
- 加拿大
- 印尼
- 日本
- 墨西哥
- 俄羅斯
- 新加坡
- 泰國
- 土耳其
- 英國
- 美國
必要條件
將數位交易納入您的「動作」之前，您必須 遵守下列先決條件：
Google Play 的開發人員帳戶和商家帳戶，可讓您透過 Google Play 管理中心管理數位商品。
在 Google Search Console 中完成驗證的網域。這個網域不需要與公開發布的網站建立關聯，只需要參照您的網域即可。
應用程式在 Google Play 管理中心擁有
com.android.vending.BILLING權限的 Android 應用程式。數位商品將是與這個應用程式在 Google Play 管理中心相關聯的「應用程式內購」項目。您也必須在 Play 管理中心使用這個應用程式建立版本，但如果不想公開該版本，則可建立「封閉式 Alpha 版本」。
如果您還沒有 Android 應用程式，請按照連結 Android 應用程式操作說明進行。
Google Play 管理中心中的一或多個訂閱項目，是您透過「動作」販售的數位商品。請注意，您必須先設定 Android 應用程式，才能在 Play 管理中心建立訂閱項目。
如果您還沒有訂閱項目，請按照建立數位商品操作說明進行。
為 Android 應用程式建立關聯
如果您目前沒有 Android 應用程式，且該帳戶具有 Google Play 管理中心的帳單權限，請按照下列步驟操作：
- 在 Android Studio 或您選擇的 Android IDE 中，建立新專案。在專案設定提示中選擇選項，以建立非常基本的應用程式。
- 為專案命名，例如
com.mycompany.myapp。請勿將此名稱保留預設值，因為您無法將包含com.example的套件上傳至 Play 管理中心。 - 開啟應用程式的
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」(產生已簽署的套件/APK)。
- 按一下「繼續」。
- 在「Key store path」(金鑰存放區路徑) 下方，按一下 [Create new] (新建)。
- 填寫每個欄位，然後按一下 [確定]。請記下您的「Key store password」(金鑰存放區密碼) 和「Key password」(金鑰密碼)，並將這些密碼存放在安全的地方，因為稍後會用到。
- 按一下「繼續」。
- 選取 [發布]。
- 選取 [V1 (JAR Signature)] (V1 (JAR 簽名))。
- 按一下「Finish」。
- 幾秒後，Android Studio 會產生
app-release.apk檔案。尋找這個檔案以供日後使用。
在 Google Play 管理中心建立新的應用程式。
前往應用程式版本。
在「封閉測試群組」下方，依序前往 [管理] 和 [Alpha 版]。
按一下 [建立版本] 按鈕。
在「讓 Google 管理及保護您的簽署金鑰」下方，輸入您的簽署金鑰資訊。
上傳 APK 檔案。
按一下「儲存」。
建立數位商品
如果 Play 管理中心目前沒有數位商品，請按照下列步驟操作：
- 在 Google Play 管理中心中，依序前往「應用程式內產品」和「訂閱項目」。如果您看到警示，請按照先前的操作說明建立 Android 應用程式，或按一下連結來建立商家檔案。
- 按一下「Create Subscription」 (建立訂閱項目)。
- 填寫數位產品的欄位。記下產品 ID， 您需在動作中參照這項產品。
- 按一下「儲存」。
- 為您要銷售的各項產品重複執行步驟 2 到 4。
準備你的 Actions 專案
在 Google Play 管理中心設定數位商品後，您必須啟用數位交易，並將動作專案與 Play 應用程式建立關聯。
設定
如要在動作專案中啟用數位商品交易，請按照下列步驟操作：
- 在動作控制台中開啟您的專案或建立新專案。
- 依序前往 [Deploy] 和 [Directory info]。
- 在「其他資訊」和「交易」下方，勾選「您的動作使用 Digital Purchase API 執行數位商品的交易」下方的「是」方塊。
- 按一下「儲存」。
建立數位商品 API 金鑰
如要傳送要求給數位商品 API，您必須下載與 Actions 主控台專案相關聯的 JSON 服務帳戶金鑰。
如要擷取您的服務帳戶金鑰，請按照下列步驟操作：
- 在「Actions 主控台」中，依序按一下右上角的三點圖示 > [Project settings]。
- 找出動作的專案 ID。
- 請使用這個連結，將「
<project_id>」替換成您的專案 ID：https://console.developers.google.com/apis/credentials?project=project_id - 在主導覽區中前往「憑證」。
- 在出現的頁面中，依序按一下 [建立憑證] 和 [服務帳戶金鑰]。
- 前往 [Service Account] (服務帳戶)，然後按一下 [New Service Account] (新增服務帳戶)。
- 為服務帳戶命名，例如數位交易。
- 按一下「建立」。
- 將「Role」(角色) 設為「Project」>「Owner」(擁有者)。
- 按一下「繼續」。
- 按一下 [Create Key] (建立金鑰)。
- 選取 [JSON] 金鑰類型。
- 按一下 [Create key] (建立金鑰) 並下載 JSON 服務帳戶金鑰。
將這個服務帳戶金鑰存放在安全的地方。您將會在執行要求中使用這組金鑰，為數位購買 API 建立用戶端。
連結至 Play 廣告空間
如要從 Actions 專案存取數位商品，請將網域網域和應用程式與專案建立關聯，做為已連結的資源。
如要將 Play 管理中心網域和應用程式連結至 Actions 專案，請按照下列步驟操作：
- 在動作控制台中，依序前往 [部署] 和 [品牌驗證]。
如果你尚未連結任何資源，請先連結網站：
- 按一下網站資源 (</>) 按鈕。
- 輸入您的網域網址，然後按一下 [連結]。
Google 會傳送一封電子郵件給 Google Search Console 上，由已驗證網域的個人。這封電子郵件的收件者完成這些步驟後，網站就會顯示在「品牌驗證」之下。
連結至少一個網站後，請按照下列步驟連結您的 Android 應用程式：
- 在動作控制台中，依序前往 [部署] 和 [品牌驗證]。
- 按一下 [連結應用程式]。
在隨即顯示的頁面中，按照操作說明在 Play 管理中心驗證您的網域。選取包含您數位商品的 Play 應用程式，然後輸入與「品牌驗證」頁面所示的網域網址完全相同。
再次，Google 會傳送一封驗證電子郵件給該網域的已驗證擁有者。對方核准驗證後，您的 Play 應用程式應該會顯示在「品牌驗證」之下。
啟用 [存取 Play 購買項目]。
建立購買流程
備妥 Actions 專案和數位商品庫存，請在對話執行 Webhook 中建構數位商品購買流程。
1. 設定數位購買 API 用戶端
在對話執行 Webhook 中，使用服務帳戶 JSON 金鑰和 https://www.googleapis.com/auth/actions.purchases.digital 範圍建立 JWT 用戶端。
下列 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 情境，以便檢查使用者是否通過驗證，確認他們是否在允許的介面 (智慧螢幕、智慧型揚聲器或 Android) 中執行交易，且位於支援數位交易的語言代碼。
建立數位購買支票情境的步驟如下：
- 在「場景」分頁中，新增名為
DigitalPurchaseCheck的場景。 - 在「運算單元填充」下方，按一下 [+] 來新增運算單元。
- 在「Select type」(選取類型) 下方，選取
actions.type.DigitalPurchaseCheckResult做為運算單元類型。 - 在運算單元名稱欄位中，為運算單元命名
DigitalPurchaseCheck。 - 啟用「Customize slot value writeback」(自訂運算單元值寫入) 核取方塊 (預設為啟用)。
- 按一下「儲存」。
數位購買檢查將會產生下列其中一種結果：
- 符合條件時，工作階段參數會設定成功條件，而您可以繼續允許使用者購買數位商品。
- 如果無法滿足一或多項條件，則工作階段參數會設定失敗，在這種情況下，您應該將對話轉向交易體驗，或是結束對話。
如要處理數位購買檢查結果，請按照下列步驟操作：
- 在「場景」分頁中，選取新建立的
DigitalPurchaseCheck場景。 - 在「條件」下方按一下「+」來新增條件。
在文字欄位中輸入下列條件語法，檢查是否成功：
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"將遊標懸停在您剛剛新增的條件上，然後按一下向上箭頭，將其放在
if scene.slots.status == "FINAL"之前。啟用 [Send 提示] 並提供簡單的提示，告訴使用者他們已準備好進行交易：
candidates: - first_simple: variants: - speech: >- You are ready to purchase digital goods.在「Transition」底下，選取另一個情境，讓使用者繼續進行對話並繼續交易。
選取條件
else if scene.slots.status == "FINAL"。啟用「Send 提示」並提供簡單的提示，讓使用者知道無法進行交易：
candidates: - first_simple: variants: - speech: Sorry you cannot perform a digital purchase.在「Transition」下方，選取「End 對話」以結束對話。
2. b. 收集可用廣告空間
請使用 Digital Purchase API 要求您目前的 Play 商店庫存資訊，然後針對各項產品建立多個 JSON 物件。您之後會參照此陣列，讓使用者瞭解有哪些購買選項。
您的數位商品都是以 JSON 格式表示。以下 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 物件的陣列。
如果只想在產生的陣列中擷取特定數位商品，請列出要在 body.ids 中購買的數位商品產品 ID (如 Google Play 管理中心各項應用程式內產品所示)。
以下 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': ['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. 建立訂單
如要開始使用者購買數位商品，請列出可供購買的數位商品清單。您可以使用各種豐富回應類型來代表庫存，並提示使用者做出選擇。
下列 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. 完成購買程序
使用者選取商品後，您就可以完成購買程序。填滿與所選項目相關聯的運算單元後，您必須轉換至執行完整購買交易的場景。
建立完整購買場景
- 在「場景」分頁中，新增名為
CompletePurchase的新場景。 - 在「運算單元填充」下方，按一下 [+] 來新增運算單元。
- 在「Select type」(選取類型) 下方，選取
actions.type.CompletePurchaseValue做為運算單元類型。 - 在運算單元名稱欄位中，為運算單元命名
CompletePurchase。 - 勾選 [自訂版位值寫入] 核取方塊 (預設為啟用)。
- 在「Configure slot」(設定運算單元) 下方的下拉式選單中，選取
Use session parameter。 - 在「Configure slot」(設定版位) 下方，在文字欄位中，輸入用於儲存訂單的工作階段參數名稱 (即
$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 場景中的每個結果。
- 在「場景」分頁中，選取新建立的
CompletePurchase場景。 - 在「條件」下方按一下「+」來新增條件。
在文字欄位中輸入下列條件語法，檢查是否成功：
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"將遊標懸停在您剛剛新增的條件上，然後按一下向上箭頭，將其放在
if scene.slots.status == "FINAL"之前。啟用 [Send 提示] 並提供簡單的提示，告訴使用者他們已準備好進行交易：
candidates: - first_simple: variants: - speech: >- Your purchase was successful.在「Transition」(轉換) 下方，選取「End 對話」以結束對話。
針對您想支援的每種購買結果，重複上述步驟。
反映使用者的購買交易
使用者查詢您的操作時，要求的 JSON 物件 user 物件會包含其購買清單。請檢查這項資訊，並根據使用者付費的內容變更動作的回應。
以下程式碼範例顯示某個要求的 user 物件，其中包含之前為 com.digitalgoods.application 套件完成的 packageEntitlements 筆應用程式內購交易：
{
"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"
]
}
}
測試專案
測試專案時，您可以在動作主控台中啟用沙箱模式，以便測試動作而不收費。如要啟用沙箱模式，請按照下列步驟操作：
- 在動作控制台中，按一下導覽中的 [測試]。
- 按一下「設定」。
- 啟用 [Development Sandbox] 選項。