チュートリアル： 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. コマンドプロンプトを開きます。

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

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

  4. スキルマニフェストでAlexa for Appsのサポートを宣言するには、以下の例のように、interfaces配列（manifest.apis.custom.interfaces）のtypeプロパティにAPP_LINKS_V2の値を追加します。 
       {
      "type":"APP_LINKS_V2"
   },
  5. スキルのリンク先アプリのメタデータをスキルマニフェストに追加するには、manifest.apis.custom.appLinkの下にappLinkオブジェクトを追加します。以下の、日本語にローカライズした名前のシティガイドスキルの例を参照してください。 
    {
   "manifest": {
      "apis": {
         "custom": {
            "endpoint": {
               "uri": "..."
            },
            "interfaces": [
               {
                  "type": "APP_LINKS_V2"
               }
            ],
   ================== ALEXA FOR APPSの追加開始 ==================
            "appLink": {
               "linkedApplications": [
                  {
                     "friendlyName":{
                        "default":"シティガイド",
                        "localizedNames": [
                           {
                              "locale":"ja-JP",
                              "name":"シティガイド"
                           }
                        ]
                     },
                     "catalogInfo": {
                        "type": "IOS_APP_STORE",
                        "identifier": "id123456789"
                     },
                     "customSchemes": [
                        "cityguide://",
                        "ctgd://"
                     ],
                     "domains": [
                        "cityguide.com",
                        "ctgd.com"
                     ]
                  },
                  {
                     "friendlyName":{
                        "default":"シティガイド",
                        "localizedNames": [
                           {
                              "locale":"ja-JP",
                              "name":"シティガイド"
                           }
                        ]
                     },
                     "catalogInfo": {
                        "type": "GOOGLE_PLAY_STORE",
                        "identifier": "com.cityguide.app"
                     },
                     "customSchemes": [
                        "cityguide://",
                        "ctgd://"
                     ],
                     "domains": [
                        "cityguide.com",
                        "ctgd.com"
                     ],
                     "androidCustomIntents": [
                        {
                           "component": "com.someapp.SomeActivity",
                           "action": "com.someapp.SOME_ACTION"
                        }
                     ]
                  }
               ],
               "linkedWebDomains": [
                  "grubbhouse.com",
                  "amazon.com",
                  "yahoo.com"
               ],
               "linkedCommonSchemes": {
                  "IOS_APP_STORE": [
                     "MAPS",
                     "TEL"
                  ],
                  "GOOGLE_PLAY_STORE": [
                     "MAPS",
                     "TEL"
                  ]
               },
               "linkedAndroidCommonIntents": [
                  {
                     "intentName": "SHOW_IN_MAP",
                     "catalogType": "GOOGLE_PLAY_STORE"
                  }
               ]
            }
================== ALEXA FOR APPSの追加終了 ==================
         }
      }
   }
}
  6. 非モバイルフローでプッシュ通知を送信するには、次の例のように、スキルマニフェストのpermissions配列内で"alexa::devices:app:push_notifications"スキル権限を宣言する必要があります。 
    "permissions": [
   {
     "name": "alexa::devices:app:push_notifications"
   }
],

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

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

    モバイルデバイスからの受信リクエストの場合、スキルはユーザーのスマートフォンでアプリのリンクを直接起動できます。

  2. このモバイルエクスペリエンスが可能かどうかを判断するには、contextオブジェクトのAppLink.directLaunchフィールドを確認します。

    次の例では、フィールドにIOS_APP_STOREキーが含まれます。これは、iOSデバイスからのリクエストであることを示しています。

    注： directLaunch.IOS_APP_STOREフィールドの値は空のオブジェクトです。これは、モバイル（直接起動）エクスペリエンスが有効であることを示しています。

    "AppLink": {
     "directLaunch": {
         "IOS_APP_STORE": {}
     }
 }

    次の例では、フィールドにGOOGLE_PLAY_STOREキーが含まれます。これは、Androidデバイスからのリクエストであることを示しています。

    注： directLaunch.GOOGLE_PLAY_STOREフィールドの値は空のオブジェクトです。これは、モバイル（直接起動）エクスペリエンスが有効であることを示しています。

    "AppLink": {
     "directLaunch": {
         "GOOGLE_PLAY_STORE": {}
     }
 }

    Amazon Echo Dotなど、Alexa搭載デバイスからの受信リクエストの場合、スキルはAlexaアプリの通知でユーザーのモバイルデバイス宛にリンクを送信できます。

  3. スキルがリンクを送信できるかどうかを判断するには、context.AppLink.sendToDeviceオブジェクトを確認します。

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

    注： directLaunch.IOS_APP_STOREフィールドとsendToDeviceフィールドの値は空のオブジェクトです。これは、directLaunch、sendToDeviceがいずれも有効であることを示しています。

    {
"version": "1.0",
"session": {...},
"context": {
   "System": {
      "device": {
         "deviceId": "string",
         "supportedInterfaces": {
            "AudioPlayer": {...},
================== ALEXA FOR APPSの追加開始 ==================
             "AppLink": {
                "version": "2.0"
             },
================== ALEXA FOR APPSの追加終了 ====================
         }
      },
      "application": {
         "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {...},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
   },
   "AudioPlayer": {...},
================== ALEXA FOR APPSの追加開始 ==================
   "AppLink": {
      "directLaunch": {
          "IOS_APP_STORE": {}
      },
      "sendToDevice": {}
   }
================== ALEXA FOR APPSの追加終了 ====================
},
"request": {...}
  4. スキルがロケールごとに異なるリンクを送信する場合は、まずhandlerInput.requestEnvelope.request.localeプロパティをチェックしてリクエスト元デバイスのロケールを判断する必要があります。

  5. アプリやウェブサイトのディープリンクを送信するには、Skill Connectionsリクエストの応答本文にConnections.StartConnectionディレクティブを含めます。

  6. ディープリンクとともに、ユーザーにディープリンクの機能を伝えるためのトピック（「メッセージを確認する」や「フライト状況を見る」など）をプロンプトで提供します。

  7. （任意）Alexa for Appsの呼び出しの一貫として、通常のスキル応答と同様にTTS（response.outputSpeech）を読み上げることもできます。たとえば、旅行スキルで「フライトは定刻通りにロサンゼルス国際空港を午後2時15分に出発します」などと読み上げることができます。Skill Connectionsリクエストの詳細については、Alexa for Apps Skill Connectionsリクエストのリファレンスを参照してください。

    以下は、接続リクエストの例です。

    {
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
        "outputSpeech": {
            ...
        },
        "card": {
            ...
        },
        "reprompt": {
            ...
        },
        "directives": [
================== ALEXA FOR APPSの追加開始 ==================
          {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
                "links": {
                    "IOS_APP_STORE": {
                        "primary": {
                            "UNIVERSAL_LINK": {
                                "appIdentifier": "id123456789",
                                "url": "https://www.cityguide.com/search/search_terms=coffee"
                            }
                        }
                    },
                    "GOOGLE_PLAY_STORE": {
                        "primary": {
                            "UNIVERSAL_LINK": {
                                "appIdentifier": "com.cityguide.app",
                                "url": "https://www.cityguide.com/search/search_terms=coffee"
                            }
                        }
                    }
                },
                "prompt": {
                    "topic": "検索結果を見る"
                }
            }
        }
================== ALEXA FOR APPSの追加終了 ====================
      ]
    }
}
  8. Skill Connectionsリクエストが完了すると、スキルは、プライマリのディープリンクアクションとフォールバックの成功／失敗、および失敗の場合は失敗の理由を示す応答を受け取ります。スキルは常に、ConnectionCompletedとSessionResumedRequestを処理する必要があります。ユーザーがスマートフォンでアプリを直接開く（directLaunch）ことに成功した場合、スキルはモバイルアプリやデバイスで残りの対話が行えるようにクリーンアップと終了の処理を実行できます。モバイル上でプライマリもフォールバックも失敗した場合、またはリクエストが非モバイルデバイスで行われた場合はいつでも、ユーザーはスキルの対話を続行できます。以下は、直接起動リクエストとスマートフォンへの引き継ぎリクエストが成功した場合のサンプル応答例です。スマートフォンへの引き継ぎリクエストの場合、ユーザーとの対話セッションを続行できます。 
    {
   "type": "SessionResumedRequest"
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause": {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "200",
         "message": "OK"
      },
      "result": {
         "directLaunch": {
            "primary": {
               "status": "SUCCESS"
            }
         }
      }
   }
}

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

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

ステップ3： Alexa for Appsスキルをテストする

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

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

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

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

モバイルデバイスでスキルをテストするには

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

モバイル以外の環境でスキルをテストするには

  • 非モバイル（Send to Phone機能）エクスペリエンスの場合、次の項目をテストしてください。
    • アプリ固有のアクションを含む、エンドツーエンドの事例が想定どおりに動作するかどうかをテストします。
    • プッシュ通知のタップをテストします。プッシュ通知を受信するには、以下を行う必要があります。
      1. OSの設定でAlexaアプリの通知を有効にします。
      2. Alexaアプリのスキルの設定ページでプッシュ通知のスキル権限を有効にします。
    • Alexaアプリでホームカードのタップをテストします。
    • スキルがサポートするさまざまなロケールでテストします。
    • アプリがインストールされていないフォールバックシナリオをテストします。
    • ディープリンクが失敗した場合の復旧シナリオをテストします（モバイルデバイスにアプリがインストールされていない場合など）。ディープリンクが失敗しても、スキルがユーザーとの対話を続行できることを確認します。