Integrate Quick Links (Beta) Into Your Alexa Custom Skill
Integrating Quick Links (Beta) into your skill is a great way to help users discover your skill and its features without requiring them to remember the utterance or navigate to the specific feature you want to promote. Quick Links provides you with URLs that you can use to share or promote your Alexa skill on your website, in apps, on social media, in emails, and on other marketing channels. You can also create QR Codes to increase user awareness and engagement. Users can open the links on their phone or computer and share them with family and friends.
In this tutorial, we go over how to integrate Quick Links into your skill. We will be using Node.js with the Alexa Skills Kit (ASK) SDK v2 and ASK Command-Line Interface (CLI) v2. We assume that you already have an Alexa Custom Skill, so we will jump straight into creating Quick Links for it.
Quick Links are available across multiple locales and devices, but they are only for custom skills which are certified and published. For more details, check the availability and requirements page.
How It Works
A Quick Link leads users to a web page in a browser or in the Alexa Companion App (if available). Users can choose to launch the skill right away or send a notification to the device to try the skill later. The interface of the Alexa Companion App looks like this:
The Alexa Quick Links landing page on the browser
How to Create Quick Links
There are two types of Quick Links: Skill Launch Quick Link and Deep Linked Quick Link (also referred to as Custom Task Quick Link):
1. Skill Launch Quick Link: This type of Quick Link allows users to directly launch the skill by clicking on it. It is easy to generate, and there is no development effort required. Sample Quick Links (for different marketplaces) that will directly invoke a skill look like this:
https://alexa-skills.amazon.<domain-suffix>/apis/custom/skills/<skill-id>/launch
A Quick Link works across marketplaces, but the experience may vary. This means that the Quick Link generated for IN marketplace will work for US or UK marketplaces also, as long as the skill exists for those marketplaces. Some examples of Skill Launch Quick Links can be seen below:
US marketplace -
https://alexa-skills.amazon.com/apis/custom/skills/amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12/launch
UK marketplace -
https://alexa-skills.amazon.co.uk/apis/custom/skills/amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12/launch
IN marketplace -
https://alexa-skills.amazon.in/apis/custom/skills/amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12/launch
Refer to this documentation for details on selecting the domain suffix.
2. Deep Linked or Custom Task Quick Link: This type of Quick Link allows users to directly launch a particular skill experience by clicking on it. It requires creating a Custom Task (Beta). A sample Quick Link that will directly invoke a skill looks like this:
https://alexa-skills.amazon.<domain-suffix>/apis/custom/skills/<skill-id>/tasks/<task-name>/<task-version>?<parameter>=<value>
This launches the skill experience defined by the task rather than the usual skill launch experience. The task experience can be further customized by passing appropriate parameters. We can provide multiple parameters as needed, just like query-strings of a typical HTTPS GET request. A sample Deep Linked Quick Link looks like this:
https://alexa-skills.amazon.com/apis/custom/skills/amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12/tasks/DailyHoroscope/1?sunSign=aries
This link will launch the skill and trigger the Daily Horoscope experience for a selected sun sign directly instead of the regular skill launch experience which prompts the user to select a sun sign. We can create multiple Quick Links by using different values for the input parameter(s). So, in this case, we can create 12 different Quick Links to respond with daily horoscope for each of the 12 Sun-Signs.
How to Create a Custom Task (Beta)
Custom Tasks are analogous to tasks in real world, but here Alexa or the Alexa skill fulfills the task. We use the following code to handle requests coming to the task.
const DailyHoroscopeTaskHandler = {
canHandle(handlerInput) {
return alexa.getRequestType(handlerInput.requestEnvelope) === 'LaunchRequest'
&& (handlerInput.requestEnvelope.request.task
&& handlerInput.requestEnvelope.request.task.name.endsWith('.DailyHoroscope'));
},
async handle(handlerInput) {
task = handlerInput.requestEnvelope.request.task;
// Get the input parameter or assume a default value if nothing provided
const sunSign = task.input['sunSign'] || "aries";
// Placeholder function to fetch prediction for sun sign
const prediction = getPrediction(sunSign);
return handlerInput.responseBuilder
.speak(prediction)
.getResponse();
}
};We add the task reference to the skill manifest (skill.json) file as follows:
{
"manifest": {
...
"apis": {
"custom": {
...
"tasks": [
{
"name": "DailyHoroscope",
"version": "1"
}
]
}
},
...
}
}We can add more than one task, but it is important to handle the requests gracefully. For each task we need to add a task name and version only to the skill manifest file. More details about the task are added to the skill definition file. The skill package has to be modified by placing the task definition file in the tasks sub-directory of the skill-package directory. The file name has to be <task-name>.<task-version>.json. For e.g. skill-package/tasks/DailyHoroscope.1.json. More details about modifying the skill package can be found here.
The task definition file defines metadata about all the locales the task supports. You should add values for all the locales the skill supports. It should look like this:
{
"openapi": "3.0.0",
"info": {
"title": "Daily Horoscope Predictions",
"version": "1",
"x-amzn-alexa-access-scope": "public",
"x-amzn-display-details": {
"en-US": {
"title": "A task to get daily horoscope predictions on the basis of sun sign"
},
"en-GB": {
"title": "A task to get daily horoscope predictions on the basis of sun sign"
},
"en-IN": {
"title": "A task to get daily horoscope predictions on the basis of sun sign"
},
"hi-IN": {
"title": "दैनिक सूर्य राशि राशिफल के लिए एक task"
}
}
},
"tags": [
{
"name": "daily horoscope"
}
],
"paths": {
"/DailyHoroscope": {
"summary": "Daily horoscope prediction",
"description": "A task to get daily horoscope predictions on the basis of sun sign",
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Input"
},
"examples": {
"DailyHoroscopeExample": {
"summary": "Example input for invoking daily horoscope.",
"description": "Example input for invoking daily horoscope.",
"value": {
"sunSign": "taurus"
}
}
}
}
}
},
"responses": {
"200": {
"description": "When the experience finishes successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessfulResponse"
}
}
}
},
"400": {
"description": "When the given parameters fail validations"
},
"500": {
"description": "When the request fails"
}
}
}
}
},
"components": {
"schemas": {
"Input": {
"type": "object",
"properties": {
"sunSign": {
"type": "string",
"x-amzn-display-details": {
"en-US": {
"name": "Sun Sign Name"
},
"en-GB": {
"name": "Sun Sign Name"
},
"en-IN": {
"name": "Sun Sign Name"
},
"hi-IN": {
"name": "सूर्य राशि का नाम"
}
}
}
}
},
"SuccessfulResponse": {
"type": "object",
"properties": {
"endTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}Refer to this documentation for details on adding Custom Tasks to your skill.
Tip: Remember to provide at least one valid example in the task definition file.
How to Test and Debug Tasks
One key requirement for Quick Links to work is that the Custom Task should be live. That happens when the backend code is deployed to live and the skill is certified and published. It is important to test the Custom Task experience before the skill changes are published to live environment. We will use the ask smapi invoke-skill-end-pointcommand of the ASK CLI v2 to test the development version of the task before the skill is submitted for certification. The command has the following syntax:
ask smapi invoke-skill-end-point -s <skill-id> -g <stage> --endpoint-region=<region-name|default> --skill-request-body file:<input-file.json>
We can test the Custom Task as:
ask smapi invoke-skill-end-point -s amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12 -g development --endpoint-region=default --skill-request-body file:input.json
The response is a JSON text which the skill would have returned when invoked. We can use the same command to test the live version of the Custom Task as well. The input.json file contains a standard request definition to an Alexa skill. A sample input.json file may look like the following:
{
"version": "1.0",
"session": {
"new": true,
"sessionId": "amzn1.echo-api.session.abc1d234-567e-12e3-1234-1abc1234d123",
"application": {
"applicationId": "amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12"
},
"user": {
"userId": "amzn1.ask.account.12345ABCDEFGH"
}
},
"context": {
"System": {
"application": {
"applicationId": "amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12"
},
"user": {
"userId": "amzn1.ask.account.12345ABCDEFGH"
}
}
},
"request": {
"type": "LaunchRequest",
"requestId": "amzn1.echo-api.request.da528275-5aa6-4f69-8038-06efc94d1923",
"timestamp": "2021-01-18T13:11:48Z",
"locale": "en-IN",
"task": {
"name": "amzn1.ask.skill.12345ab1-1234-12ab-a1bc-abc123abcd12.DailyHoroscope",
"version": "1",
"input": {
"sunSign": "aries"
}
}
}
}Refer to this documentation for more details about the invoke-skill-end-point command.
Best Practices
To provide your skill users with the best possible experience, you should:
- Provide valid response for all locales: Quick Links do not include a locale parameter. This allows you to use a single link to work across all locales that your skill supports. Whichever device / locale the user selects, the Alexa skill responds appropriately. Just like the Alexa skill, the Custom Task should also handle requests for all locales that the Alexa skill supports.
- Add campaign attribution: You may want to promote Quick Links for your skill across various social media or marketing channels, but how do you measure the performance of those channels or campaigns? Quick Links allows you to add another parameter a2z_ref=<campaign-name> to your Quick Links. This can be a string or text used to identify the skill, channel, and campaign. You can use the campaign name, for example a2z_ref=dailyhoroscope_twitter. All the metrics are available in the metrics section of the Alexa developer portal.
Conclusion
In this tutorial, we used the Quick Links feature to create shareable links that help users invoke the skill in different ways. Create Quick Links for your Alexa skill and share it with your potential and existing users to deepen engagement with them.
We look forward to seeing what you will build! Keep checking the Amazon Developer Blogs for updates.