Transactions API のサポートは 2023 年 6 月 13 日に終了します。2023 年 5 月 3 日に終了します。詳細については、会話型アクションの廃止をご覧ください。

このページは Cloud Translation API によって翻訳されました。

消費可能なデジタルトランザクションを構築する（Dialogflow）

このガイドでは、会話にデジタルトランザクションを追加する方法について説明しますアクション: ユーザーが消費可能なデジタル商品を購入できるようにします。

主な用語: 消費型デジタルアイテムとは、 1 人のユーザーが複数回（ゲーム内通貨の数量など）を使用および購入できる考えてみましょうこのデジタルアイテムは、非消費型アイテムとは異なります 1 人のユーザーが 1 回しか購入できないデジタルアイテム。

消費可能な 1 回限りのアイテムについて詳しくは、関連ドキュメント 1 回限りのアイテム固有の機能。

制限と審査のガイドライン

取引を伴うアクションには追加のポリシーが適用されます。この処理には取引を含むアクションをレビューするために何週間も費やす必要があります公開スケジュールの計画審査プロセスを容易にするため、新しい取引に関するポリシーとガイドライン提出してください。

デジタル商品を販売するアクションは、次の国でのみデプロイできます。

オーストラリア
ブラジル
カナダ
インドネシア
日本
メキシコ
ロシア
シンガポール
タイ
トルコ
英国
米国

で確認できます。

取引の流れ

このガイドでは、デジタル商品で行われる各開発ステップについて概説します。トランザクションフローを実行しますアクションがデジタル商品の取引を処理する場合、次のフローを使用します。

Digital Purchases API クライアントを設定する: アクションでデジタル版の購入 API を使用して Google Play の広告枠と通信し、取引できます。アクションは他の処理を行う前に、JWT クライアントを作成し、 Digital Purchases API と通信するためのサービスキーを提供します。
Getting information（情報を収集する）: アクションは、アクティビティに関する基本情報を収集します。 Google Play の広告枠で取引の準備をします。
1. 取引要件を検証する: アクションはデジタル購入フローの開始時に取引要件ヘルパーを追加しそのユーザーが取引できるようにします
2. 利用可能な広告枠を収集する: アクションで Google Play を確認します。在庫を調べて、現在購入可能な商品を特定します。
注文を作成する: アクションは購入可能なデジタル商品を購入する商品をユーザーが選択できます。
購入を完了する: アクションは Digital Purchases API を使用して購入を完了します。ユーザーが Google Play ストアから選択したアイテムで購入を開始する。
結果を処理する: アクションは、返された結果のステータスコードを受け取ります。購入が正常に完了したことをユーザーに通知（または追加手順）があります。
繰り返し購入できるようにする: アクションはデジタル購入を使用します。「消費」するための API購入されたアイテム。そのアイテムを購入可能にします。そのユーザーから再度リクエストできます。

前提条件

デジタル取引をアクションに組み込む前に、以下が必要です。次の前提条件を満たす必要があります。

デベロッパーアカウントおよび販売アカウント Google Play でデジタル商品を Google Play Console。
ウェブドメインは Google Search Console で確認済み。このドメインは一般に公開されているウェブサイトに関連付ける必要はありません。使用するのはウェブドメインだけです。
com.android.vending.BILLING を使用した Android アプリ権限。デジタル商品は「アプリ内購入」になる Google Play Console でこのアプリに関連付けられている。

また、このアプリを含む Google Play Console でリリースを作成する必要がありますが、リリースを公開したくない場合は、クローズドアルファ版をリリース。

Android アプリをお持ちでない場合は、 Android アプリを関連付ける手順をご確認ください。
1 つ以上の管理対象アイテムを Google Play Console アクションで販売するデジタル商品ですなお、 Google Play Console で管理対象アイテムを作成するには、 Android アプリの前提条件

まだ管理対象アイテムがない場合は、デジタルアイテムの手順を作成します。

Android アプリを関連付ける

お支払いとご請求の権限を持つ Android アプリを Google Play Console で手順は次のとおりです。

