Add Content to the Home Screen of Alexa Devices

When not responding to user queries, multimodal Alexa-enabled devices cycle through content on the home screen. You can use the Proactive Suggestion API to add a home card to this rotation for users who have your skill enabled.

Example home cards include daily quotes from an inspirational skill, top scores for the week from a game skill, sample questions and answers from a trivia skill, and top facts from a fact skill.

Features

By publishing home cards, your skill can use the following features:

  • Include text and touch events that invoke your skill from the content of your home card.
  • Use a template to bind your data.
  • Have up to five active home cards at a time.
  • Assign start and expiration times for each of your home cards.
  • Schedule home cards to start displaying up to 30 days from the time of publishing.

User experience

Alexa-enabled multimodal devices, such as the Echo Show, cycle through content on the home screen when the user isn't actively interacting with Alexa. This content is a mix of Alexa-provided home cards and developer-submitted home cards. By publishing a home card, you're creating a developer-submitted home card.

As the home screen cycles through cards, a certain number of slots are dedicated to developer-submitted home cards. If Alexa selects your home card, your card displays to users that enabled your skill. Users must also have a device, such as the Echo Show, that's compatible with developer-submitted home cards.

When a user taps on your card, the tap sends a launch request to your skill. Your skill handles the launch request, and takes the user experience from there.

Users can turn off home content across all skills by visiting Settings > Home & Clock (Echo Show 5 only) > Home Content > Your Enabled Skills on their Alexa-enabled multimodal device at any time.

Requirements

To publish home cards, your skill and home card content must meet the following requirements.

Skill requirements

Your skill must meet the following requirements:

  • The skill must be a custom skill.
  • The skill must meet all certification requirements.
  • The skill must be in the live stage.
  • The skill can't fall into one of the following categories:
    • Child-directed – Skills that are directed towards children under 16.
    • Health – Skills that provide health-related information or attempt to collect information about the user's physical/mental health or condition. For details, see Health.
    • Financial – Skills that enable users to access personal financial information. For details, see Financial skills.
    • Mature – Skills that are labeled as mature.

Home card content requirements

The content of the home card must meet the following requirements:

  • Your home card must be related to your skill.
  • Your home card must not upsell, market, or otherwise drive users to a pay wall to access premium content. All content promoted on the Alexa home screen must be accessible with no additional charge or friction upon engaging with the skill.
  • Your home card must meet all policy requirements.
  • At this time, you can't personalize the content of the home card for the user, such as personalized music recommendations, ranking for a trivia game, and so on.
  • During the developer preview, you must schedule your home card to expire within three days of the publishing date. Expiration removes the card from the rotation.

Limits

The following limits apply to home cards:

  • You can have up to five active home cards at a time, regardless of the target recipient of your home cards (that is, your user ID or all skill users). "Active" means not expired and not deleted. To delete a home card, delete the campaign.
  • If Alexa chooses to display a home card, the minimum display time for the home card is two hours.
  • This feature is available only in en-US. In other words, even if the associated skill supports other locales, the home cards are only displayed in en-US.

Templates

To create your home card, you can use the following template.

Text wrapping template

This template lets you provide data such as text and a background image.

Text wrapping home card template.

To use this template, you use the Proactive Suggestion API to create a campaign with the following fields in the suggestion.variants[].content.values[].datasources object.

Data Field Description Required?

displayText

Container for the template data.

Yes

displayText.headerText

Header text (see previous image).
Max character count: 25

No

displayText.primaryText

The largest text on the screen (see previous image).
Max character count: 60

Yes

displayText.secondaryText

Text immediately below the primary text (see previous image).
Max character count: 60

No

displayText.tertiaryText

Text immediately below the secondary text (see previous image).
Max character count: 25

No

displayText.attributionText

Text that identifies that this home card is associated with your skill.
Max character count: 35

No

displayText.hintText

Text that hints what the user can say to use the content. The following rules apply:

  • To represent the wake word, use {WakeWord}. Don't use "Alexa".
  • If you use quotation marks within the hint text, precede the quotation marks with a backslash (\).
  • The max character count is 60, including {WakeWord}.

