このガイドでは、会話型アクションにデジタル トランザクションを追加して、ユーザーが非消費型デジタル商品を購入できるようにする方法について説明します。
重要な用語: 非消費型デジタル アイテムとは、アクションや Android アプリでの追加コンテンツへの有料アクセスなど、1 回しか購入できない最小管理単位(SKU)のことです。このタイプの商品は、購入、使用、再購入が可能な消費型デジタル アイテムとは異なります。
消費不可の 1 回限りのアイテムについて詳しくは、Android のドキュメントで 1 回限りのアイテム固有の機能に関する説明をご覧ください。
取引の流れ
このガイドでは、デジタル商品の取引フローで発生する各開発ステップの概要を説明します。アクションは、デジタル商品の取引を処理する場合、次のフローを使用します。
- デジタル購入 API クライアントを設定する: アクションは Digital Purchases API を使用して Google Play 広告枠と通信し、取引を行います。アクションはなんらかの処理を行う前に、デジタル購入 API と通信するためのサービスキーを持つ JWT クライアントを作成します。
- 情報を収集する: アクションは、取引の準備をするために、ユーザーと Google Play インベントリに関する基本情報を収集します。
- 取引要件を検証する: アクションは、購入フローの開始時にデジタル取引要件ヘルパーを使用して、ユーザーが取引できることを確認します。
- 利用可能な在庫を収集する: アクションは Google Play の在庫をチェックし、現在購入可能なアイテムを特定します。
- 注文を作成する: アクションは、ユーザーが購入可能なデジタル商品を選択できるようにします。
- 購入を完了する: アクションは Digital Purchases API を使用して、Google Play ストアへのユーザーの選択に基づいて購入を開始します。
- 結果を処理する: アクションは取引のステータス コードを受け取り、購入が正常に完了したこと(または追加の手順が必要)をユーザーに通知します。
制限と審査のガイドライン
トランザクションを含むアクションには、追加のポリシーが適用されます。Google がトランザクションを含むアクションの審査には数週間かかることがあります。リリース スケジュールを計画するときは、この時間を考慮してください。審査プロセスを容易にするため、審査のためにアクションを送信する前に、取引に関するポリシーとガイドラインに準拠していることを確認してください。
デジタル商品を販売するアクションは、次の国でのみデプロイできます。
- オーストラリア
- ブラジル
- カナダ
- インドネシア
- 日本
- メキシコ
- ロシア
- シンガポール
- タイ
- トルコ
- 英国
- 米国
前提条件
デジタル取引をアクションに組み込むには、次の前提条件を満たす必要があります。
Google Play のデベロッパー アカウントと販売アカウント。Google Play Console でデジタル商品を管理します。
Google Search Console で確認されたウェブドメイン。このドメインは、一般公開されているウェブサイトに関連付ける必要はありません。Google が参照する必要があるのはウェブドメインだけです。
Google Play Console で
com.android.vending.BILLING
権限を付与された Android アプリ。デジタル商品は、Google Play Console でこのアプリに関連付けられた「アプリ内購入」になります。また、このアプリを使用して Google Play Console でリリースを作成する必要がありますが、リリースを公開したくない場合は、クローズド アルファ版リリースを作成できます。
Android アプリをまだお持ちでない場合は、Android アプリの関連付けの手順に沿って操作してください。
Google Play Console の 1 つ以上の管理対象アイテム。アクションと一緒に販売するデジタル商品です。Android アプリの前提条件を設定するまで、Google Play Console で管理対象アイテムを作成することはできません。
管理対象アイテムがない場合は、デジタル アイテムを作成するの手順に沿って操作します。
Android アプリを関連付ける
請求に関する権限を持つ Android アプリが現在 Google Play Console にない場合は、次の手順を行います。
- Android Studio または任意の Android IDE で、新しいプロジェクトを作成します。プロジェクト設定プロンプトでオプションを選択して、非常に基本的なアプリを作成します。
- プロジェクトにパッケージ名を付けます(例:
com.mycompany.myapp
)。com.example
を含むパッケージは Google Play Console にアップロードできないため、この名前をデフォルトのままにしないでください。 - アプリの
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] をクリックします。
- 各フィールドに入力し、[OK] をクリックします。[キーストアのパスワード] と [鍵のパスワード] は後で使用するため、安全な場所に保管してください。
- [次へ] をクリックします。
- [release] を選択します。
- [V1(JAR Signature)] を選択します。
- [Finish] をクリックします。
- 数秒後、Android Studio が
app-release.apk
ファイルを生成します。 後で使用するために、このファイルを見つけてください。
Google Play Console で、新しいアプリを作成します。
[アプリのリリース] に移動します。
[クローズド トラック] で [管理]、[アルファ版] の順に移動します。
[リリースの作成] ボタンをクリックします。
[Google が署名鍵の管理と保護を行う] で、署名鍵情報を入力します。
APK ファイルをアップロードします。
[保存] をクリックします。
デジタル アイテムを作成する
現在 Google Play Console にデジタル商品がない場合は、次の手順を行います。
- Google Play Console で、[アプリ内アイテム]、[管理対象アイテム] の順に移動します。警告が表示された場合は、前述の手順に沿って Android アプリを作成するか、リンクをクリックして販売者プロフィールを作成します。
- [管理対象アイテムを作成] をクリックします。
- デジタル商品の項目を入力します。プロダクト ID は、アクションからこの商品を参照する際に使用します。
- [保存] をクリックします。
- 販売する商品ごとにステップ 2 ~ 4 を繰り返します。
Actions プロジェクトを準備する
Google Play Console でデジタル商品をセットアップしたら、デジタル トランザクションを有効にし、Actions プロジェクトを Play アプリに関連付ける必要があります。
設定
Actions プロジェクトでデジタル商品の取引を有効にする手順は次のとおりです。
- Actions Console でプロジェクトを開くか、新しいプロジェクトを作成します。
- [Deploy]、[Directory information] の順に移動します。
- [その他の情報] と [トランザクション] で、[アクションで Digital Purchase API を使用してデジタル商品のトランザクションを実行します] で [はい] チェックボックスをオンにします。
- [保存] をクリックします。
デジタル商品の API キーを作成する
Digital Goods API にリクエストを送信するには、Actions Console プロジェクトに関連付けられた JSON サービス アカウント キーをダウンロードする必要があります。
サービス アカウント キーを取得する手順は次のとおりです。
- Actions Console で、右上のその他アイコンをクリックし、[プロジェクト設定] をクリックします。
- アクションのプロジェクト ID を確認します。
- 次のリンクにアクセスします。「
<project_id>
」は実際のプロジェクト ID に置き換えてください。https://console.developers.google.com/apis/credentials?project=project_id
- メイン ナビゲーションで [認証情報] に移動します。
- 表示されたページで [認証情報を作成]、[サービス アカウント キー] の順にクリックします。
- [サービス アカウント] に移動し、[新しいサービス アカウント] をクリックします。
- サービス アカウントに「digitaltransactions」などの名前を付けます。
- [作成] をクリックします。
- [ロール] を [プロジェクト] > [オーナー] に設定します。
- [Continue](続行)をクリックします。
- [キーを作成] をクリックします。
- キータイプとして [JSON] を選択します。
- [キーを作成] をクリックし、JSON サービス アカウント キーをダウンロードします。
このサービス アカウント キーは安全な場所に保管してください。このキーをフルフィルメントで使用して、Digital Purchases API のクライアントを作成します。
Play 広告枠に接続する
Actions プロジェクトからデジタル商品にアクセスするには、ウェブドメインとアプリを接続プロパティとしてプロジェクトに関連付けます。
Google Play Console のウェブドメインとアプリを Actions プロジェクトに接続する手順は次のとおりです。
- Actions Console で、[Deploy]、[Brand verification] の順に移動します。
プロパティを接続していない場合は、まずウェブサイトを接続します。
- ウェブ プロパティ(</>)ボタンをクリックします。
- ウェブドメインの URL を入力し、[接続] をクリックします。
Google Search Console でウェブドメインの所有権が確認された個人に、詳しい手順が記載されたメールを送信します。このメールの受信者がこれらの手順を完了すると、[ブランドの確認] の下にウェブサイトが表示されます。
1 つ以上のウェブサイトを接続したら、次の手順で Android アプリを接続します。
- Actions Console で、[Deploy]、[Brand verification] の順に移動します。
- [Connect App](アプリを接続)をクリックします。
表示されたページで、手順に沿って Google Play Console でウェブドメインを確認します。デジタル商品が含まれている Play アプリを選択し、[ブランドの確認] ページに表示されているとおりにウェブドメインの URL を入力します。
ここでも、Google からドメインの確認済み所有者に確認メールが送信されます。オーナーが確認を承認すると、Play アプリが [ブランドの確認] に表示されます。
[Access Play purchases](Play での購入にアクセス)を有効にします。
購入フローを構築する
Actions プロジェクトとデジタル商品在庫を用意したら、会話フルフィルメント Webhook でデジタル商品の購入フローを構築します。
1. Digital Purchases API クライアントを設定する
会話フルフィルメント Webhook で、サービス アカウントの JSON キーと https://www.googleapis.com/auth/actions.purchases.digital
スコープを使用して JWT クライアントを作成します。
次の 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. 情報を収集する
ユーザーが購入を行う前に、アクションはユーザーの購入可否と在庫から購入可能な商品に関する情報を収集します。
2. a. デジタル購入の要件を検証する
購入オプションを提供する前に、ユーザーのアカウントがトランザクションを実行するように設定されていることを確認することをおすすめします。DigitalPurchaseCheck
シーンに移行する必要があります。このシーンでは、ユーザーが検証されていること、ユーザーが許可されたサーフェス(スマートディスプレイ、スマート スピーカー、Android)でトランザクションを実行していること、ユーザーがデジタル取引がサポートされている言語 / 地域にいることを確認します。
デジタル購入確認シーンを作成する手順は次のとおりです。
- [Scenes] タブで、
DigitalPurchaseCheck
という名前の新しいシーンを追加します。 - [スロットフィル] で [+] をクリックして新しいスロットを追加します。
- [タイプを選択] で、スロットタイプとして
actions.type.DigitalPurchaseCheckResult
を選択します。 - スロット名の欄で、スロットに「
DigitalPurchaseCheck
」という名前を付けます。 - [Customize slot value writeback] チェックボックスを有効にします(デフォルトで有効になっています)。
- [保存] をクリックします。
デジタル購入チェックの結果は、次のいずれかになります。
- 要件が満たされると、セッション パラメータに成功条件が設定され、ユーザーによるデジタル商品の購入を続行できます。
- 1 つ以上の要件を満たすことができない場合、セッション パラメータに失敗条件が設定されます。この場合は、会話をトランザクション エクスペリエンスから離れるか、会話を終了する必要があります。
デジタル購入のチェック結果を処理する手順は次のとおりです。
- [Scenes] タブで、新しく作成した
DigitalPurchaseCheck
シーンを選択します。 - [Condition] で、[+] をクリックして新しい条件を追加します。
テキスト フィールドに次の条件構文を入力して、成功条件を確認します。
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 Purchases API を使用して、現在利用可能な Google 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
]
}
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
エンドポイントに POST リクエストを送信し、{packageName}
は Google Play Console のアプリのパッケージ名(com.myapp.digitalgoods
など)で、その結果を SKU オブジェクトの配列形式にします。
結果の配列で特定のデジタル商品のみを取得するには、body.ids
で購入可能にするデジタル商品の商品 ID をリストします(Google Play Console の各アプリ内アイテムの下に表示されます)。
次の Node.js コードは、Digital purchases 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': ['nonconsumable.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 オブジェクトのインベントリ配列を読み取り、それぞれに 1 つのリストアイテムを含むリスト レスポンスを作成します。
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
」という名前を付けます。 - [Customize slot value writeback] チェックボックスを有効にします(デフォルトで有効になっています)。
- [スロットを構成] で、プルダウンから
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
シーンを選択します。 - [Condition] で、[+] をクリックして新しい条件を追加します。
テキスト フィールドに次の条件構文を入力して、成功条件を確認します。
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.
[移行] で [会話を終了] を選択して、会話を終了します。
サポートする購入結果のタイプごとに上記の手順を繰り返します。
ユーザーの購入情報を反映
ユーザーがアクションにクエリを実行すると、リクエスト 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"
]
}
}
プロジェクトをテストする
プロジェクトをテストするときは、Actions Console でサンドボックス モードを有効にして、お支払い方法を請求せずにアクションをテストできます。サンドボックス モードを有効にする手順は次のとおりです。
- Actions Console で、ナビゲーションの [Test] をクリックします。
- [設定] をクリックします。
- [開発サンドボックス] オプションを有効にします。