Tutorial: Add Alexa for Apps to Your Custom Skill

Important: Alexa for Apps is a developer preview and might change as Amazon receives feedback and iterates on the feature. To use this feature, you must register for the preview. If you have questions or feedback about Alexa for Apps, please email alexaforapps-help@amazon.com.

To add Alexa for Apps to your custom skill, you need to add app and website metadata to your skill manifest, edit your skill endpoint to send deep links, and then test and publish your skill. In this tutorial, you'll learn how to add Alexa for Apps with an example custom skill called "City Guide."

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

Prerequisites

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

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

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 3: Edit your skill endpoint to send deep links
Step 3: Test and publish your 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 skill by using the get-skill-manifest and update-skill-manifest CLI commands, you can clone the entire skill. You perform the clone by using the ask clone (ASK CLI v1) 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

Install the ASK CLI as described in Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI).
To download the skill manifest for your custom skill to a new file named skill.json, use the get-skill-manifest CLI command as follows:

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 in the interfaces array (manifest.apis.custom.interfaces), as shown in the following example:
```
   {
      "type":"APP_LINKS"
   },
```

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 line "ALEXA FOR APPS ADDITIONS START".

{
   "manifest": {
      "apis": {
         "custom": {
            "endpoint": {
               ...
            },
            "interfaces": [
               {
                  "type": "APP_LINKS"
               }
            ],
   ================== 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.android.ctgdmobile"
                  },
                  "customSchemes": ["cityguide://","ctgd://"],
                  "domains": ["cityguide.com","ctgd.com"]
                  }
               ]
            },    

To let customers know how to use your skill on mobile devices, consider updating the description and examplePhrases attributes for your skill,. You can update these attributes directly in the manifest.publishingInformation.locales section of your skill manifest. Or, if you prefer, you can update this information in the Alexa developer console at any time before you test and publish your skill. Be sure to let users know what mobile apps your skill can access, as well as sample utterances that work on mobile. If the skill only works on mobile devices, you should let 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": []
      },
   }
}

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 follows.
```
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. It also examines the originating platform (Android or iOS) and locale.

To edit your skill endpoint to send deep links

To make sure the user's device supports Alexa for Apps, your skill should examine whether the context.System.device.SupportedInterfaces object has an AppLink field.

To determine whether the request came from an Android device or an iOS device, your skill should examine the context.AppLink.supportedCatalogTypes field. If the request came from an iOS device, this field has the value ["IOS_APP_STORE"]:

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

If the request came from an Android device, this field has the value ["GOOGLE_PLAY_STORE"]:

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

The following example shows a skill receiving a request from an iOS device.

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": {...},
             ================== 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": {
      "supportedCatalogTypes": ["IOS_APP_STORE"]
   },
   ================== ALEXA FOR APPS ADDITIONS END ====================
},
"request": {...}

If your skill sends different links for different locales, it should determine the locale of the requesting device by examining handlerInput.requestEnvelope.request.locale.
Note: Your skill only receives requests from locales where you distribute your skill. See Develop Skills in Multiple Languages.

Tip: Because the locale is available in every request, consider using locale to determine which deep link you should send. If your deep links vary by country instead of locale, your skill must request permission from the user to access the user's country. One way to perform this request is to access the device address that the user registered with Alexa. For details, see Enhance Your Skill With Address Information. You can also access a user's real-time location, although that doesn't necessarily reflect the user's App Store country association. For details about real-time location services, see: Location Services for Alexa Skills.
Alexa for Apps supports universal links, custom schemes, Android intents, and Android Package Manager app launch links. For details, see Deep link types. To send a deep link to an app or website, your skill connection request must have a Connections.StartConnection directive in the response body. For details, see Skill connection request payload example.
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, the skill can clean up and end so that the rest of the interaction occurs on the mobile app/website. For failure cases where the primary and fallback were unsuccessful, or where the primary encountered an error without attempting fallback, you have the option to continue interaction in the skill so the customer can complete their request by voice.

The following example shows a response:
```
{
   "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"
         }
      }
   }
}
```
For details about the response payload, see Skill connection response reference.

Note: 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 us at alexaforapps-help@amazon.com.

By default, deep link requests fail when the user is driving, for safety purposes. When a customer makes a request while they're driving, your skill doesn't receive an AppLink property in the skill request object. But if your skill sends a deep link request anyway, it receives an INVALID_STATE error response. You can examine the skill request object for the Automotive property if you want to provide a tailored voice response when users are driving. Please contact us 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 example, you want to deep-link the user to an application to assist with hands-free navigation or calling.

Step 3: Test and publish your skill

Test your 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.

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

Using an Alexa Built-in Phone.
Using a 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.

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 app isn't installed.
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 user.

Certify and publish your skill

After you upload your manifest, make runtime changes to your Lambda function, and test on a mobile device, you can proceed to publish (or republish) your skill. You can certify and publish your skill by using the ASK CLI submit-skill-for-certification. For more details, see Skill Certification and Publication. Or, if you prefer, you can use the Alexa console for this step.

The following example shows the submit-skill-for-certification command:

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

The submit-skill-for-certification command defaults to auto-publishing. If you specify MANUAL_PUBLISHING to certify your skill but not publish it, you must separately run the publish-skill subcommand to set your release date.

Your skill follows the normal publishing flow as any other custom skill including basic verification and ensuring that it adheres to Alexa skill policies. During the Alexa for Apps developer preview, you must also (re-)validate your skill.json by sending it to alexaforapps-help@amazon.com any time the Alexa for Apps portion of the manifest changes.