チュートリアル： Alexa for Appsをカスタムスキルに追加する



チュートリアル： Alexa for Appsをカスタムスキルに追加する

Alexa for Appsをカスタムスキルに追加するには、アプリとウェブサイトのメタデータをスキルマニフェストに追加し、ディープリンクを送信するスキルのエンドポイントを編集して、スキルのテストと公開を行う必要があります。このチュートリアルでは、「シティガイド」カスタムスキルを例にとって、Alexa for Appsを追加する方法を説明します。

この機能の概要については、Alexa for Appsとはを参照してください。

前提条件

スキルにAlexa for Appsを追加するには、以下の項目が必要です。

  • 開発したAlexaカスタムスキル
  • ディープリンクを利用可能なiOSアプリ、Androidアプリ、ウェブサイトのいずれか

Alexa for Appsをカスタムスキルに追加する手順の概要

Alexa for Appsは、以下の手順でスキルに追加します。

ステップ1： アプリとウェブサイトのメタデータをスキルマニフェスト（skill.json）に追加する

このステップでは、スキルマニフェストでスキルのリンク先となるアプリやウェブサイトを指定し、それぞれの情報を追加します。

アプリとウェブサイトのメタデータをスキルマニフェストに追加する

  1. クイックスタート： Alexa Skills Kitコマンドラインインターフェース（ASK CLI）の手順に従ってASK CLIをインストールします。

  2. カスタムスキルのスキルマニフェストをskill.jsonという新しいファイルにダウンロードするには、次のようにget-skill-manifest CLIコマンドを使用します。

    ask smapi get-skill-manifest -s <skill-id> -g <stage> > skill.json

  3. スキルマニフェストでAlexa for Appsのサポートを宣言するには、以下の例のように、interfaces配列（manifest.apis.custom.interfaces）のtypeプロパティにAPP_LINKSの値を追加します。 
       {
      "type":"APP_LINKS"
   },
  4. スキルのリンク先アプリのメタデータをスキルマニフェストに追加するには、manifest.apis.custom.appLinkの下にappLinkオブジェクトを追加します。以下の、ドイツ語にローカライズした名前のシティガイドスキルの例を参照してください。 
    {
   "manifest": {
      "apis": {
         "custom": {
            "endpoint": {
               ...
            },
            "interfaces": [
               {
                  "type": "APP_LINKS"
               }
            ],
   ================== ALEXA FOR APPSの追加開始 ==================
            "appLink": {
               "linkedApplications": [
               {
                  "friendlyName":{
                     "default":"シティガイド",
                     "localizedNames": [
                        {"locale":"de-DE", "name":"Stadtführer"}
                     ]
                  },
                  "catalogInfo": {
                     "type": "IOS_APP_STORE",
                     "identifier": "id123456789"
                  },
                  "customSchemes": ["cityguide://","ctgd://"],
                  "domains": ["cityguide.com","ctgd.com"]
                  },
                  {
                  "friendlyName":{
                     "default":"シティガイド",
                     "localizedNames": [
                        {"locale":"de-DE", "name":"Stadtführer"}
                     ]
                  },
                  "catalogInfo": {
                     "type": "GOOGLE_PLAY_STORE",
                     "identifier": "com.cityguide.android.ctgdmobile"
                  },
                  "customSchemes": ["cityguide://","ctgd://"],
                  "domains": ["cityguide.com","ctgd.com"]
                  }
               ]
            },

  5. ユーザーにモバイルデバイスでのスキルの使い方を知ってもらうために、スキルのdescriptionアトリビュートやexamplePhrasesアトリビュートを更新することを検討してください。これらのアトリビュートは、スキルマニフェストのmanifest.publishingInformation.localesセクションで直接更新できます。また、この情報はスキルをテストして公開する前に、いつでもAlexa開発者コンソールから更新できます。スキルがアクセスできるモバイルアプリや、モバイルで使えるサンプル発話についての情報をユーザーに知らせるようにします。スキルがモバイルデバイスでのみ動作する場合は、これをユーザーに伝えてください。以下は、シティガイドスキルでこれらのアトリビュートを更新する方法の例です。

    {
   "locales": {
      "ja-JP": {
         "name": "シティガイド",
         "smallIconUri": "<s3 link>",
         "largeIconUri": "<s3 link>",
         "summary": "シティガイドでさまざまなスポットを見つけましょう。",
         "description": "モバイルデバイスのシティガイドならすばやく検索できます。 「アレクサ、シティガイドでタピオカティーを探して」と言ってみましょう。 Alexaに徒歩での行き方をたずねると、アプリのライブ追跡マップにすぐにアクセスできます。",
         "examplePhrases": [
            "アレクサ、シティガイドで近くのコーヒーショップを探して",
            "アレクサ、シティガイドでバスの時刻表を見せて",
            "アレクサ、シティガイドでお気に入りランドマークへの徒歩での行き方を教えて"
         ],
         "keywords": []
      },
   }
}

    発話の競合を最小限にするには、サポートされている呼び出しフレーズを参考にサンプルフレーズを決定し、音声でスキルをテストしてください。

  6. 更新したカスタムスキルのスキルマニフェストをアップロードするには、次のようにupdate-skill-manifest CLIコマンドを使います。 
    ask smapi update-skill-manifest -s <skill-id> -g <stage> --manifest <manifest>

ステップ2： ディープリンクを送信するスキルのエンドポイントを編集する

このステップでは、スキルが受け取ったリクエストを確認し、Alexa for Appsをサポートするデバイスからのものかどうかを判断します。また、リクエスト元のプラットフォーム（Android、iOS）とロケールについても確認します。

ディープリンクを送信するスキルのエンドポイントを編集する

  1. ユーザーのデバイスがAlexa for Appsをサポートすることを確認するには、スキルでcontext.System.device.SupportedInterfacesオブジェクトにAppLinkフィールドがあるかどうかを確認します。

  2. Androidデバイス、iOSデバイスのどちらがリクエスト元であるかを判断するには、スキルでcontext.AppLink.supportedCatalogTypesフィールドを確認します。リクエスト元がiOSデバイスの場合、このフィールドに["IOS_APP_STORE"]の値が設定されています。

    "AppLink": {"supportedCatalogTypes": ["IOS_APP_STORE"]},

    リクエスト元がAndroidデバイスの場合、このフィールドに["GOOGLE_PLAY_STORE"]の値が設定されています。

    "AppLink": {"supportedCatalogTypes": ["GOOGLE_PLAY_STORE"]},

    以下は、iOSデバイスからリクエストを受信するスキルの例です。

    {
"version": "1.0",
"session": {...},
"context": {
   "System": {
      "device": {
         "deviceId": "string",
         "supportedInterfaces": {
            "AudioPlayer": {...},
             ================== ALEXA FOR APPSの追加開始 ==================
             "AppLink": {...},
             ================== ALEXA FOR APPSの追加終了 ====================
         }
      },
      "application": {
         "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {...},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
   },
   "AudioPlayer": {...},
   ================== ALEXA FOR APPSの追加開始 ==================
   "AppLink": {
      "supportedCatalogTypes": ["IOS_APP_STORE"]
   },
   ================== ALEXA FOR APPSの追加終了 ====================
},
"request": {...}
  3. スキルがロケールごとに異なるリンクを送信する場合は、handlerInput.requestEnvelope.request.localeでリクエスト元デバイスのロケールを判断する必要があります。
  4. Alexa for Appsは、ユニバーサルリンク、カスタムスキーム、Androidインテント、Android Package Managerアプリ起動のリンクをサポートします。詳細については、ディープリンクの種類を参照してください。アプリやウェブサイトへのディープリンクを送信するには、Skill Connectionsリクエストの応答本文にConnections.StartConnectionディレクティブが必要です。詳細については、Skill Connectionsリクエストペイロードの例を参照してください。

  5. Skill Connectionsリクエストが完了すると、スキルは、プライマリのディープリンクアクションとフォールバックの成功／失敗、および失敗の場合は失敗の理由を示す応答を受け取ります。スキルは常に、ConnectionCompletedとSessionResumedRequestを処理する必要があります。成功の場合、スキルはモバイルアプリやデバイスで残りの対話が行えるようにクリーンアップと終了の処理を実行できます。プライマリとフォールバックが成功しなかった場合やプライマリがフォールバックを試行することなくエラーになった場合は、ユーザーが音声でリクエストを完了できるようスキルでの対話を続けるという選択肢があります。

    以下は、応答の例です。

    {
   "type": "SessionResumedRequest"
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {"code": "200","message": "OK"},
      "result": {
         "primary": {
            "status": "FAILURE",
            "errorCode": "APP_INCOMPATIBLE"
         },
         "fallback": {
            "status": "SUCCESS"
         }
      }
   }
}

    応答ペイロードの詳細については、Skill Connections応答のリファレンスを参照してください。

ステップ3： スキルをテストして公開する

スキルのテスト

現時点では、Alexa開発者コンソールのテストページは、スキルリクエストでAppLinkオブジェクトを送信しません。エンドツーエンドのテストでは、スキルにアクセスできる開発者またはベータアカウントに接続されたモバイルデバイスでテストを実施してください。

次の3つのいずれかの方法を使って、どのモバイルデバイスでもスキルをテストできます。

  • Alexa搭載スマートフォンを使用する。
  • Alexaモバイルアクセサリ（Echo Budsなど）を使用する。
  • Alexaモバイルアプリから直接テストする。

Alexaモバイルアプリで、ビルトインのウェイク機能を使ったリクエストやAlexaアイコンのタップによってテストすることができます。

テスト項目は次のとおりです。

  • アプリ固有のアクションを含む、エンドツーエンドの事例が想定どおりに動作するかどうかをテストします。
  • デバイスのロック／ロック解除をテストします。
  • スキルがサポートするさまざまなロケールでテストします。
  • アプリがインストールされていないフォールバックシナリオをテストします。
  • ディープリンクが失敗した場合の復旧シナリオをテストします（サポートされていない種類のデバイスなど）。ディープリンクが失敗しても、スキルがユーザーとの対話を続行できることを確認します。

スキルの認定と公開

マニフェストをアップロードし、Lambda関数のランタイムを変更して、モバイルデバイスでのテストを完了したら、スキルを公開（再公開）できます。スキルの認定と公開は、ASK CLIのsubmit-skill-for-certificationコマンドで実行できます。詳細については、スキルの認定と公開を参照してください。また、このステップをAlexaコンソールで行うこともできます。

以下は、submit-skill-for-certificationコマンドの例です。

$ ask smapi submit-skill-for-certification -s {skillId}

submit-skill-for-certificationコマンドのデフォルトは、自動公開です。認定はするが公開はしないMANUAL_PUBLISHINGを指定した場合は、別途、publish-skillサブコマンドを実行してリリース日を設定する必要があります。

ほかのカスタムスキル同様、基本的な検証を行い、Alexaスキルのポリシーに準拠していることを確認し、通常の公開フローに従って公開してください。Alexa for Appsの開発者プレビュー中に、マニフェストのAlexa for Appsセクションを変更した場合は、必ずskill.jsonをalexaforapps-help@amazon.comに送信して検証（再検証）する必要もあります。