チュートリアル： Alexa for Apps V1からV2への移行

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

このチュートリアルは、Alexa for Apps V1を使用するスキルを開発済みで、Alexa for Apps V2への移行を希望する開発者向けです。

V2のAPIでは、Echoデバイスを始め、あらゆるAlexa搭載デバイスからの音声によるアプリエクスペリエンスをスキルが橋渡しできるようになります。

V1とV2のユーザーエクスペリエンスの違い

V1とV2のおもな違いは、V1では、スキルがモバイルデバイス上のアプリに移動することのみ可能だったことです。V2では、スキルを使ってAlexa対応デバイス（Amazon Echoデバイスなど）からアプリにつなぐこともできます。

移行ワークフロー

以下のタスクリストは、スキルをAlexa for Apps V2に移行する際の手順をまとめたものです。

ステップ1：スキルマニフェストを更新する
ステップ2：スキルエンドポイントのコードを更新する
ステップ3： Alexa for Apps V2スキルをテストする

ステップ1：スキルマニフェストを更新する

スキルマニフェストを更新し、Alexa for Apps V2のサポートとインテントを宣言します。

スキルマニフェストを更新する

Alexa Skills Kitコマンドラインインターフェース（ASK CLI）を開きます。
カスタムスキルのスキルマニフェストのmanifest.apis.custom.interfacesセクションで、"type": "APP_LINKS"を"type": "APP_LINKS_V2"に置き換えます。

この宣言により、AlexaはスキルがAppLink V2インターフェースをサポートすることを認識できます。AppLink V1インターフェースとAppLink V2インターフェースの両方を宣言することはできません。
スキルからスマートフォンへの引き継ぎのプッシュ通知権限を追加するには、manifest.permissionsに、alexa::devices:app:push_notificationsを追加します。

この権限により、ユーザーはAlexaアプリでスキルのプッシュ通知送信を許可できます。Alexa for Appsは、ユーザーが権限を有効にしていない場合のシナリオを音声による同意を使って処理します。スキルがこの権限を確認したり、ユーザーに権限を有効にするようプロンプトを出したりする必要はありません。この行をマニフェストの権限セクションに追加するだけです。

スキルがAndroidのカスタムインテントを使う場合、スキルマニフェストのappLinkセクションを以下の例のように更新します。

注： Alexa for Apps V1では、宣言しなくてもスキルでAndroidのカスタムインテントを送信できました。V2では、Androidのカスタムインテントを宣言する必要があります。

"appLink": {
   "linkedApplications": [
      {
         "friendlyName": {
            "default": "GrubbHouse",
            "localizedNames": [
               {
                  "locale": "de-DE",
                  "name": "GrubbHaus"
               }
            ]
         },
         "catalogInfo": {
            "type": "GOOGLE_PLAY_STORE",
            "identifier": "com.someapp"
         },
         "customSchemes": [
            "grubbhouse://",
            "grbh://"
         ],
         "domains": [
            "grubbhouse.com",
            "grbh.com"
         ],
         # Androidカスタムインテントを宣言します
         "androidCustomIntents": [
            {
               "component": "com.someapp.SomeActivity",
               "action": "com.someapp.SOME_ACTION"
            }
         ]
      }
   ]
}

Alexa for Apps V2で新たに追加された種類のディープリンク（ウェブサイトのみのリンク、共通URIスキーム、Android共通インテント）を追加する場合、appLinkセクションを更新してlinkedWebDomains、linkedCommonSchemes、linkedAndroidCommonIntentsの必要なプロパティを以下の例のように追加します。

詳細については、Alexa for Apps V2 Skill Connectionsリクエストのリファレンスを参照してください。
```
"appLink": {
   "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"
      }
   ]
}
```

ステップ2：スキルエンドポイントのコードを更新する

ステップ1では、スキルマニフェストでAlexa for Apps V2のサポートを宣言しました。この宣言により、以下のペイロードが変更されます。

スキルが受信リクエストで受け取るリクエストペイロード
Skill Connectionsリクエストでスキルが送信するリクエストペイロード
スキルが受け取るSkill Connections応答ペイロード