Android Studio または任意の Android IDE で、新しいプロジェクトを作成します。オプションを選択プロジェクト設定プロンプトで、基本的なアプリを作成します。
プロジェクトにパッケージ名（com.mycompany.myapp など）を付けます。この名前をデフォルトのままにしないでください。デフォルト以外のパスは、 Google Play Console に 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. [キーストアのパス] で、[新規作成] をクリックします。
4. 各フィールドに入力して、[OK] をクリックします。キーストアをメモし、 パスワードと鍵のパスワードは、安全な場所に保管してください。後ほど使用します
5. [次へ] をクリックします。
6. [リリース] を選択します。
7. [V1（JAR Signature）] を選択します。
8. [完了] をクリックします。
9. 数秒後、Android Studio によって app-release.apk ファイルが生成されます。後で使用できるように、このファイルを見つけます。
Google Play Console 新しいアプリケーションを作成します。
[アプリのリリース] に移動します。
[クローズドトラック] で [管理]、[アルファ版] の順に移動します。
[リリースを作成] ボタンをクリックします。
[署名鍵の管理と保護を Google に任せる] で、署名を入力します。あります。
APK ファイルをアップロードします。
[保存] をクリックします。

デジタルアイテムを作成

現在 Google Play Console にデジタル商品がない場合は、手順:

Google Play Console [アプリ内アイテム] > [管理対象のアイテム] に移動します。警告が表示された場合は上記の手順で Android アプリを作成するか、リンクをクリックします。販売者プロフィールを作成します
[管理対象アイテムを作成] をクリックします。
デジタル商品の各フィールドに入力します。プロダクト ID をメモしておきます。アクションからこの商品を参照します。
[保存] をクリックします。
販売する商品ごとにステップ 2 ～ 4 を繰り返します。

Google Play Console に表示される消費財の例。

Actions プロジェクトを準備する

Google Play Console でデジタル商品をセットアップするには、以下を有効にする必要があります。デジタル取引を作成し、Actions プロジェクトを Play アプリに関連付けます。

Actions プロジェクトでデジタル商品の取引を有効にする手順は次のとおりです。手順:

Actions Console で、プロジェクトを開くか、新しいプロジェクトを作成します。
[デプロイ]、[ディレクトリ情報] の順に移動します。
[詳細情報] と [取引] で [はい] チェックボックスをオンにします。 [アクションは Digital Purchase API を使用して取引を実行するか] で。
[保存] をクリックします。

デジタル商品の API キーを作成する

Digital Goods API にリクエストを送信するには、JSON サービスをダウンロードする必要がありますアカウントキー。

サービスアカウントキーを取得する手順は次のとおりです。

