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

Note: Submit your skill and see it come to life.

注： Alexa for Appsは開発者プレビュー段階です。フィードバックに基づく改善や今後の機能強化によって変更される場合があります。この機能を利用するには、登録してプレビューを申請する必要があります。Alexa for Appsに関するご質問やご意見がありましたら、alexaforapps-help@amazon.comまでメールでお寄せください。

このチュートリアルでは、Alexa for Appsをカスタムスキルに追加する手順について説明します。このチュートリアルのサンプルコードでは、「シティガイド」というスキルを使用しています。

まず、アプリとウェブサイトのメタデータをスキルマニフェストに追加します。次に、ディープリンクを送信するようスキルのエンドポイントを編集し、スキルをテストします。

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

前提条件

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

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

重要： 子ども向けスキルは現在、ディープリンクを利用できません。子ども向けスキルでAlexa for Appsの利用を検討されている場合は、alexaforapps-help@amazon.com（英語での対応）までお問い合わせください。

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

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

ステップ1：アプリとウェブサイトのメタデータをスキルマニフェスト（skill.json）に追加する
ステップ2：ディープリンクを送信するスキルのエンドポイントを編集する
ステップ3： Alexa for Appsスキルをテストする

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

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

ヒント： get-skill-manifestとupdate-skill-manifestのCLIコマンドを使って既存のAlexa-hostedスキルのマニフェストを直接取得して更新する代わりに、スキル全体をクローンしてローカルマシンに移行できます。クローンは、ask clone（ASK CLI v1）、ask init（ASK CLI v2）のいずれかのコマンドで作成できます。更新による問題を回避するため、初めて既存スキルのクローンを作成する際には必ずプロファイル名（ask init -p <profile-name>）を指定してください。

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

インストールしていない場合は、クイックスタート： Alexa Skills Kitコマンドラインインターフェース（ASK CLI）の手順に従ってASK CLIをインストールします。
コマンドプロンプトを開きます。
カスタムスキルのスキルマニフェストをskill.jsonという新しいファイルにダウンロードするには、次のようにget-skill-manifest CLIコマンドで指定します。

ask smapi get-skill-manifest -s <skill-id> -g <stage> > skill.json
スキルマニフェストでAlexa for Appsのサポートを宣言するには、以下の例のように、interfaces配列（manifest.apis.custom.interfaces）のtypeプロパティにAPP_LINKS_V2の値を追加します。
```
   {
      "type":"APP_LINKS_V2"
   },
```

スキルのリンク先アプリのメタデータをスキルマニフェストに追加するには、manifest.apis.custom.appLinkの下にappLinkオブジェクトを追加します。以下の、日本語にローカライズした名前のシティガイドスキルの例を参照してください。

注： localizedNames値を指定できるのは、スキルマニフェストのmanifest.publishingInformation.localesセクションに含まれるロケールのみです。

重要： 実際のスキルマニフェストでは、「ALEXA FOR APPSの追加開始」、「ALEXA FOR APPSの追加終了」の行は省略してください。

{
   "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の追加終了 ==================
         }
      }
   }
}

非モバイルフローでプッシュ通知を送信するには、次の例のように、スキルマニフェストのpermissions配列内で"alexa::devices:app:push_notifications"スキル権限を宣言する必要があります。
注：スキルで必要なのは、マニフェストで権限を宣言するだけです。実行時に権限のステータス確認や有効化を処理する必要はありません。Alexa for Apps APIがスキルに代わって権限を処理します。
```
"permissions": [
   {
     "name": "alexa::devices:app:push_notifications"
   }
],
```

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

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

ヒント： 発話の競合を最小限にするには、サンプル発話のベストプラクティスを参考にサンプルフレーズを決定し、音声でスキルをテストしてください。

更新したカスタムスキルのスキルマニフェストをアップロードするには、次のようにupdate-skill-manifest CLIコマンドを使います。
```
ask smapi update-skill-manifest -s <skill-id> -g <stage> --manifest <manifest>
```
注： --manifestパラメーターの値はファイル名ではなく、JSON文字列にする必要があります。

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

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

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