このステップでは、スキルエンドポイントのコードを更新してこれらの変更を処理します。

ステップ2a：更新された受信リクエストのペイロードを解析する

スキルリクエストのペイロードは、スキルが受信リクエストで受け取るオブジェクトです。Alexa for Apps V2で変更されるこのオブジェクトのセクションは、context.System.device.supportedInterfacesとcontext.AppLinkの2つです。スキルリクエストハンドラーがこれらのセクションを受け取る場合、コードを更新して正しく解析できるようにする必要があります。

context.System.device.supportedInterfacesセクションにAppLinkプロパティが存在する場合、スキルがAlexa for Appsリクエストを行うことができることを意味します。V1では、AppLinkプロパティは空のオブジェクトでした。V2では、以下の例のようにversionフィールドに"2.0"という値が入ります。この値は、リクエストがAlexa for Apps V2リクエストであることを示します。

   "supportedInterfaces": {
      "AudioPlayer": {...},
   ===== ALEXA FOR APPSの追加開始 =====
      "AppLink": {
         "version": "2.0"
      },
   ===== ALEXA FOR APPSの追加終了 =====
   }

Alexa for Apps V1では、context.AppLinkオブジェクトにsupportedCatalogTypesフィールドのみが含まれました。これは、ユーザーがモバイルOSを使っていることを表します。Alexa for Apps V2では、このオブジェクトにdirectLaunchフィールドとsendToDeviceフィールドが追加され、モバイルエクスペリエンスと非モバイルエクスペリエンスがサポートされることを表します。directLaunchフィールドは、アプリの直接起動が可能かどうかを表します。sendToDeviceフィールドは、プッシュ通知フローが可能かどうかを表します。

モバイルリクエストのOSの種類は、directLaunchプロパティの子オブジェクトに移動しました。

モバイルデバイスからのリクエスト

Alexa for Apps V1と同様、ユーザーがモバイルデバイスからリクエストを行うと、通常は直接起動とプッシュ通知のどちらを使うかを選択できます。ユーザーにとっては多くの場合、ハンズフリーでアプリが起動されるほうが使いやすいです。アプリやウェブサイトを直接起動する代わりにスキルとユーザーとの対話を続けることで、押し付けがましくないエクスペリエンスを実現したい場合は通知を送信できます。

モバイルでの直接起動エクスペリエンスが可能かどうかを判断するには

スキルでcontext.AppLink.directLaunchフィールドを確認します。

iOSデバイスからのリクエストの場合、このプロパティには以下の例のように"IOS_APP_STORE"というキーが含まれます。
```
 "AppLink": {
    "directLaunch": {
       "IOS_APP_STORE": {}
    }
 }
```
Androidデバイスからのリクエストの場合、このプロパティには以下の例のように"GOOGLE_PLAY_STORE"というキーが含まれます。
```
 "AppLink": {
    "directLaunch": {
       "GOOGLE_PLAY_STORE": {}
    }
 }
```

Alexa搭載デバイスからのリクエスト

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

スキルがユーザーのスマートフォンに通知を送信できるかどうかを判断するには

次の例に示すように、スキルでcontext.AppLink.sendToDeviceフィールドを確認します。
```
 "AppLink": {
    "sendToDevice": {}
 }
```
以下は、直接起動とスマートフォンへの引き継ぎの両方を処理できるiOSデバイスからリクエストを受信するスキルの例です。
```
 "AppLink": {
    "directLaunch": {
       "IOS_APP_STORE": {}
    },
    "sendToDevice": {}
 }
```

ステップ2b： Skill Connectionsリクエストで新しい形式のペイロードを送信する

Alexa for Apps V2では新しいURIエンドポイントが追加されました。Skill Connectionsリクエストを行う際に使用することで、アプリを直接起動したり、ユーザーにディープリンクを含む通知を送信したりできます。Alexa for Appsリクエストのペイロード構造は形式が変更されました。ただし、実際に提供する情報はほとんど同じです。詳細については、Alexa for Apps V2 Skill Connectionsリクエストのリファレンスを参照してください。

