Tutorial: Add Alexa for Apps to Your Custom Skill

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)

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

  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 City Guide skill example with a localized name in German. 
    {
   "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"]
                  }
               ]
            },

  5. 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.

  6. 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>

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

  1. 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.

  2. 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.

    {
"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": {...}
  3. If your skill sends different links for different locales, it should determine the locale of the requesting device by examining handlerInput.requestEnvelope.request.locale.
  4. 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.

  5. 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.

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.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment