Tutorial: Add Alexa for Apps V2 to Your Custom Skill

Note: Alexa for Apps V2 is a private beta and might change as Amazon receives feedback and iterates on the feature. To use this feature, you must register for the private beta program. If you have questions or feedback about Alexa for Apps, contact your Amazon Business Development representative, or email alexaforapps-help@amazon.com.

This tutorial walks you through adding Alexa for Apps to your own custom skill. The code examples in this tutorial are for a skill called "City Guide."

You start by adding app and website metadata to the skill manifest. You edit the skill endpoint to send deep links, and then you test the skill.

For an overview of this feature, see About Alexa for Apps V2.

Prerequisites

Before you can add Alexa for Apps to your own skill, you need the following items:

Your own Alexa custom skill.
An iOS or Android app with available deep links, or a website.

Important: Child-directed skills aren't currently eligible to use deep links. If you have a child-directed skill that you'd like to have considered for Alexa for Apps, contact alexaforapps-help@amazon.com.

High-level steps to add Alexa for Apps to your custom skill

The following steps show you how to add Alexa for Apps to your skill:

Step 1: Add app and website metadata to your skill manifest (skill.json)
Step 2: Edit your skill endpoint to send deep links
Step 3: Test your Alexa for Apps V2 skill

Step 1: Add app and website metadata to your skill manifest (skill.json)

In this step, you specify in your skill manifest which apps and websites your skill links to, and provide information about each one.

Tip: Instead of directly updating the manifest of an existing AWS-hosted skill by using the get-skill-manifest and update-skill-manifest CLI commands, you can clone the entire skill to migrate it to your local machine. You perform the clone by using the ask clone (ASK CLI 1) or ask init (ASK CLI v2) command. Make sure to specify the profile name (ask init -p <profile-name>) when you first clone an existing skill to avoid any potential issues with the update.

To add app and website metadata to your skill manifest

If you haven't already, install the ASK CLI as described in Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI).
Open the command prompt.
To download the skill manifest for your custom skill to a new file named skill.json, enter the string for the get-skill-manifest CLI command as shown in the following example:

ask smapi get-skill-manifest -s <skill-id> -g <stage> > skill.json
To declare support for Alexa for Apps in your skill manifest, add a type property with value APP_LINKS_V2 in the interfaces array (manifest.apis.custom.interfaces), as shown in the following example:
```
   {
      "type":"APP_LINKS_V2"
   },
```

To add metadata to your skill manifest for the apps your skill links to, add an appLink object under manifest.apis.custom.appLink, as shown in the following City Guide skill example with a localized name in German.

Note: You can only specify localizedNames values for the locales that you included in the manifest.publishingInformation.locales section of your skill manifest.

Important: In your own skill manifest, omit the lines "ALEXA FOR APPS ADDITIONS START" and "ALEXA FOR APPS ADDITIONS END".