Alexa for Appsに送信してディープリンクをリクエストするSkill Connectionsペイロードに以下の変更を行います。

ディープリンクをリクエストする

response.directives.uriフィールドで、スキルのLinkApp接続URIの末尾に以下のように"/2"を追加します。
```
"uri": "connection://AMAZON.LinkApp/2"
```
response.directives.inputフィールドを以下のように変更します。
- response.outputSpeechプロパティを使って、ディープリンクの前に音声応答を指定します。
  
  たとえば、フライトスキルで「フライトは定刻通りにロサンゼルス国際空港を太平洋標準時午後2時に出発します」と読み上げてから、ユーザーにフライトの詳細ページのディープリンクを送信します。
- onAppLinkedフィールドとonScreenLockedフィールドを削除し、Alexa for Appsがさまざまなシナリオで対応するために使用する"topic"フィールドを追加します。
たとえば、ユーザーがディープリンクをトリガーするリクエストを行ったときにスマートフォンがロックされている場合、Alexa for Appsは"メッセージを表示するには、端末のロックを解除してください"と応答します。トピックの文字数は最大23文字で、アクションを表す句を指定します。日本語で言えば「メッセージを見る」や「ラザニアのレシピを見る」のような形式です。この形式にすることで、Alexaは「太郎さんがラザニアのレシピを見られるようにリンクを送ります」のように、文章内でトピックを再利用できます。
- デフォルトの、ロック解除されたモバイルの直接起動の読み上げ（"<アプリ名>です"）を適用しない場合はinput.prompt.directLaunchDefaultPromptBehaviorを"SUPPRESS"に設定します。
注：ロックされたスマートフォンのヘルプ応答を指定したり、出さないようにしたりすることはできなくなります。
サポートするカタログの種類ごとにディープリンクを指定します。

Alexaは、ユーザーの受信デバイス（iOSまたはAndroid）に基づいて適切なリンクを選んで使用します。

モバイルデバイスからのリクエストの場合、Alexa for Appsはデフォルトでユーザーのスマートフォンのアプリを開こうとします。

モバイルデバイスからリクエストが送信されたときの動作を無効にするには

Skill ConnectionsリクエストペイロードでdirectLaunch.enabledをfalseに設定します。

Alexa搭載デバイスからのリクエストの場合、Alexa for Appsはデフォルトでユーザーのスマートフォンにプッシュ通知を送信しようとします。

例：直接起動のみ — AndroidカスタムインテントとExtraデータ

以下は、ANDROID_CUSTOM_INTENTディープリンクを使ったSkill Connectionsリクエストペイロードの例です。スキルはモバイルデバイス上で直接アプリを起動する必要があるだけなので、sendToDevice.enabledプロパティを明示的にfalseに設定します。

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPSの追加開始 ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/2",
         "input": {
            "links": {
                "GOOGLE_PLAY_STORE": {
                    "primary": {
                        "ANDROID_CUSTOM_INTENT": {
                            "appIdentifier": "com.cityguide.app",
                            "intentSchemeUri": "intent:#Intent;package=com.cityguide.app;component=com.cityguide.app.SearchActivity;i.some_int=100;S.some_str=hello;end"
                        }
                    }
                }
            },
            "prompt": {
                "topic": "検索の詳細を見る",
            },
            "sendToDevice": {
                "enabled": false
            }
         },
================== ALEXA FOR APPSの追加終了 ====================
      ]
   }
}

例：スマートフォンへの引き継ぎのみ — Android共通インテントと共通スキーム

以下は、Android共通インテントとディープリンク用の共通URIスキームの両方を使ったSkill Connectionsリクエストペイロードの例です。このアプローチは、プッシュ通知を送信するだけでユーザーのスマートフォンでアプリを直接起動するわけではないため、押し付けがましさが軽減されます。アプリの機能を無効にするために、スキルで明示的にdirectLaunch.enabledをfalseに設定します。

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPSの追加開始 ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/2",
         "input": {
            "links": {
                "GOOGLE_PLAY_STORE": {
                    "primary": {
                        "ANDROID_COMMON_INTENT": {
                            "intentName": "OPEN_SETTINGS",
                            "intentSchemeUri": "intent:#Intent;action=android.settings.WIFI_SETTINGS;end"
                        }
                    }
                },
                "IOS_APP_STORE": {
                    "primary": {
                        "COMMON_SCHEME": {
                            "scheme": "TEL",
                            "uri": "tel:1234567"
                        }
                    }
                }
            },
            "prompt": {
                "topic": "設定を見る"
            },
            "directLaunch": {
                "enabled": false
            }
         },
