スキル内課金の管理

Note: Sign in to the developer console to build or publish your skill.

スキル内課金の管理

ASK SDK for Javaには、利用可能なスキル内商品や課金されたスキル内商品を検索したり、スキル内から課金とキャンセルのリクエストを開始したりするためのサービスクライアントとヘルパークラスが含まれています。

スキル内課金サービス
スキル内課金のインターフェース

スキル内課金サービス

ASK SDK for Javaには、inSkillProducts APIを呼び出すMonetizationServiceClientが用意されています。このAPIでは、現在のスキルに関連付けられているすべてのスキル内商品を取得し、各スキル内商品が課金可能かまたは現在のユーザーがすでに課金済みかを確認できます。次のメソッドがあります。

getInSkillProducts(String locale, String purchasableFilter, String entitledFilter, String productType, String nextToken, BigDecimal maxResults)
getInSkillProduct(String locale, String inSkillProductId)

localeは、リクエストからinput.getRequestEnvelope().getRequest().getLocale()で取得できます。purchasableFilterは、nullを指定するとすべてのスキル内商品を取得し、PURCHASABLEまたはNOT_PURCHASABLEを指定すると、課金可能かどうかで応答を絞り込むことができます。entitledFilterは、nullを指定するとすべてのスキル内商品を取得し、ENTITLEDまたはNOT_ENTITLEDを指定すると、買い切り型のステータスで応答を絞り込むことができます。productTypeは、nullを指定するとすべてのスキル内商品を取得し、ENTITLEMENT、CONSUMABLE、SUBSCRIPTIONのいずれかを指定すると、商品タイプで絞り込むことができます。nextTokenは、複数ページのクエリの場合には必須です。maxResultsを使うと、API呼び出しで取得したレコードをスキルで制御できます。デフォルトのページサイズは100レコードです。inSkillProductIdには取得するスキル内商品を指定します。

getInSkillProducts()

getInSkillProductsメソッドは、現在のスキルに関連付けられているすべてのスキル内商品を取得し、現在のスキルとユーザーについて各商品の課金可能性と買い切り型商品のステータスを示します。

import com.amazon.ask.model.services.monetization.MonetizationServiceClient;
import com.amazon.ask.model.services.ServiceException;
import com.amazon.ask.model.services.monetization.InSkillProduct;
import com.amazon.ask.model.services.monetization.InSkillProductsResponse;

@Override
public Optional<Response> handle(HandlerInput input) {
  try {
    MonetizationServiceClient client = input.getServiceClientFactory().getMonetizationService();
    String locale = input.getRequestEnvelope().getRequest().getLocale();

    // すべての商品を取得します
    InSkillProductsResponse responseProducts = client.getInSkillProducts(locale, null, null, null, null, null);
    System.out.println("すべての購入可能な商品とサイズは、" + responseProducts.getInSkillProducts().size() + "です");
  }
  catch (ServiceException e) {
    System.out.println("getInSkillProducts APIの呼び出し中に例外が発生しました。エラーコード: " + e.getStatusCode());
  }
}

API応答にはスキル内商品レコードの配列が含まれます。