Actions Console で、右上にあるその他アイコンをクリックします。 [プロジェクトの設定] をクリックします。
アクションのプロジェクト ID を見つけます。
「<project_id>」と置き換えて、こちらのリンクをクリックしてくださいをプロジェクト ID に置き換えます。 https://console.developers.google.com/apis/credentials?project=project_id
メインナビゲーションで [認証情報] に移動します。
表示されたページで [認証情報を作成]、[サービスアカウントキー。
[サービスアカウント] に移動し、[新しいサービスアカウント] をクリックします。
サービスアカウントに「digitaltransactions」などの名前を付けます。
[作成] をクリックします。
ロール を Project > に設定します。オーナー。
[続行] をクリックします。
[キーを作成] をクリックします。
キータイプとして [JSON] を選択します。
[キーを作成] をクリックし、JSON サービスアカウントキーをダウンロードします。

このサービスアカウントキーを安全な場所に保存します。この鍵はフルフィルメントで Digital Purchases API のクライアントを作成します。

Google Play の広告枠に接続する

Actions プロジェクトからデジタル商品にアクセスするには、ウェブドメインとアプリをプロジェクトとして接続されたプロパティです。

注: 確認が完了するまで、接続手順が完了するまでに 1 週間ほどかかることがあります。追加できますこの期間を過ぎてもウェブサイトまたはアプリがリンクされない場合は、サポートにお問い合わせください。

Google Play Console のウェブドメインとアプリを Actions プロジェクトに接続する手順は次のとおりです。手順は次のとおりです。

Actions Console で、[Deploy]（デプロイ）、[Brand verification]（ブランドの確認）の順に移動します。
プロパティを接続していない場合は、まずウェブサイトを接続します。
1. [ウェブプロパティ]（</>）ボタンをクリックします。
2. ウェブドメインの URL を入力し、[接続] をクリックします。
手続きを行った個人に、詳しい手順が記載されたメールが Google から確認したウェブドメインの Google Search Console: メールの受信者が上記の手順を行うと、ウェブサイトは [ブランドの確認] に表示されます。
ウェブサイトを 1 つ以上接続したら、次の手順を行います。 Android アプリを接続します。
1. Actions Console で、[Deploy]（デプロイ）、[Brand verification]（ブランドの確認）の順に移動します。
2. [Connect App]（アプリを接続）をクリックします。
3. 表示されたページで、手順に沿ってウェブの所有権を確認します。以下が含まれている Play アプリを選択します: ページに表示されているとおりにウェブドメインの URL を ブランドの確認ページ。
  
  繰り返しになりますが、Google から必要があります。デベロッパーが確認を承認すると、Play アプリは [ブランドの確認] に表示されます。
  
  注: ウェブドメインは、Google Play Console に表示される前に表示されます。確認できます。Actions Console が表示されるまでに数日かかることがある更新されます。
4. [Access Play purchases]（Play での購入にアクセス）を有効にします。

Actions プロジェクトに接続されているウェブサイトとアプリを示す画像。

購入フローを構築する

Actions プロジェクトとデジタル商品のインベントリを準備して、商品購入フローを実行します。

1. Digital Purchases API クライアントを設定する

会話フルフィルメント Webhook で、サービスを使用して JWT クライアントを作成するアカウントの JSON キーと、 https://www.googleapis.com/auth/actions.purchases.digital スコープ。

次の Node.js コードは、Digital Purchases 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. 情報を収集する

ユーザーが購入を行う前に、アクションは購入に関する情報を収集します。ユーザーが購入できることや、Google Play でできます。

2. a.取引要件を検証する

ユーザーのアカウントが、高いパフォーマンスを生むようにセットアップされている購入オプションを提示する前にこのステップユーザーがお支払い方法を設定していて、お客様がデジタル取引がサポートされている言語 / 地域です。トランザクションの開始時 DIGITAL_PURCHASE_CHECK ヘルパーを使用してユーザーの取引を検証する設定することもできます。

次の Node.js コードは、DIGITAL_PURCHASE_CHECK をあります。

app.intent('Default Welcome Intent', async (conv, { SKU }) => {
  // Immediately invoke digital purchase check intent to confirm
  // purchase eligibility.
  conv.ask(new DigitalPurchaseCheck());
});

このチェックの結果は、次のように会話引数で探すことができます。 DIGITAL_PURCHASE_CHECK_RESULT。この結果に基づいて、 Google Pay の取引フローを確認するか、できます。

次の Node.js コードが要件チェックの結果を処理します。

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.利用可能な広告枠を収集する

Digital Purchases API を使用して、現在利用可能な Google Play ストアをリクエストします各商品の JSON オブジェクトの配列に作成します。後でこの配列を参照して、使用可能なオプションをユーザーに示す購入できます。

デジタル商品はそれぞれ、JSON 形式の SKU として表されます。「次の Node.js コードは、各 SKU に期待されるフォーマットの概要を示しています。

body = {
  skus: [
    skuId: {
      skuType: one of "APP" or "UNSPECIFIED"
      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 コードは、デジタルストアで購入可能な商品のリストをリクエストします。 Purchase 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': 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. 注文を作成する

ユーザーのデジタル購入を開始するには、デジタル商品のリストを提示してください購入できます。さまざまなリッチレスポンスタイプで、選択するようユーザーに促します。

次の Node.js コードは、SKU オブジェクトのインベントリ配列を読み取り、 list response に 1 つのリスト項目をそれぞれ:

skus.forEach((sku) => {
  const key = `${sku.skuId.skuType},${sku.skuId.id}`
  list.items[key] = {
    title: sku.title,
    description: `${sku.description} | ${sku.formattedPrice}`,
  };
});

4. 購入を完了する

購入を完了するには、COMPLETE_PURCHASE ヘルパーインテントをユーザーが選択したアイテムが表示されます

次の Node.js コードは、リストレスポンスからのユーザーの SKU 選択を処理します。その情報を含む COMPLETE_PURCHASE インテントをリクエストします。

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. 結果を処理する

購入が完了すると、actions_intent_COMPLETE_PURCHASE がトリガーされる Dialogflow イベント（または actions.intent.COMPLETE_PURCHASE Actions SDK インテント）を含む結果を記述する COMPLETE_PURCHASE_VALUE 引数。インテントを作成するこのイベントによってトリガーされ、結果がユーザーに通知されます。

考えられる購入結果は次のとおりです。

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: 原因不明な理由で取引が失敗しました。現在のステータスも不明です。このエラーステータスを処理するには、ユーザーに取引が失敗したことを通知し、再試行するかどうかを尋ねます。

次の Node.js コードは、COMPLETE_PURCHASE_VALUE 引数を読み取り、各結果を処理します。

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. 繰り返し購入できるようにする