Add Alexa for Apps to Your Custom Skill

Use Alexa for Apps in your skill to let your customers use Alexa to access content or functionality in your app or web site.

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:

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

Procedure overview

Here are the steps to add Alexa for Apps to 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.

To add app and website metadata to your skill manifest

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

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

  3. 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"
       },
    
  4. 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 example.
    {
       "manifest": {
          ....
       },
       ================== 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"]
             }
          ]
       },    
    
  5. We recommend that you update the description and examplePhrases attributes for your skill, to let customers know how to use your skill on mobile devices. 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. Following is an example:

    {
       "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.

  6. Use the update-skill-manifest CLI command as follows to upload the updated skill manifest for your custom skill:
    ask smapi update-skill-manifest -s <skill-id> -g <stage> --manifest <manifest>
    

Step 2: Edit your skill endpoint to send deep links

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

To edit your skill endpoint to send deep links

  1. To make sure the user's device supports Alexa for Apps, your skill should check whether the context.System.device.SupportedInterfaces object has an AppLink field.
  2. To determine whether the request came from an Android device or an iOS device, your skill should check for the context.AppLink.supportedCatalogTypes field. If the request came from an iOS device, your skill sees this:

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

    If the request came from an Android device, your skill sees this:

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

    Following is an example:

    {
    "version": "1.0",
    "session": {...},
    "context": {
       "System": {
          "device": {
             "deviceId": "string",
             "supportedInterfaces": {
                "AudioPlayer": {...},
                 ================== ALEXA APP LINK ADDITIONS START ==================
                 "AppLink": {...},
                 ================== ALEXA APP LINK ADDITIONS END ====================
             }
          },
          "application": {
             "applicationId": "amzn1.ask.skill.[unique-value-here]"
          },
          "user": {...},
          "apiEndpoint": "https://api.amazonalexa.com",
          "apiAccessToken": "AxThk..."
       },
       "AudioPlayer": {...},
       ================== ALEXA APP LINK ADDITIONS START ==================
       "AppLink": {
          "supportedCatalogTypes": ["IOS_APP_STORE"]
       },
       ================== ALEXA APP LINK ADDITIONS END ====================
    },
    "request": {...}
    
  3. If your skill sends different links for different locales, it should determine the locale of the requesting device by checking handlerInput.requestEnvelope.request.locale. Note that your skill only receives requests from locales where your skill is distributed. See Develop Skills in Multiple Languages.
  4. Alexa for Apps supports universal links, custom schemes, Android intents, and Android Package Manager app launch links. For detailed information, see Deep link types. To send a deep link to an app or website, you need to send a skill connection request with a Connections.StartConnection directive in the response body. See Skill connection request payload example.
  5. After the skill connection request is complete, your skill receives a response indicating 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 neither a primary nor a fallback were successful, 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 is an example 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"
             }
          }
       }
    }
    

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, using one of three methods: using an Alexa Built-in Phone; using a Alexa mobile accessory, such as Echo Buds; or 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.

You should test the following items:

  • Your 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 it fails in a way that allows your skill to continue its interaction with the user.

Certify and publish your skill

After uploading your manifest, making runtime changes to your Lambda function, and testing 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.

An example submit-skill-for-certification command looks like the following:

$ 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'll also need to (re-)validate your skill.json by sending it to alexaforapps-help@amazon.com any time the Alexa for Apps portion of the manifest changes.