{
  "inSkillProducts":[
    {
      "productId": "amzn1.adg.product....",
      "referenceName": "<開発者が定義した商品参照名>",
      "type": "SUBSCRIPTION",               // またはENTITLEMENT
      "name": "<開発者が定義したロケール固有の商品名>",
      "summary": "<開発者が提供したロケール固有の商品説明>",
      "entitled": "ENTITLED",              // またはNOT_ENTITLED
      "purchasable": "PURCHASABLE",        // またはNOT_PURCHASABLE
      "purchaseMode": "TEST"               // またはLIVE
      "activeEntitlementCount": 1
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}

getInSkillProduct()

getInSkillProductメソッドは商品IDで識別される単一のスキル内商品の商品レコードを取得します。

import com.amazon.ask.model.services.monetization.MonetizationServiceClient;
import com.amazon.ask.model.services.ServiceException;
import com.amazon.ask.model.services.monetization.InSkillProduct;
import com.amazon.ask.model.services.monetization.InSkillProductsResponse;

@Override
public Optional<Response> handle(HandlerInput input) {
  try {
      MonetizationServiceClient client = input.getServiceClientFactory().getMonetizationService();
      String locale = input.getRequestEnvelope().getRequest().getLocale();

      // 商品IDを使用して特定のスキル内商品を取得します
      String productId = "<'amzn1.adg.product....'形式の商品ID>";
      InSkillProduct responseProduct = client.getInSkillProduct(locale, productId);

      if(responseProduct!=null) {
        System.out.println("次のIDの商品が見つかりました。" + productId);
      }
  }
  catch (ServiceException e) {
      System.out.println("getInSkillProduct APIの呼び出し中に例外が発生しました。エラーコード: " + e.getStatusCode());
  }
}

API応答には単一のスキル内商品レコードが含まれます。

{
  "productId": "amzn1.adg.product....",
  "referenceName": "<開発者が定義した商品参照名>",
  "type": "SUBSCRIPTION",               // またはENTITLEMENT
  "name": "<開発者が定義したロケール固有の商品名>",
  "summary": "<開発者が提供したロケール固有の商品説明>",
  "entitled": "ENTITLED",              // またはNOT_ENTITLED
  "purchasable": "PURCHASABLE",        // またはNOT_PURCHASABLE
  "purchaseMode": "TEST"               // またはLIVE
  "activeEntitlementCount": 1
}

これらのAPIとスキル実装での使い方の詳細については、こちらを参照してください。カスタムスキルへのスキル内課金の追加

スキル内課金のインターフェース

ASK SDK for Javaには、スキルでAlexaからスキル内課金とキャンセルのリクエストを開始するためのSendRequestDirectiveが用意されています。Amazonシステムはユーザーとの音声による対話を管理し、課金取引を処理して、ステータス応答をリクエスト元のスキルに返します。このインターフェースを使用して、以下の3つのアクションがサポートされます。

Upsell
Buy
Cancel

これらのアクションと推奨されるユースケースの詳細については、こちらを参照してください。カスタムスキルへのスキル内課金の追加

Upsell

スキルは、ユーザーが明示的にコンテキストをリクエストしなかった場合にスキルのコンテキストを提供するためにUpsellアクションを開始する必要があります。たとえば、無料のコンテンツが提供されている間または後です。Upsellアクションを開始するには、商品IDとアップセルメッセージが必要です。アップセルメッセージを使って、開発者はAlexaで価格を提示する前にユーザーにスキル内商品を提示する方法を指定できます。

// 下記を追加でハンドラーソースファイルに含めます
import com.amazon.ask.model.interfaces.connections.SendRequestDirective;

// ディレクティブペイロードを準備します
Map<String,Object> mapObject = new HashMap<String,Object>();
Map<String, Object> inskillProduct = new HashMap<>();
inskillProduct.put("productId", "<amzn1.adg.product....形式の商品ID>"); // productIdを商品IDで置換します
mapObject.put("upsellMessage","この商品を購入しますか");
mapObject.put("InSkillProduct", inskillProduct);

// ディレクティブリクエストを準備します
SendRequestDirective directive = SendRequestDirective.builder()
    .withPayload(mapObject)
    .withName("Upsell")
    .withToken("correlationToken")
    .build();
Optional<Response> response = input.getResponseBuilder()
        .addDirective(directive)
        .withShouldEndSession(true)
        .build();
// スキルのコンテキストからディレクティブを返してアクションリクエストをトリガーします
return response;

Buy

スキルは、ユーザーが特定のスキル内商品の課金をリクエストしたときにBuyアクションを開始します。Buyアクションを開始するには、商品IDが必要です。

// 下記を追加でハンドラーソースに含めます
import com.amazon.ask.model.interfaces.connections.SendRequestDirective;

// ディレクティブペイロードを準備します
Map<String,Object> mapObject = new HashMap<String,Object>();
Map<String, Object> inskillProduct = new HashMap<>();
inskillProduct.put("productId", "<amzn1.adg.product....形式の商品ID>"); // productIdを商品IDで置換します
mapObject.put("InSkillProduct", inskillProduct);

// ディレクティブリクエストを準備します
SendRequestDirective directive = SendRequestDirective.builder()
    .withPayload(mapObject)
    .withName("Buy")
    .withToken("sometoken")
    .build();
Optional<Response> response = input.getResponseBuilder()
        .addDirective(directive)
        .withShouldEndSession(true)
        .build();
// スキルのコンテキストからディレクティブを返してアクションリクエストをトリガーします
return response;

Cancel

スキルは、ユーザーがサポートされているスキル内商品の既存の非消費型アイテムまたはサブスクリプションのキャンセルをリクエストしたときにCancelアクションを開始します。Cancelアクションを開始するには、商品IDが必要です。

// 下記を追加でハンドラーソースに含めます
import com.amazon.ask.model.interfaces.connections.SendRequestDirective;

// ディレクティブペイロードを準備します
Map<String,Object> mapObject = new HashMap<String,Object>();
Map<String, Object> inskillProduct = new HashMap<>();
inskillProduct.put("productId", "<amzn1.adg.product....形式の商品ID>"); // productIdを商品IDで置換します
mapObject.put("InSkillProduct", inskillProduct);

// ディレクティブリクエストを準備します
SendRequestDirective directive = SendRequestDirective.builder()
    .withPayload(mapObject)
    .withName("Cancel")
    .withToken("sometoken")
    .build();
Optional<Response> response = input.getResponseBuilder()
        .addDirective(directive)
        .withShouldEndSession(true)
        .build();
// スキルのコンテキストからディレクティブを返してアクションリクエストをトリガーします
return response;

このページは役に立ちましたか？

フィードバックを送信