Add Rich Media to Your Skill Detail Page
Rich Media on Skill Detail Pages is currently in limited preview. To request access, email alexarichmedia@amazon.com.
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.
Note: In private beta, only one asset profile is supported:mobileRectangle
, for a rectangular asset to be displayed on a mobile device. Assets in this profile appear on the Alexa companion app.
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
Featured frame
- 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
- Step 2: Specify the uploaded assets in the skill manifest
- Step 3: Verify assets in the skill detail page
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
-
To use in subsequent steps, get an access token.
You must provide this token in the
Authorization
header for all SMAPI requests. -
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" }
- To use in subsequent steps, make a note of the
id
(catalogId
) value. -
To associate the catalog with your skill, make the following
PUT
request. Use the same catalogid
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
- 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.- Create a ZIP file that adheres to the following restrictions:
- The ZIP file can contain no more than seven rich media asset files.
- The ZIP file can be no larger than 500 MB.
- Each file, unzipped, can be no larger than 100 MB.
- Images must be in PNG format.
- Videos must be in MOV or MP4 format.
- 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 }] }
- Create a ZIP file that adheres to the following restrictions:
- Make a note of the
id
(uploadId
) value. This value is different from thecatalogId
. You'll use both values later when specifying your assets in the skill manifest. -
To upload the ZIP file to S3, make the following
PUT
request, by using theurl
(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
-
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
- After you mark the upload as complete, the Alexa team asynchronously validates the contents of the ZIP file.
-
(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.
-
To see the current status of the upload validation, check
ingestionSteps.[1]
, theVALIDATION
step, periodically.Possible states are
SUCCEEDED
orFAILED
. IfFAILED
, 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
- 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 namedasset1.png
. The path to that asset file would befolder/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 beasset1.png
.
- 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
- 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.
Related topics
Last updated: Oct 13, 2023