Rendering Images on Cards
It’s been said that a picture is worth a thousand words. It wouldn’t be a great idea to have a card with a thousand words in it, but adding an image to a card could carry just as much value.
For example, suppose that we want to return a card in response to scheduling a trip. The card could include text describing the planned trip and be informative. But including an image of the destination along with that information will provide an enormous amount of visual value to the card.
We’ll start by adding new language-specific strings for the new card’s title and content to languageStrings.js:
| | module.exports = { |
| | en: { |
| | translation: { |
| | ... |
| | SCHEDULED_CARD_TITLE: 'Enjoy your trip!', |
| | SCHEDULED_CARD_MSG: "You're all set for a trip to {{destination}}, " + |
| | "leaving {{departureDate}} and returning {{returnDate}}!", |
| | ... |
| | } |
| | }, |
| | es: { |
| | translation: { |
| | ... |
| | SCHEDULED_CARD_TITLE: 'Enjoy your trip!', |
| | SCHEDULED_CARD_MSG: "You're all set for a trip to {{destination}}, " + |
| | "leaving {{departureDate}} and returning {{returnDate}}!", |
| | ... |
| | } |
| | } |
| | } |
Speaking of the card, we’ll need to use a standard card instead of a simple card if we want the card to include an image. Recall that simple cards only carry a title and some text, and standard cards let us include an image. To add a standard card to the response, we’ll call WithStandardCard() on the response builder:
| | const ScheduleTripIntentHandler = { |
| | ... |
| | async handle(handlerInput) { |
| | ... |
| | const cardTitle = handlerInput.t('SCHEDULED_CARD_TITLE'); |
| | const cardContent = handlerInput.t('SCHEDULED_CARD_MSG', |
| | { |
| | destination: destination, |
| | departureDate: departureDate, |
| | returnDate: returnDate |
| | }); |
| | const baseUrl = 'https://starport75.dev/images/planets/'; |
| | const smallImageUrl = baseUrl + destination.toLowerCase() + '_sm.jpg'; |
| | const largeImageUrl = baseUrl + destination.toLowerCase() + '_lg.jpg'; |
| | |
| | return handlerInput.responseBuilder |
| | .speak(speakOutput) |
| » | .withStandardCard(cardTitle, cardContent, smallImageUrl, largeImageUrl) |
| | .withShouldEndSession(true) |
| | .getResponse(); |
| | }, |
Before building the response, the card’s title and content are retrieved by calling the t() function on handlerInput. In the case of SCHEDULED_CARD_MSG, we pass an object with the destination and travel dates to fill in placeholders in the string.
As for the image, there are two image URLs, one for a small version of the image (approximately 720 pixels by 480 pixels) and one for a large version (approximately 1200 pixels by 800 pixels). The images for each destination are served from Amazon’s S3 storage service and are named such that we can construct the S3 URLs by using the destination name normalized to lowercase. Only one of the images will be displayed, depending on the capabilities of the device viewing the card.
With the card’s title, content, and image URLs prepared, we simply call WithStandardCard() on the handlerInput to include the card in the response. Note that both image parameters are optional. If both are left off, the card will appear as a simple card. If only one image is given, it will be assumed to be the small image and will be scaled up if displayed on a device with a high resolution. Therefore, it’s best to include both images to avoid potential image quality issues that might result from scaling the small image.
After deploying our changes, we can see what the card will look like by planning a trip and the viewing the card in the companion application. For example, if we were to schedule a trip to Saturn, the resulting card might look like this:
Adding an image of the planet to the card adds a little pizzazz and makes it clear that this card has something to do with a trip to Saturn.
Cards are typically viewed in the Alexa companion application. But they may also appear on the screen of a screen-enabled device such as an Echo Show or Fire TV. For example, if we were to plan a trip to Saturn on an Echo Show, the card would be displayed like the image on the device’s screen at the end of the scheduling process as shown.
Notice that the card is a bit more spread out due to the fact that it has more screen resolution to work with. Even so, it’s still the same card that was shown in the companion application, just formatted differently.