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 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, and es_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:

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 the info object is a custom extension field to add a user-friendly string and an optional localization mapping for the task title. If no x-amzn-display-details value is specified, the default value of the title field is used.
  • Input parameters: The x-amzn-display-details field inside the input 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 no x-amzn-display-details field is specified, the name of the property itself inside the properties field is used.

For details, see Creating a task definition file.

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

To generate a quick link for your custom task

  1. Locate the skill-id for your live custom skill:
    1. Navigate to the Alexa developer console.
    2. Log in if necessary.
    3. In the Skills tab, click the Copy Skill ID link under the skill name.
    4. Use the syntax provided previously and replace <skill-id> with the skill ID that you just located.
  2. Determine the top-level domain:
    1. 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.
    2. Quick links for your skill can be generated for AU, BR, CA, DE, ES, FR, GB, IN, IT, JP, MX, and US marketplaces.
    3. 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
  3. Add your skill ID to the URL.
  4. 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

  1. 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.
  2. In the task definition file for the custom task, create an input parameter named a2z_ref, of type string.

  3. 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's can_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>"
  4. To make your new or modified custom task live, publish your skill.
  5. 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.
Was this page helpful?

Last updated: Sep 10, 2024