Add Rich Media to Your Skill Detail Page

The skill detail page in the Alexa app provides information about your skill. By adding rich media assets, such as images and videos, you can enrich the experience of your skill and use the detail page to teach new and returning customers how to use your skill.

Terminology

This topic uses the following terms:

  • Rich media asset – An image or video that describes, or "previews," the functionality of a skill.

  • Featured frame – An optional custom thumbnail image for the detail page to display when a rich media video asset isn't auto-playing. You must specify the featured frame manually, and you can make it a frame of the video or a separate image.

  • Asset profile – A collection of rich media assets, grouped by viewport mode and asset shape. An asset profile is different from an Alexa Presentation Language (APL) viewport profile. The viewport profile describes the device that renders the APL. In contrast, an asset profile describes the device and the assets.

Prerequisites

Before you upload the rich media assets for the skill detail page, make sure they adhere to the following asset restrictions and guidelines.

Asset restrictions

Alexa enforces the following restrictions on rich media assets under the mobileRectangle asset profile. Note that the asset resolution must be exact to ensure a consistent user experience.

Images

  • Resolution: 1280 x 800 px
  • Aspect ratio: 16:10
  • Maximum file size: 20 MB
  • Supported formats: PNG, JPG

Video

  • Resolution: 1280 x 720 px
  • Aspect ratio: 16:9
  • Maximum file size: 100 MB
  • Duration: 15–60 seconds
  • Supported formats: QuickTime, H.264 MPEG-4 (MP4, MOV)
  • Minimum bit rate: 1200 kbps
  • Resolution: 1280 x 720 px
  • Aspect ratio: 16:9
  • Maximum file size: 20 MB
  • Supported formats: PNG, JPG

Asset guidelines

Make sure that your images and videos meet Amazon policy guidelines. For more details, see Policy Requirements. For depictions of Echo devices in rich media content, please refer to the Echo Branding Guidelines and the Review Process. In addition, rich media content on skill detail pages must be appropriate for all ages.

Steps to associate rich media with your skill

To associate rich media assets with your skill, perform the following steps:

Step 1: Upload the assets to S3

The first step is to upload the assets to S3 by using the SMAPI Catalog API.