================== ALEXA FOR APPSの追加終了 ====================
      ]
   }
}

ステップ2c：更新されたAlexa for Apps応答ペイロードを処理する

Alexa for Apps V2では、応答ペイロードのcause.resultフィールドにdirectLaunch、sendToDeviceのいずれかが含まれます。directLaunchが含まれる場合、Alexa for Appsがアプリを起動しようとすることを意味します。sendToDeviceの場合、Alexa for Appsがユーザーのモバイルデバイスにリンクを送信しようとすることを意味します。

更新されたAlexa for Apps応答ペイロードを処理するには

応答ハンドラーでdirectLaunch、sendToDeviceのどちらが含まれるかを確認する必要があります。
また、応答ハンドラーでステータスコードやエラーコードを確認し、試行したアクションが成功したかどうかを判断する必要もあります。

Alexa for AppsがsendToDeviceエクスペリエンスを試行するすべてのケースで、スキルはユーザーとの対話を再開できます。

直接起動の応答例

{
  "type": "SessionResumedRequest",
  "requestId": "<string>",
  "timestamp": "<string>",
  "locale": "<string>",
  "cause": {
    "type": "ConnectionCompleted",
    "token": "1234",
    "status": {
      "code": "200",     // これは接続呼び出し自体のステータスコードです
      "message": "OK"
    },
    "result": {
      "directLaunch": {    // Alexaが直接起動を試行したことを意味します
        "primary": {
           "status": "FAILURE",
           "errorCode": "APP_INCOMPATIBLE"  // プライマリリンクに失敗しました
        },
        "fallback": {
           "status": "SUCCESS"  // フォールバックに成功しました
        }
      }
    }
  }
}

スマートフォンへの引き継ぎの応答例

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

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

重要： Alexa for Apps開発者プレビューの期間中は、Alexa for Apps V1スキルのクローンを作成し、非モバイルエクスペリエンスを追加して更新することをお勧めします。開発中のスキルをテストできます。ただし、V2 APIがリリースされるまで、更新したスキルの認定と公開はできません。

Alexa for Apps V2開発者プレビュースキルをテストするには

開発者プレビュースキルをテストする方法については、ステップ3： Alexa for Apps V2スキルをテストするを参照してください。

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

フィードバックを送信

最終更新日: 2024 年 05 月 08 日

チュートリアル： Alexa for Apps V1からV2への移行

V1とV2のユーザーエクスペリエンスの違い

移行ワークフロー

ステップ1： スキルマニフェストを更新する

ステップ2： スキルエンドポイントのコードを更新する

ステップ2a： 更新された受信リクエストのペイロードを解析する

モバイルデバイスからのリクエスト

Alexa搭載デバイスからのリクエスト

ステップ2b： Skill Connectionsリクエストで新しい形式のペイロードを送信する

例： 直接起動のみ — AndroidカスタムインテントとExtraデータ

例： スマートフォンへの引き継ぎのみ — Android共通インテントと共通スキーム

ステップ2c： 更新されたAlexa for Apps応答ペイロードを処理する

直接起動の応答例

スマートフォンへの引き継ぎの応答例

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

関連トピック

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

ステップ1：スキルマニフェストを更新する

ステップ2：スキルエンドポイントのコードを更新する

ステップ2a：更新された受信リクエストのペイロードを解析する

例：直接起動のみ — AndroidカスタムインテントとExtraデータ

例：スマートフォンへの引き継ぎのみ — Android共通インテントと共通スキーム

ステップ2c：更新されたAlexa for Apps応答ペイロードを処理する