Alexa Blogs
スキル内課金は、Alexaスキル内でデジタルコンテンツに課金できるようにするための仕組みです。この記事では、Alexaスキルにスキル内課金を導入するための手順について説明しますので、ぜひアイデアをふくらませてスキル内課金に取り組んでみましょう。スキル内課金の概要については、「スキルによる収益化」の記事をご覧ください。
Alexaスキルにスキル内課金を導入するための手順は次の通りです。
- スキル内商品の作成とスキルとの関連付け
- 対話モデルへの購入関連インテントの追加
- コードへの購入関連処理の実装
- テストおよびスキル審査の準備
以下ではそれぞれのステップの内容を紹介します。
(1) スキル内商品の作成とスキルとの関連付け
スキル内商品の管理は、開発者コンソールからGUIで行う方法と、ASK CLIを使ってコマンドで行う方法があり、今回はGUIの方法を説明します。ASK CLIでのスキル内商品管理についてはこちらのリファレンスをご覧ください。まずはAlexaスキルの開発者コンソール上でスキル内商品を作成します。「ビルド」タブの左側のメニューから「スキル内商品」を選択して、右側に表示される画面から「スキル内商品を作成」ボタンを押します。
次の画面では、スキル内商品の参照名を入力して、買い切り型・サブスクリプション型・消費型といった種類を選択します。完了したら「スキル内商品を作成」を押します。
ここからはスキル内商品の情報を入力します。まずは「新しい言語を追加」を押して、日本語を選択してください。次の画面では、表示名・説明・アイコン等のスキル内商品に関する情報を設定してください。「購入プロンプトの説明」という項目は、スキル内商品の購入を案内する際に、Alexaがそのまま話す文言となります。一通り情報を入力した後には「保存」ボタンを押して前の画面に戻ってください。
続いて、価格設定等を入力します。「価格設定と購入可能状況」の項目では Amazon.co.jp を選択し、日本円での価格を入力してください。また「税金のカテゴリー」は適切なものを選択してください。
最後に画面右上の「保存」ボタンを押すと、作成したスキル内商品をスキルに関連付けるかどうかの選択が提示されるので、「スキルにリンク」を押してください。関連付けは後で行うこともできます。これでスキル内商品の作成と関連付けは完了です。
(2) 対話モデルへの購入関連インテントの追加
次にスキルの対話モデルにスキル内商品の購入に関連した、次のようなインテントおよびサンプル発話を追加します。
- 商品購入: 「買う」、「何を買える？」、「<商品名>を買いたい」、「<商品名>がほしい」等
- キャンセル: 「返金して」、「<商品名>をキャンセル」等
- 商品数確認（消費型の場合のみ）: 「<商品名>はいくつある？」、「<商品名>は残ってる？」等
(3) コードへの購入関連処理の実装
あとはスキルのコードにスキル内商品の購入に関連した処理を実装します。スキル内課金を導入したスキルの動作概要は下図の通りです。下図の商品購入およびキャンセルの処理は、対話モデルに追加したインテントに対応しています。またアップセルとは、ユーザが無料コンテンツを利用した後や有料コンテンツにアクセスしようとした際に、スキル内商品の購入を促す処理を指します。
前提として、In-Skill Product ServiceのAPIを利用することで、スキル内商品を購入済みか、また何回購入したかといった情報を取得することができます。例えばスキル内商品の一覧を取得するAPIからは、下記のようなレスポンスが得られます。レスポンスの中で、entitled というパラメータはスキル内商品が購入された状態かどうかを表し、activeEntitlementCount は購入回数を表します。purchaseMode は購入処理が開発時の開発環境 (TEST) か、もしくはスキル公開時の本番環境 (LIVE) かを表します。開発環境での購入処理には実際の課金は発生しません。In-Skill Product Serviceの詳細につきましてはこちらのドキュメントを参照してください。
{
"inSkillProducts": [
{
"productId": "amzn1.adg.product.unique-id-1",
"referenceName": "your_product_name_1",
"type": "ENTITLEMENT",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 0,
"purchaseMode": "TEST"
},
{
"productId": "amzn1.adg.product.unique-id-2",
"referenceName": "your_product_name_2",
"type": "SUBSCRIPTION",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"purchasable": "NOT_PURCHASABLE",
"activeEntitlementCount": 1,
"purchaseMode": "TEST"
},
{
"productId": "amzn1.adg.product.unique-id-3",
"referenceName": "your_product_name_3",
"type": "CONSUMABLE",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 2,
"purchaseMode": "TEST"
}
],
"nextToken": null,
"truncated": false
}
また ASK SDK では In-Skill Product Service のAPIを簡単に利用するための MonetizationServiceClient が用意されており、getInSkillProducts というメソッドを呼び出すことでスキル内商品の情報を取得することができます。MonetiazationServiceClientにはドキュメントとコード例が用意されていますのでそちらも参照してください。
次は購入処理の実装です。ユーザが発話の中で購入したいスキル内商品を具体的に指定しなかった場合には、問い返して確認する必要があります。購入する商品が明確になれば、Buy ディレクティブをスキルのレスポンスに含めることで購入処理を進めます。コード例は下記の通りで、ディレクティブの productId パラメータに購入対象商品のIDを指定します。注意点として、購入関連処理のディレクティブをレスポンスで返すと、一度スキルのセッションは終了し、その後の処理はスキル外で行われます。スキル外で話される購入メッセージは、スキル内商品の定義に基づいてAlexaが適切な発話を行います。その後またスキルにリクエストが送信されてセッションが再開しますが、一度セッションが終了した際にセッションアトリビュートは失われてしまいますので、必要なデータはDynamoDB等に永続化してください。小さいデータであればディレクティブの token パラメータに含めることで、セッション再開時に同じ値を受け取ることができます。購入処理の詳細はこちらのドキュメントを参照してください。
return handlerInput.responseBuilder
.addDirective({
type: "Connections.SendRequest",
name: "Buy",
payload: {
InSkillProduct: {
productId: "amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
}
},
token: "correlationToken", // セッション再開時にも同じ値がリクエストに含まれる
})
.getResponse();
購入処理後のスキルセッション再開時には、Connections.Response という種類のリクエストがスキルに送られるので、これをハンドラで処理します。このリクエストの中には下記のように購入処理が成功したか失敗したかという情報が purchaseResult というパラメータに含まれていますので、状況に応じたレスポンスを返してください。例えば購入が成功した場合にはプレミアムコンテンツにアクセスさせる、購入が失敗した場合には引き続き無料の体験を楽しんでもらうといった処理です。またAlexaアプリの設定で音声ショッピングがオフになっている場合には、purchaseResult はERRORという値になります。スキルセッション再開時の詳細は、こちらのドキュメントを参照してください。
アップセル処理は、ユーザがスキルを利用している中で自然にスキル内商品を提示して、興味があるか尋ねることで購入につなげる処理です。購入処理と同様、スキルのレスポンスにUpsellディレクティブを含めると、スキルのセッション外でAlexaがUpsellディレクティブに含まれるアップセルメッセージを読み上げ、ユーザに興味があるかを尋ねます。ユーザが「はい」と答えた場合には、購入処理と同じく、スキル外でAlexaが購入メッセージを読み上げます。購入処理後のスキルセッション再開については前述の通りです。またアップセルに対してユーザが「いいえ」と答えた場合には、name が Upsell で purchaseResult が DECLINED な Connections.Response リクエストがスキルに送られますので、ユーザを適切に元の体験に戻してください。他にも注意点として、アップセルの中ではスキル内商品の価格等に言及しないてください。それらは購入処理のステップにおいて、スキル内商品の情報に基づいて適切にユーザに提示されます。アップセル処理の詳細は、こちらのドキュメントを参照してください。
キャンセル処理ではサブスクリプション型のキャンセルを行うことができます。購入・アップセル処理と同様にスキルのレスポンスにCancelディレクティブを含めると、スキルのセッション外でキャンセル処理が行われます。その後スキルに送信される Connections.Response リクエストを適切にハンドルしてください。詳細はこちらをご確認ください。
最後に消費型の場合のみ、スキル内商品の個数管理に気を付けてください。前述の通り、In-Skill Product Service のAPIを呼び出すことで、ユーザがスキル内商品を何回購入したことがあるかという値 (activeEntitlementCount) を取得することができます。しかし消費型のスキル内商品について、ユーザがスキル内でいくつ消費したかという数字はスキル側で管理する必要があります。具体的には商品の消費数をDynamoDBのような永続ストレージに保持することになります。したがって、ユーザが「<商品名>はいくつ残っている？」のように消費型商品の残り個数を尋ねた場合には、APIから取得できる購入数とスキルが自前で管理する消費数から、残っている数を計算して答えるようにしてください。また消費型の場合には、お客様がAmazonから返金を受けた場合等、購入数 (activeEntitlementCount) がスキル外で増減する可能性があります。消費数が購入数を超えてしまうような場合にも、エラーが起きないよう考慮してください。
(4) テストおよびスキル審査の準備
スキル内課金を導入したスキルのテストについて、気を付けるべき点を挙げます。詳しい情報はこちらのドキュメントもご確認ください。
- 開発中のスキルを一度無効にして、再度有効にしてもスキルの購入状況は変化しません。消費型商品を導入したスキルの場合、ストアに公開されたLiveバージョンではスキルを無効にしてもユーザのUser IDは変わりませんので、スキルが無効にされても商品の消費数は永続化したままにしてください。また開発中のスキルにおいて、開発者アカウントと紐付いたユーザの購入状況をリセットするには、下記のように開発者コンソールのスキル内商品画面から「テスト購入をリセット」のリンクを押してください。
- スキルのベータテスト機能を使って招待したテストユーザが、開発中のスキル内でスキル内商品の購入処理を行った場合、実際の課金は発生しません。この場合、In-Skill Product Service のAPIから得られる購入状況は、purchaseMode がTESTという値になりますので、公開されたスキルでの購入とは区別できます。
スキル審査にパスするためには、こちらのドキュメントも参考にしてスキル内商品の購入に関する基本的な機能がカバーされているか確認してください。また、こちらのスキル内商品に関する審査時の要件も参考にして、準拠するようにしてください。
「スキル内課金の開発手順」はいかがでしたか。概念を理解すれば、サンプルコードを元に実装を進められると思います。ぜひスキル内課金の仕組みを利用して、スキルユーザに優れたコンテンツを届けましょう。
参考資料
