交易 API 將於 2023 年 5 月 3 日淘汰，並將於 2023 年 6 月 13 日淘汰。詳情請參閱「對話動作已淘汰」。

本頁面由 Cloud Translation API 翻譯而成。

建立數位訂閱交易

本指南說明如何在對話式中新增數位訂閱交易採取行動，讓使用者可以購買您的訂閱項目。

重要詞彙：「訂閱」數位商品是保存單位 (SKU)，要求使用者必須定期付費，例如線上雜誌。這是不同於「消耗性」數位商品，使用者必須手動重新購買或非消耗性數位商品 (即會自動取得) 僅購買一次

如要進一步瞭解數位訂閱，請參閱 Android 說明文件訂閱專屬功能。

交易流程

本指南將概述數位商品中發生的所有開發步驟交易流程當您的動作處理數位商品交易時，使用下列流程：

設定數位購買交易 API 用戶端：您的動作使用數位版購買 API，以便與 Google Play 庫存和交易通訊。在您執行其他動作之前，系統會先建立 JWT 用戶端，服務金鑰來與 Digital Purchases API 通訊
收集資訊：您的動作會收集和 Google Play 廣告空間，為交易做好萬全準備。
1. 驗證交易規定：您的動作使用的是數位版交易需求協助確保使用者能夠完成交易
2. 收集可用廣告空間：您的動作會檢查 Google Play 辨識目前可供購買的商品
建立訂單：您的動作會顯示可用的數位商品：讓使用者選擇要購買的商品。
完成購買：您的動作會使用數位購買 API，讓使用者自行選擇至 Google Play 商店購物。
處理結果：您的動作會收到交易，並通知使用者該購買成功 (或其他步驟)。

限制和評論規範

其他政策適用於「含有交易的動作」。這可能需要一些並考量包含交易的動作規劃發布時間表為了減輕審查程序，請務必遵守使用交易政策與規範，再將動作送交審查。

銷售數位商品的動作只能在下列國家/地區部署：

澳洲
巴西
加拿大
印尼
日本
墨西哥
俄羅斯
新加坡
泰國
土耳其
英國
美國

，瞭解如何調查及移除這項存取權。

必要條件

將數位交易納入動作之前，您需要具備幾項先決條件

A 罩杯開發人員帳戶和商家帳戶管理您在 Google Play 的 Google Play 管理中心：
意即在 Google Search Console 中完成驗證。此網域不需要與公開上線的網站相關聯。只需要參照你的網域即可
具有 com.android.vending.BILLING 的 Android 應用程式權限。數位商品將設為「應用程式內購」。

您也必須在 Play 管理中心使用這個應用程式建立版本。如果您不想公開這個版本，可以建立封閉式 Alpha 版測試版本。

如果您尚未安裝 Android 應用程式，請按照建立 Android 應用程式操作說明。
一或多個訂閱項目中的 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 中，按照下列步驟操作：
1. 依序前往「Build」和「Generate Signed Bundle / APK」。
2. 點選「下一步」。
3. 在「Key store path」下方，點選「Create new」。
4. 填寫每個欄位，然後按一下「確定」。請記下「KeyStore」和金鑰密碼，並將這些密碼儲存在安全的地方，因為您稍後會用到這些內容
5. 點選「下一步」。
6. 選取「release」。
7. 選取「V1 (JAR Signature)」。
8. 按一下 [完成]。
9. 幾秒後，Android Studio 會產生 app-release.apk 檔案。找出這個檔案供日後使用。
在 Google Play 管理中心建立新的應用程式
前往「應用程式版本」。
在「封閉式測試群組」下方，依序前往「管理」和「Alpha 版」。
按一下「Create Release」按鈕。
在「讓 Google 管理及保護簽署金鑰」下方，輸入您的簽署憑證重要資訊。
上傳 APK 檔案。
按一下 [儲存]。

建立數位商品

如果您在 Play 管理中心目前沒有數位商品，請按照下列指示操作步驟：

在 Google Play 管理中心依序前往「應用程式內商品」和「訂閱項目」。如果看到警告訊息請按照前述操作說明建立 Android 應用程式，或按一下連結即可建立商家檔案。
按一下「Create Subscription」 (建立訂閱項目)。
填寫數位產品的欄位。記下產品 ID 這就是你在動作中參照這項產品的方式
按一下 [儲存]。
針對您要銷售的每項產品，重複執行步驟 2 到 4。

Google Play 管理中心的訂閱項目範例。

準備 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 專案，請按照下列步驟操作：步驟如下：

在動作控制台中，依序前往「部署」和「品牌驗證」。
如果尚未連結任何資源，請先連結網站：
1. 按一下網站資源 (</>) 按鈕。
2. 輸入你的網域網址，然後按一下「連結」。
Google 會傳送電子郵件給進行驗證 Google Search Console。收到這封電子郵件的使用者完成這些步驟後，網站應該「品牌驗證」底下。
擁有至少一個連結網站後，請執行下列步驟，連結您的 Android 應用程式：
1. 在動作控制台中，依序前往「部署」和「品牌驗證」。
2. 按一下 [連結應用程式]。
3. 在隨即顯示的頁面中，按照操作說明驗證您的網路網域。選取哪個 Play 應用程式？然後輸入「數位商品」中顯示的網域網址「品牌驗證」頁面。
  
  Google 再次寄送驗證電子郵件給已驗證的擁有者網域。管理員核准驗證後，您的 Play 應用程式應該就會「品牌驗證」底下。
  
  注意： 您的網域會先顯示在 Play 管理中心，然後才會顯示。Actions 主控台可能需要幾天的時間才能完成更新。
4. 啟用「存取 Play 購買項目」。

圖片：顯示與 Actions 專案連結的網站和應用程式。

建立購買流程

備妥 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': ['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. 完成購買程序

使用者選取商品後，就能完成交易。填寫完與所選項目相關聯的版位，您應該要轉換至並實際完成購買程序

建立完整的購買情境

在「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 場景。
在「條件」下方，按一下「+」新增條件。