ユーザーのデバイスがAlexa for Appsをサポートすることを確認するには、以下の構造でcontext.System.device.SupportedInterfacesオブジェクトにAppLinkフィールドがあるかどうかを確認します。
```
   "AppLink": {
      "version": "2.0"
   }
```
モバイルデバイスからの受信リクエストの場合、スキルはユーザーのスマートフォンでアプリのリンクを直接起動できます。
このモバイルエクスペリエンスが可能かどうかを判断するには、contextオブジェクトのAppLink.directLaunchフィールドを確認します。
注：このステップでのcontext.AppLinkオブジェクトは、スキルリクエスト内の前のステップのAppLinkフィールドとは別の部分です。

次の例では、フィールドに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アプリの通知でユーザーのモバイルデバイス宛にリンクを送信できます。
スキルがリンクを送信できるかどうかを判断するには、context.AppLink.sendToDeviceオブジェクトを確認します。

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

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

ヒント： Send to Phone機能（sendToDevice）の対話を短時間で実装するには、AMAZON.SendToPhoneIntentを使用します。この標準ビルトインインテントは、「スマートフォンに送信して」や「リンクを送って」といったさまざまな発話に対応しています。ビルトインインテントの使用について詳しくは、ビルトインインテントを実装するを参照してください。

ヒント： ユーザーがモバイルデバイスを使っていても、押し付けがましさを軽減するためにsendToDeviceを使用できます。たとえば、ユーザーが後で確認できるよう情報のリンクを送信したい場合などです。

重要： 実際のスキルでは、「ALEXA FOR APPSの追加開始」、「ALEXA FOR APPSの追加終了」の行は省略します。
```
{
"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": {...}
```
スキルがロケールごとに異なるリンクを送信する場合は、まずhandlerInput.requestEnvelope.request.localeプロパティをチェックしてリクエスト元デバイスのロケールを判断する必要があります。
注：スキルは、スキルを配信しているロケールからのリクエストのみを受信します。詳しくは、多言語に対応するスキルを開発するを参照してください。

ヒント： ロケールはすべてのリクエストで利用できるため、どのディープリンクを送信するか、ロケールを使用して判断することを検討してください。ディープリンクがロケールではなく国によって異なる場合、ユーザーの国にアクセスする権限をユーザーにリクエストする必要があります。このリクエストを実行する方法の1つは、ユーザーがAlexaに登録したデバイスアドレスにアクセスすることです。詳細については、所在地情報を使用してスキルを拡張するを参照してください。ユーザーに紐づいたiOS App StoreやGoogle Playストアの国を反映しているとは限りませんが、ユーザーのリアルタイムの位置情報にアクセスすることもできます。リアルタイムの位置情報サービスの詳細については、Alexaスキル向け位置情報サービスを参照してください。
アプリやウェブサイトのディープリンクを送信するには、Skill Connectionsリクエストの応答本文にConnections.StartConnectionディレクティブを含めます。
ディープリンクとともに、ユーザーにディープリンクの機能を伝えるためのトピック（「メッセージを確認する」や「フライト状況を見る」など）をプロンプトで提供します。

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

重要： topicフィールドはスマートフォンへの引き継ぎのやり取りの間にユーザーが聞く音声応答を制御するため、リンクの目的を明確に記述する必要があります。日本語では、topicは通常、動詞句のコールトゥーアクションになります。たとえば、topicフィールドが「フライト状況を確認する」の場合、Alexaは「花子さんにフライト状況を確認できるリンクを送信します」などと言います。

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

{
    "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の追加終了 ====================
      ]
    }
}   

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応答のリファレンスを参照してください。

注：デフォルトでは、安全上の理由から、運転中のユーザーのディープリンクリクエストは失敗します。ユーザーが運転中にAndroidまたはiOSデバイスからリクエストを行っても、スキルはスキルリクエストオブジェクトのdirectLaunchプロパティを受け取りません。スキルがディープリンクリクエストを送信した場合、Amazonはデフォルトで直接起動ではなく通知を送信します。運転中のユーザーにカスタマイズした音声応答を提供する場合は、スキルリクエストオブジェクトのAutomotiveプロパティを検討してください。ハンズフリーでの操作や通話を支援するアプリにユーザーをディープリンクするなど、運転中の直接起動シナリオにスキルを登録する必要があるとお考えの場合、スキルIDとシナリオを添えてalexaforapps-help@amazon.com（英語での対応）までお問い合わせください。

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

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

重要： Alexa for Apps開発者プレビューの段階では、開発中のスキルをテストすることはできますが、認定して公開することはできません。

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

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

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

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

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

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

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

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

前提条件

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

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

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

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

関連トピック

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

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