Example: Try \"{WakeWord}, open Ride Hailer\"

No

displayText.action

The action to take when the user taps the home card. Currently, the only supported action is to send a launch request to your skill. You must use the settings in the displayText.action fields listed next.

Yes

displayText.action.type

The action type. Set to SkillConnection.

Yes

displayText.action.uri

A URI to the skill associated with the home card. Format: connection://AMAZON.ColdLaunch/1?provider=YOUR_SKILL_ID.

Example: connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

Yes

displayText.action.input

Data to pass to the skill. At this time, this functionality isn't supported. Leave this object empty.

Yes

background

Object that contains the URL to a background image to display on the home card.

No

background.backgroundImageSource

A URL to a JPG or PNG image.
Format: https://.
Max height: 1280dp
Max width: 800dp

No

The following is an example of the request body when you create a campaign with this template.

Steps to submit a home card for a custom skill

To add a home card for a custom skill, take the following steps:

  1. Register for the developer preview.
  2. Get your client credentials.
  3. Find your user ID.
  4. Assemble and upload your home card (targeted to your user ID).
  5. Test your home card.
  6. Assemble and upload your home card (targeted to skill users).
  7. (Optional) Check the status of your home card.

Step 1: Register for the developer preview

To sign up for the developer preview, please contact Alexa developer support and indicate that you want to try progressive suggestions on home cards. If accepted into the developer preview, Amazon gives your developer account permission to submit home cards.

Step 2: Get your client credentials

Before you can upload your home card content by using the Proactive Suggestion API, you must get the client ID and client secret for your skill.

To get your client credentials by using the developer console

  1. Sign in to the Alexa developer console and navigate to your skill.
  2. Select the Build tab.
  3. On the left, click TOOLS, and then click Permissions.
  4. Scroll down to the Alexa Skill Messaging section at the bottom of the page, and find the Alexa Client Id and Alexa Client Secret values.
  5. Give your client ID to your contact in the home card preview program, which you registered for in step 1.

You can also get your client ID and client secret by using the Skill Credential API or the Alexa Skills Kit Command Line Interface (ASK CLI) smapi subcommand get-skill-credentials.

Step 3: Find your user ID

In a subsequent step, you test your home card before you make it available to users of your skill. To test your home card, you must target the home card to your user ID the first time you upload your home card by using the Proactive Suggestion API in step 4.

Therefore, in this step you find your user ID. Your user ID is in the session object of requests that Alexa sends to your skill.

To find your user ID

  1. Make sure your skill is enabled in the Alexa Skills Store for the same account you used to develop the skill.
  2. Sign in to the Alexa developer console and navigate to your skill.
  3. Select the Test tab.
  4. In the Alexa simulator text entry box, type Open [your skill invocation name].
  5. In the JSON Input 1 window, find the value of session.user.userId.
    The format of the user ID is amzn1.ask.account.[unique-value].
  6. Copy the user ID (including the amzn1.ask.account prefix) so that you can use it in the next step.

Step 4: Assemble and upload your home card (targeted to your user ID)

You can now assemble and upload your home card. You target your home card to your user ID so that you can test your home card with your own account.

To assemble and upload a home card targeted to your user ID

  1. Assemble the request body that you will use in your POST request to the Proactive Suggestion API. For the format of the request body, see Request body format. Pay particular attention to the following aspects:
    • The suggestion.variants[].content.values[].datasources object – Fill this object with information from a template.
    • The skill ID – Make sure to include your skill ID in the displayText.action.uri field of the template. For example, if your skill ID is amzn1.ask.skill.12345, the value of displayText.action.uri should be connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345.

    • Target – To target the home card to your user ID, use the targeting object. Set the targeting.type to USERS, and include your user ID in the targeting.values list, as shown in the following example. For details, see Users target.

      {
 "suggestion": {
   "variants": [{
     ...
   }]
 },
 "targeting": {
 {
    "type": "USERS", 
    "values": [
     {
         "id": "amzn1.ask.account.[unique-value]"
     }
    ]
 }
 },
 "scheduling": {
 ...
 }
}
    • Scheduling – In the scheduling object, choose a start and end time that encompass when you will test your skill.

  2. Generate an access token by sending a POST request to the Alexa API with the client ID and client secret you found in step 2. The following example shows a curl command that sends a request to generate the token.

    curl -i -XPOST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa::skill_event' https://api.amazon.com/auth/o2/token
  3. Call the Proactive Suggestion API to create a campaign with the request body that you assembled.

