Create a Quick Link for Your Custom Task
You can generate a quick link to take your customers to a specific custom task within your custom skill and pass input parameters. For example, you can deep-link customers to a new trivia category in a trivia skill, or to new audio content that you just made available. If your skill can track a customer's online orders with your business by using an order ID, you can pass the order ID from your website to your skill through a quick link. You can then start tracking the order for the customer that's using your skill.
Quick link availability
Quick links for custom tasks have the same requirements and availability as quick links for custom skills, plus a few additional ones:
- Devices: Customers can use quick links to launch skills on these devices: Echo (all versions), Echo Tap, Echo Dot (all versions), Echo Show (all versions), Echo Spot, and Fire TV.
- Locales: Custom skills that are built for
en_AU
,en_CA
,en_IN
,en_GB
,en_US
,fr_CA
,fr_FR
,de_DE
,hi_IN
,it_IT
,ja_JP
,pt_BR
,es_ES
,es_MX
, andes_US
.
Prerequisites
Your skill must meet the following requirements:
- Child-directed skills and HIPAA skills aren't eligible to use quick links.
Your custom task must meet the following requirements:
- It must be a custom task, not an Amazon predefined task.
- It must be live (certified and published) and available in each desired marketplace. For details, see Develop Skills in Multiple Languages and Define Skill Store Details for Publication.
- In the task definition file:
- The
x-amzn-alexa-access-scope
field must be set topublic
, notvendor-private
. - The
components.schemas.Input
object must contain at least one input parameter.
- The
- Skills with a future product site launch date (PSLD) are not eligible for launch until the date specified by the PSLD.
Create your custom task
If you haven't already done so, build a custom task in your skill following the instructions in Implement Custom Tasks in Your Skill.
Make sure you add user-friendly strings for your task title and input parameters, so that they can be displayed to customers on the Quick Links for Alexa web page for your task.
- Task title: The
x-amzn-display-details
field of theinfo
object is a custom extension field to add a user-friendly string and an optional localization mapping for the task title. If nox-amzn-display-details
value is specified, the default value of the title field is used. - Input parameters: The
x-amzn-display-details
field inside theinput
properties of the task component is a custom extension field to add a user-friendly string and optional localization mappings for the task input parameters. If nox-amzn-display-details
field is specified, the name of the property itself inside theproperties
field is used.
For details, see Creating a task definition file.
Generate a quick link for your custom task
The URL for a custom task's quick link has the following syntax: https://alexa-skills.amazon.<domain>/apis/custom/skills/<skill-id>/tasks/<custom-task-name>/versions/<task-version>?<task-input-key1>=<task-input-value1>&<task-input-key2>=<task-input-value2>
.
Field | Description | Type | Required |
---|---|---|---|
domain |
The domain corresponding to each marketplace in which you will surface your link. | String | Yes |
skill-id |
The skill ID for your skill. | String | Yes |
custom-task-name |
Internal name of your custom task. | String | Yes |
task-version |
Version number for your custom task. | String | Yes |
task-input-key1 |
Name of the first parameter for your custom task. | String | No |
task-input-value1 |
Value of the first parameter for your custom task. | String | No |
https://alexa-skills.amazon.com/apis/custom/skills/
, are case-sensitive, including skill IDs, custom task names, and query strings.To generate a quick link for your custom task
- Locate the
skill-id
for your live custom skill:- Navigate to the Alexa developer console.
- Log in if necessary.
- In the Skills tab, click the Copy Skill ID link under the skill name.
- Use the syntax provided previously and replace
<skill-id>
with the skill ID that you just located.
- Determine the top-level
domain
:- If your skill is available in marketplaces other than the US, it is recommended that you create a separate quick link for each marketplace by setting different domains in the quick link URL for your skill.
- Quick links for your skill can be generated for AU, BR, CA, DE, ES, FR, GB, IN, IT, JP, MX, and US marketplaces.
- For each marketplace in which you want to surface a quick link for your customer skill, select a URL domain from the table below and replace
<domain>
in the syntax previously provided.Marketplace Domain AU .com.au
BR .com.br
CA .ca
DE .de
ES .es
FR .fr
GB .co.uk
IN .in
IT .it
JP .co.jp
MX .com.mx
US .com
Note: Quick links meant for a given marketplace work in other marketplaces as well. However, a customer who clicks a quick link from a different marketplace must sign in with their Amazon credentials for their marketplace to be able to launch your skill. This often means that the customer is signing in to Amazon twice and can lead to a poor customer experience.
For example, suppose a customer in the UK clicks a quick link URL with the.com
domain suffix, while the default Amazon domain for their marketplace is.co.uk
. The customer will most likely first need to sign in to*.amazon.com
, as it is not a domain they visit frequently. After signing in, the customer is redirected to*.amazon.co.uk
, where they may have to sign in again, depending on the time lapsed since their last visit to*amazon.co.uk
. Finally, they are able to see the Quick Links for Alexa page where they can select an Alexa device and launch your skill.
- Add your skill ID to the URL.
- Add your custom task name and version.
If your custom task requires <task-input-key> = <task-input-value>
input parameter-value pairs, you can include them as a standard URL query string. Task parameters must be simple data types, such as strings, numbers, or Boolean values.
Add campaign attribution to your traffic analytics
You can track the number of skill launches coming from individual links surfaced in different online channels. You track the launches by using input parameters in custom tasks in your skill, in combination with query string parameters in the quick link URL.
Your skill can capture traffic analytics for individual ad campaigns that you run online, for example, on different social media channels. To do so, create an input parameter with the name a2z_ref
in each custom task in your skill that you want to surface as a quick link. You can use this parameter in your quick link URL as a query string parameter. You set its value to be a unique string that you can attribute to a particular source. While you're free to create any input parameter you like, and use it to pass attribution strings, the a2z_ref
input parameter exists only for campaign attribution. This parameter doesn't appear in the Quick Links for Alexa web page.
The following steps show you how to add campaign attribution to your traffic analytics.
To add attribution parameters to your quick links
- To create a custom task in your skill, follow the steps listed in Create a task definition file. Or you can use an existing custom task if you have one.
- In the task definition file for the custom task, create an input parameter named
a2z_ref
, of typestring
. -
Implement functionality for this task in your skill's handler code.
If you simply want to offer your launch experience to your customer, you only need to add a new check to your
LaunchRequest
handler'scan_handle
logic. This action checks to see if this is a request for your custom task. The following Python example shows the new check.def can_handle(self, handler_input): return is_request_type("LaunchRequest")(handler_input)\ and handler_input.request_envelope.request.task.name == "<your task name>"
- To make your new or modified custom task live, publish your skill.
- After your custom task is live, create a quick link for this task, include the
a2z_ref
parameter in the URL, and assign it values depending on the campaign you plan to surface online; for example, an ad campaign.
When customers click this quick link to launch your skill, the request carries the value of the a2z_ref
parameter as an input parameter to your custom task. You can then use the parameter for attributing the launch to the corresponding campaign.
Best Practices: Custom task parameters
Custom tasks enhance the functionality of your quick links by supporting deep linking. However, you must protect your and your customers' privacy and security using tasks in your skill. When you design custom task parameters and generate quick links for these tasks, consider the following recommendations:
- Select the right data type for your input parameter. For example, if your input parameter is always going to have a numeric value, pick a numeric data type for the parameter when defining your task.
- If possible, enumerate the values that you plan to use with your input parameters rather than accept free-form strings. Then, you can reject any values coming in from quick link query strings that don't map to this enumeration. This value enumeration prevents misuse of your quick link query parameters by malicious actors.
- When you use the
a2z_ref
attribution parameter, use a predefined string pattern that works for your marketing team. Reject any values that don't match this pattern. For example, your pattern could be<website-or-app-name>_<campaign>
, where<website-or-app-name>
is a string that represents the name of the website or app where you plan to surface the link.<campaign>
is a string that represents a name that you come up with for your marketing campaign. By requiring your marketers to always use this pattern, including the underscore, you can validate the input value that you receive in your custom task handler logic. - Don't include parameter names or values that could reveal personally identifiable information (PII) for your customers. PII data includes things like your customer's name, address, email, and Social Security numbers.
- In some cases, you might want to pass encoded values in the URL parameter and then decode them in your custom task handler logic. When you do this, make sure you indicate through your input parameter description string that this is an encoded value. For example, say you want to encode a discount offer ID and pass it as a parameter in your custom task URL. You later decode the ID in your handler logic before rendering the customer experience. For the custom task input parameter, choose a human-readable name like "Secret Offer ID". This allows the customer to see a string similar to the following on the amazon.com page: "Secret Offer ID: a1b2c3". The string helps the customer understand that this value shouldn't be visible, while also protecting both your customer and your skill.
Related topics
- Create a Quick Link for Your Custom Skill
- Custom tasks and Amazon predefined tasks
- Implement Custom Tasks in Your Skill
Last updated: Sep 10, 2024