{
   "manifest": {
      "apis": {
         "custom": {
            "endpoint": {
               "uri": "..."
            },
            "interfaces": [
               {
                  "type": "APP_LINKS_V2"
               }
            ],
   ================== ALEXA FOR APPS ADDITIONS START ==================
            "appLink": {
               "linkedApplications": [
                  {
                     "friendlyName":{
                        "default":"CityGuide",
                        "localizedNames": [
                           {
                              "locale":"de-DE",
                              "name":"Stadtführer"
                           }
                        ]
                     },
                     "catalogInfo": {
                        "type": "IOS_APP_STORE",
                        "identifier": "id123456789"
                     },
                     "customSchemes": [
                        "cityguide://",
                        "ctgd://"
                     ],
                     "domains": [
                        "cityguide.com",
                        "ctgd.com"
                     ]
                  },
                  {
                     "friendlyName":{
                        "default":"CityGuide",
                        "localizedNames": [
                           {
                              "locale":"de-DE",
                              "name":"Stadtführer"
                           }
                        ]
                     },
                     "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 ADDITIONS END ==================
         }
      }
   }
}

To be able to send push notifications in the non-mobile flow, declare the skill permission "alexa::devices:app:push_notifications" inside the permissions array in your skill manifest, as shown in the following example.
Note: Your skill only needs to declare the permission in the manifest. It doesn't need to handle checking or enabling the status of the permission at runtime. The Alexa for Apps API handles the permissions on behalf of your skill.
```
"permissions": [
   {
     "name": "alexa::devices:app:push_notifications"
   }
],
```

For mobile-specific commands, update the description and examplePhrases attributes for your skill in the manifest.publishingInformation.locales section of your skill manifest. Or update this information in the Alexa developer console at any time before you test and publish your skill. Make sure to let customers know what mobile apps your skill can access, and provide sample utterances that work on mobile. If the skill only works on mobile devices, be sure to let your customers know that as well. The following example shows how to update these attributes for the City Guide skill.

{
   "locales": {
      "en-US": {
         "name": "City Guide",
         "smallIconUri": "<s3 link>",
         "largeIconUri": "<s3 link>",
         "summary": "Find your way with City Guide!",
         "description": "Search faster with City Guide on mobile devices! Try saying, Alexa, ask City Guide to search for boba! Asking Alexa for walking directions, now also shortcuts you into the app to see the live tracking map!",
         "examplePhrases": [
            "Alexa, ask City Guide for coffee shops near me",
            "Alexa, ask City Guide for the bus schedule",
            "Alexa, ask City Guide for walking directions to My Favorite Landmark!"
         ],
         "keywords": []
      },
   }
}

Tip: "To minimize utterance conflicts, use the pattern "Ask <Skill Name> to <do action>" in your example phrases, even if "<do action> in <App Name>" flows better."

To upload the updated skill manifest for your custom skill, use the update-skill-manifest CLI command as shown in the following example.
```
ask smapi update-skill-manifest -s <skill-id> -g <stage> --manifest <manifest>
```
Note: The --manifest parameter value must be a JSON string, not a filename.

Step 2: Edit your skill endpoint to send deep links

In this step, your skill examines each incoming request to determine whether it originated from a device that supports Alexa for Apps. Your skill also examines the originating platform (Android or iOS) and locale.

To edit your skill endpoint to send deep links

To make sure the customer's device supports Alexa for Apps, check whether the context.System.device.SupportedInterfaces object includes an AppLink field, with the following structure.
```
   "AppLink": {
      "version": "2.0"
   }
```
When the incoming request comes from a mobile device, your skill can directly launch app links on the customer's phone.
To determine whether this mobile experience is possible, check the AppLink.directLaunch field in the context object.
Note: The context.AppLink object in this step is in a different part of the skill request than the AppLink field in the previous step.

In the following example, the field includes the key IOS_APP_STORE, indicating that the request came from an iOS device.

Note: The directLaunch.IOS_APP_STORE field value is an empty object. This indicates that the mobile (direct launch) experience is enabled.
```
"AppLink": {
     "directLaunch": {
         "IOS_APP_STORE": {}
     }
 }
```
In the following example, the field includes the key GOOGLE_PLAY_STORE, indicating that the request came from an Android device.

Note: The directLaunch.GOOGLE_PLAY_STORE field value is an empty object. This indicates that the mobile (direct launch) experience is enabled.
```
"AppLink": {
     "directLaunch": {
         "GOOGLE_PLAY_STORE": {}
     }
 }
```
When the incoming request comes from an Alexa-enabled device, such as an Amazon Echo Dot, your skill can send links to a customer's mobile device in a notification from the Alexa app.
To determine whether your skill can send links, check the context.AppLink.sendToDevice object.

The following example shows a skill that receives requests from iOS devices.

Note: The directLaunch.IOS_APP_STORE and sendToDevice field values are empty objects. This indicates that both directLaunch and sendToDevice are enabled.

Tip: To save time when you implement Send to Phone (sendToDevice) interactions, use AMAZON.SendToPhoneIntent. This standard built-in intent covers many different utterances such as "send it to my phone" or "send me the link." For details about using built-in intents, see Implement a built-in intent.

Tip: You might choose to use sendToDevice even if the customer is on a mobile device, in order to be less intrusive – for example, if you want to send the customer a link to information that they can review later.

Important: In your own skill, omit the lines "ALEXA FOR APPS ADDITIONS START" and "ALEXA FOR APPS ADDITIONS END".
```
{
"version": "1.0",
"session": {...},
"context": {
   "System": {
      "device": {
         "deviceId": "string",
         "supportedInterfaces": {
            "AudioPlayer": {...},
================== ALEXA FOR APPS ADDITIONS START ==================
             "AppLink": {
                "version": "2.0"
             },
================== ALEXA FOR APPS ADDITIONS END ====================
         }
      },
      "application": {
         "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {...},
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
   },
   "AudioPlayer": {...},
================== ALEXA FOR APPS ADDITIONS START ==================
   "AppLink": {
      "directLaunch": {
          "IOS_APP_STORE": {}
      },
      "sendToDevice": {}
   }
================== ALEXA FOR APPS ADDITIONS END ====================
},
"request": {...}
```
If your skill sends different links for different locales, have your skill first determine the locale of the requesting device by checking the handlerInput.requestEnvelope.request.locale property.
Note: Your skill only receives requests from locales where you distribute your skill. For details, see Develop Skills in Multiple Languages.

Tip: Because the locale is available in every request, consider using locale to determine which deep link to send. If your deep links vary by country instead of locale, your skill must request permission from the customer to access the customer's country. One way to perform this request is to access the device address that the customer registered with Alexa. For details, see Enhance Your Skill With Address Information. You can also access a customer's real-time location, although that doesn't necessarily reflect the customer's iOS App Store or Google Play Store country association. For details about real-time location services, see Location Services for Alexa Skills.
To send deep links to an app or website, place a Connections.StartConnection directive in the response body of your skill connection request.
Along with the deep links, provide a topic, which is a prompt that helps the customer know what the deep-link does (for example, "Check your messages" or "See your flight status").

(Optional) Play text-to-speech (TTS) (response.outputSpeech) as you normally would in your skill response as part of the call to Alexa for Apps. For example, a travel skill might say, "Your flight is on time, leaving Los Angeles International Airport at 2:15 PM.". For more details on the connection request, see Alexa for Apps Skill Connection Request Reference.

Important: Because the topic field controls the voice response that the customer hears during send-to-phone exchanges, it should clearly state the reason for the link. In English, the topic is typically a verb-first call to action. For example, if the topic field is "check flight status", Alexa says something like, "I'll send a link to Janet to check flight status."

The following example shows a sample connection request.

{
    "version": "1.0",
    "sessionAttributes": {},
    "response": {
        "outputSpeech": {
            ...
        },
        "card": {
            ...
        },
        "reprompt": {
            ...
        },
        "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
          {
            "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": "see your search results"
                }
            }
        }
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
    }
}   

After the skill connection request is complete, your skill receives a response showing the success or failure of the primary deep link action and the fallback, along with a reason for failure cases. Your skill should always handle a SessionResumedRequest with the type ConnectionCompleted. In the success case where the customer had the app directly open on their phone (directLaunch), the skill can clean up and end so that the rest of the interaction occurs on the mobile app or website. If both the primary and fallback are unsuccessful on mobile, or any time a request is made on a non-mobile device, the customer can continue interaction in the skill. The following examples show sample responses for a successful direct launch request and a send-to-device request. For send-to-device requests, you can continue the session to interact with the customer.
```
{
   "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"
         }
      }
   }
}
```
For details about the response payload, see Skill connection response reference.

Note: For safety purposes, by default, deep link requests fail when the customer is driving. When a customer makes a request from an Android or iOS device while they're driving, your skill doesn't receive a directLaunch property in the skill request object. If your skill sends a deep link request, by default Amazon sends notification instead of Direct Launch. You can examine the skill request object for the Automotive property if you want to provide a tailored voice response when customers are driving. Please contact Amazon with your skill ID and use case at alexaforapps-help@amazon.com if you believe that your skill should be registered for driving scenarios for Direct Launch app links – for example, you want to deep-link the customer to an application to assist with hands-free navigation or calling.

Step 3: Test your Alexa for Apps V2 skill

Currently the Alexa developer console Test page doesn't send an AppLink object in the skill request. For end-to-end testing, you must test on a mobile device connected to a developer or beta account with access to the skill.

Important: During the Alexa for Apps V2 beta, you can test your skill in the development stage, but you can't certify and publish it.

You can test your skill on any mobile device, by using one of three methods:

Using an Alexa Built-in phone.
Using an Alexa mobile accessory, such as Echo Buds.
Directly from the Alexa mobile app.

You can test using the Alexa mobile app by making a request using the built-in wake capability or by tapping the Alexa icon.

To test your skill on a mobile device

For the mobile experience, test the following items:
- Test that end-to-end use cases work as expected, including app-specific actions.
- Test locked and unlocked devices.
- Test with different locales that your skill supports.
- Test fallback scenarios where the customer hasn't installed the app.
- Test recovery scenarios where the deep link fails (for example, on an unsupported device type). Make sure that the deep link fails in a way that allows your skill to continue its interaction with the customer.

To test your skill in a non-mobile experience

For the non-mobile (Send to Phone) experience, test the following items:
- Test that end-to-end use cases work as expected, including app-specific actions.
- Test tapping push notifications. To receive a push notification, you must:
  1. Enable Notifications in OS Settings for the Alexa app.
  2. Enable Push Notification skill permission in the Alexa app's Skill Settings page for your skill.
- Test tapping the home card in the Alexa app.
- Test with different locales that your skill supports.
- Test fallback scenarios where the app isn't installed.
- Test recovery scenarios where the deep link fails (for example, if the mobile device doesn't have the app installed). Make sure that the deep link fails in a way that allows your skill to continue its interaction with the customer.