Step 5: Test your home card

You can test your home card on your Echo device.

Ensure that your test setup meets the following criteria:

  • Your Echo device is registered to the developer account that you used to create the skill.
  • Your account is testing the live version of the skill, not the development version. For details about how to choose the version of your skill to test, see Test your skill in the developer console.

To test your home card

  1. After you upload your card in the previous step, reboot your Echo device by shutting it down, unplugging it, and then plugging it back in. Alternatively, you can wait two hours for the home card to surface to your device.
  2. On your Echo device, enable Settings > Home & Clock (Echo Show 5 only) > Home Content > Rotate Continuously.
  3. Observe the rotating content on the home screen of the Echo device.
  4. When your home card appears, tap it to make sure your skill launches as expected.

Step 6: Assemble and upload your home card (targeted to skill users)

After you finish testing your home card, you make another POST request to the Proactive Suggestion API. This time you use production settings. Most of the request body is the same as the one you assembled in step 4, except the targeting and scheduling objects as follows.

To assemble and upload a home card targeted to skill users

  1. Start with the request body you used in step 4.

  2. Make the following two changes:

    • Target the home card to skill users – Use the SKILL_SUBSCRIBERS targeting type, as shown in the following example. For details, see Skill subscribers target.
    {
 "suggestion": {
     "variants": [{
       ...
     }]
 },
 "targeting": {
   {
      "type": "SKILL_SUBSCRIBERS"
   }
 },
 "scheduling": {
   ...
 }
}
    • Schedule the card for production – In the scheduling object, choose a start and end time for which you want to surface your home card to users.

  3. Generate an access token by sending a POST request to the Alexa API with the client ID and client secret you found in step 2. The following example shows a curl command that sends a request to generate the token.

    curl -i -XPOST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa::skill_event' https://api.amazon.com/auth/o2/token

  4. Call the Proactive Suggestion API to create a campaign with your updated request body.

(Optional) Step 7: Check the status of your home card

You don't need to re-certify your skill, but your home card must be approved by the Alexa team before Alexa can surface the card to users.

The home card approval process typically takes 24 hours. To check if your home card is approved, call the Proactive Suggestion API to get the campaign. The validation status is in the body of the response.

Best practices

When you create home cards, use the following best practices.

General best practices

Use the following general best practices.

  • Provide context and include content that enables users to view your skill content or skill experience at a glance. Examples:
    • Include a "word of the day" and a definition.
    • Summarize events for "this day in history."
    • Show the average percentage score across users in a given day or week for a trivia skill.
  • Try to frequently update your content to keep your users engaged. Feel free to update your content daily.
  • Don't simply include content that prompts users to open your skill or try an intent that your skill supports.

Background images

If your home card has a background image, use the following best practices.

  • The background image should add value and give context about the content.
  • Avoid images that overflow into "safe zones." Safe zones include the following areas of the home screen:
    • The header space that includes the persistent time/weather.
    • The footer space at the bottom right that includes the three dots for user feedback.
  • Ensure that the headline and hint of the home card are clearly legible on top of the background image. For example:
    • Don't use white on white.
    • The image shouldn't be too "busy."
    • The image should have sufficient contrast with the overlaid headline.
  • Limit the use of text within the background image itself. If you require text in your background image, ensure that the headline and hint of the home card are clearly legible on top of the background image text. In other words, don't have text on text.
  • Avoid embedding fake UI elements, logos, or borders/frames.
Was this page helpful?

Last updated: May 29, 2024