To upload your skill's rich media assets to S3

  1. To use in subsequent steps, get an access token.

    You must provide this token in the Authorization header for all SMAPI requests.

  2. To create a new catalog, make the following POST request.

    For the catalog title, choose a name that's memorable and helps to differentiate it from other catalogs that you own.

    POST /v0/catalogs HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer <SMAPI access Token>

    {
   "title": "<Catalog title>",
   "type": "AMAZON.PreviewMedia",
   "usage": "AlexaSkillStore.Catalog.PreviewMedia",
   "vendorId": "<your vendor id>"
}

    You should receive the following response code.

    201 Created

    You should receive the following response body. Make a note of the id (catalogId) value for use in subsequent steps.

    {
   "associatedSkillIds": [],
   "createdDate": "<date>",
   "id": "<catalogId>",
   "lastUpdatedDate": "<date>",
   "title": "<Catalog title>",
   "type": "AMAZON.PreviewMedia",
   "usage": "AlexaSkillStore.Catalog.PreviewMedia"
}
  3. To use in subsequent steps, make a note of the id (catalogId) value.

  4. To associate the catalog with your skill, make the following PUT request. Use the same catalog id value from the previous request. You must perform this step before you can upload assets into the catalog. For more details, see Associate a catalog with a skill.

    PUT /v0/skills/{skillId}/catalogs/{catalogId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer <lwaToken>

    You should receive the following response code.

    201 Created
  5. To populate your AMAZON.PreviewMedia catalog, perform the following steps to create an upload. Each upload is a ZIP file containing one or more rich media assets. For more details, see Create an upload, v0.
    1. Create a ZIP file that adheres to the following restrictions:
      1. The ZIP file can contain no more than seven rich media asset files.
      2. The ZIP file can be no larger than 500 MB.
      3. Each file, unzipped, can be no larger than 100 MB.
      4. Images must be in PNG format.
      5. Videos must be in MOV or MP4 format.
    2. Make the following POST request. 
      POST /v0/catalogs/{catalogId}/uploads HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer <lwaToken>

      You should receive the following response code.

      201 Created

      You should receive the following response body.

      {
   "id": "<uploadId>",
   "catalogId": "<catalogId>",
   "status": "string",
   "locales": [
      "string"
   ],
   "createdDate": "2019-04-06T23:52:20.528Z",
   "lastUpdatedDate": "2019-04-06T23:52:20.528Z",
   "ingestionSteps": [{
      "name": "UPLOAD",
      "status": "string",
      "logUrl": "string",
      "errors": [{
         "code": "string",
         "message": "string"
      }]
   }],
   "presignedUploadParts": [{
      "url": "<signedExpiringS3Url>",
      "partNumber": 1
   }]
}
  6. Make a note of the id (uploadId) value. This value is different from the catalogId. You'll use both values later when specifying your assets in the skill manifest.

  7. To upload the ZIP file to S3, make the following PUT request, by using the url (signedExpiringS3Url) value from the previous step. For more details, see Amazon S3–Uploading Objects Using Presigned URLs.

    PUT <signedExpiringS3Url route> HTTP/1.1
Host: <signedExpiringS3Url host>
Content-Type: application/zip

    You should receive the following response code. This might take a few seconds, depending on the size of the ZIP file.

    200 OK

  8. To mark the upload as complete, make the following POST request.

    POST /v0/catalogs/<catalogId>/uploads/<uploadId> HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer <lwaToken>

    You should receive the following response code. This may take a few seconds, depending on the size of the ZIP file.

    202 Accepted
  9. After you mark the upload as complete, the Alexa team asynchronously validates the contents of the ZIP file.

  10. (Optional) Check the status of validation periodically by making the following GET request. For more details, see Get information about a specified upload, v0.

    GET /v0/catalogs/<catalogId>/uploads/<uploadId> HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer <lwaToken>

    You should receive the following response code.

    200 OK

    You should receive the following response body.

    {
   "catalogId": "<catalogId>",
   "createdDate": "2021-05-19T22:09:27.941Z",
   "file": {
      "presignedDownloadUrl": "<url>",
      "status": "AVAILABLE"
   },
   "id": "<uploadId>",
   "ingestionSteps": [
      {
         "errors": [],
         "logUrl": "",
         "name": "UPLOAD",
         "status": "SUCCEEDED"
      },
      {
         "errors": [],
         "logUrl": "",
         "name": "VALIDATION",
         "status": "SUCCEEDED"
      }
   ],
   "lastUpdatedDate": "2021-05-19T22:11:00.831Z",
   "status": "SUCCEEDED"
}

    The response should provide details on the current status of validation.

  11. To see the current status of the upload validation, check ingestionSteps.[1], the VALIDATION step, periodically.

    Possible states are SUCCEEDED or FAILED. If FAILED, refer to the errors field, ingestionSteps[1].errors, for details. After validation is complete, you can then specify the uploaded assets in the skill manifest.

Step 2: Specify the uploaded assets in the skill manifest

After the upload validation is complete, you have 24 hours to upload an updated skill manifest. This skill manifest should specify the preview media assets in the publishingInformation section of the skill manifest, as shown in the following example.

{
  "manifest": {
    "publishingInformation": {
      "locales": {
        "en-US": {
          "summary": "This is a sample Alexa custom skill.",
          "examplePhrases": [
            "Alexa, open sample custom skill.",
            "Alexa, play sample custom skill."
          ],
          "keywords": [
            "Descriptive_Phrase_1",
            "Descriptive_Phrase_2",
            "Descriptive_Phrase_3"
          ],
          "smallIconUri": "https://smallUri.com",
          "largeIconUri": "https://largeUri.com",
          "name": "Sample custom skill name.",
          "description": "This skill does interesting things.",
          "preview": {
            "assets": {
                "mobileRectangle": {
                    "images": [
                        {
                            "source": {
                                "type": "CATALOG_UPLOAD",
                                "catalogId": "<ID of catalog that contains uploaded asset>",
                                "uploadId": "<ID of upload that contains uploaded asset>",
                                "filePathInUpload": "foo/image.png"
                            }
                        }
                    ],
                    "videos": [
                        {
                            "source": {
                                "type": "CATALOG_UPLOAD",
                                "catalogId": "<ID of catalog that contains uploaded asset>",
                                "uploadId": "<ID of upload that contains uploaded asset>",
                                "filePathInUpload": "foo/bar.mov"
                            },
                            "featuredFrame": {
                                "type": "CATALOG_UPLOAD",
                                "catalogId": "<ID of catalog that contains uploaded asset>",
                                "uploadId": "<ID of upload that contains uploaded asset>",
                                "filePathInUpload": "foo/frame.png"
                            }
                        }
                    ]
                }
            }
        }
      },
      "isAvailableWorldwide": false,
      "testingInstructions": "1) Say 'Alexa, hello world'",
      "category": "HEALTH_AND_FITNESS",
      "distributionCountries": [
        "US",
        "GB",
        "DE"
      ]
    },
    "apis": {
        ...
    },
    "manifestVersion": "1.0",
    "permissions": [
      ...
    ],
    "privacyAndCompliance": {
      ...
    },
    "events": {
      ...
    }
  }
}

To upload the updated skill manifest

  1. Before you upload the updated skill manifest, make sure the manifest adheres to the following requirements:
    • Preview media assets can have a maximum of five images and one video per asset profile. As shown in the previous example, an asset is specific to a locale.
    • In the filePathInUpload field:
      • If the rich media assets were inside a folder in the ZIP file you created, you must specify the folder. For example, consider a ZIP file containing a folder named folder that in turn contains an asset file named asset1.png. The path to that asset file would be folder/asset1.png.
      • If the rich media assets aren't inside a folder, you don't need to specify a folder. For example, consider a ZIP file containing an asset file named asset1.png. The path to that asset file would be asset1.png.
  2. To upload the skill manifest, make a PUT request as directed in Update an existing skill.

Step 3: Verify assets in the skill detail page

To confirm assets for each locale, on your mobile device navigate to the skill detail page in the Alexa app. The set of assets displayed in the Alexa app are determined by the Country/Region settings in your Amazon account. You'll need an Alexa account for each Alexa-supported country where your skill is available.

Was this page helpful?

Last updated: Oct 13, 2023