Steps to Add Alexa Advertising ID to Your Skill

You can use the Alexa advertising ID in your skill to deliver interest-based ads or generate advertising analytics. When you indicate that your skill delivers advertising, Alexa sends your skill a unique advertising ID and the customer preference for receiving interest-based ads. For an overview of the advertising ID, see About Alexa Advertising ID.

Complete the following steps to add Alexa advertising IDs to your Alexa custom skills, Alexa music skills, and video skills for Echo Show.

Advertising object

For certified skills that declare advertising, Alexa includes the advertising object in the request to the skill. The object provides customer preferences for in-skill advertising.

Property Description Type Required

advertisingId

Customer-resettable, unique identifier that maps to the ifa attribute of the OpenRTB API specification.

Formatted as a version 4 UUID string separated by dashes (8-4-4-4-12).
Example: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367

String

Yes

limitAdTracking

Indicates whether the customer wants to receive interest-based ads. Set to true when the customer opts out of interest-based ads and tracking.
The limitAdTracking property maps to the lmt attribute of the OpenRTB API specification.

Boolean

Yes

Prerequisites

To use the advertising object, your skill must meet the following requirements:

Steps to add advertising ID

Complete the following steps to add the advertising object to your Alexa custom skills, music skills, and video skills for Echo Show.

  1. Design your skill for advertising ID.
  2. Access the advertising ID in your code.
  3. Declare that your skill delivers advertising (custom and music skills only).
  4. Test and certify your skill.

Step 1: Design your skill for advertising ID

Design your skill to use the advertising object from each request. In your code, precede any access to the advertisingId with code to verify the limitAdTracking flag. If limitAdTracking == true, you must honor the customer's choice and disable tracking.

Don't cache the advertising properties because the customer can reset their ID and change their preference to receive interest-based ads at any time during or after the skill session. Alexa sends the latest values in the next request to your skill. Don't associate the new advertisingId with a previous advertisingId or data tied to a previous advertisingId unless the customer has provided explicit consent for you to do so. Also, don't associate any personal data with the advertisingId unless the customer has provided explicit consent for you to do so.

When the customer chooses not to receive interest-based ads, the advertisingId is available for analytics, but you must disable tracking and interest-based ads.

In some requests, Alexa might not include the advertising object. Design your skill to run with and without the advertisingId.

Step 2: Access the advertising ID in your code

Alexa includes the advertising object in each request to your skill based on your skill type:

  • For custom skills, Alexa includes the Advertising object in the context object in requests to your skill.
  • For music skills, Alexa includes the advertising object in the RequestContext object in requests to your skill. The advertising object is available to music and radio skills.
  • For video skills for Echo Show, Alexa includes the advertising object in the payload of the GetPlayableItemsMetadata API.

Access the advertising object from each request to determine the customer's choice for receiving interest-based ads.

The following examples for music and video skills show settings that indicate that the customer chose not to receive interest-based ads. In custom skills, the examples are the same, but the object name is uppercase, Advertising.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": true
}

"advertising": {
    "advertisingId": "00000000-0000-0000-0000-00000000",
    "limitAdTracking": true
}

The following example shows settings that indicate that the customer chose to receive interest-based ads.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": false
}

Step 3: Declare that your skill delivers advertising

Before Alexa sends your skill the advertising object, you must declare that your skill delivers advertising, and then submit your skill for certification. Your skill won't receive the advertising object until Amazon certifies your skill.

You can declare that your skill delivers advertising in the Alexa developer console. Alternatively, you can update your skill manifest directly to declare advertising in your skill.

To declare advertising in your skill on the Alexa developer console

  1. Sign in to the Alexa developer console.
  2. From the skill list, locate your skill, and then, in the dropdown under ACTIONS, select Edit.
  3. Navigate to the Distribution page.
  4. On the Store Preview page, for Privacy Policy URL, enter a URL that links to your privacy policy, and then click Save and continue.
  5. On the Privacy & Compliance page, for Does this skill contain advertising?, select Yes.
  6. Click the link to read the Alexa Skills Advertising Policy, and then select the check box to acknowledge that you read and comply to the terms.
  7. To save the settings, click Save and continue.

To declare advertising in your skill in the skill manifest

  1. Open your skill manifest file in your editor.
  2. Navigate to the privacyAndCompliance section.
  3. To declare advertising, add the containsAds property set to true.
  4. For each supported locale, include a locales object with the locale string and a privacyPolicyUrl.
    Each locale requires a separate privacy policy URL.
  5. Save your manifest file.
  6. To deploy the changed manifest, use the Alexa Skills Kit Command Line Interface.

The following example shows the skill manifest that declares advertising.

"privacyAndCompliance": {
    "allowsPurchases": false,
    "usesPersonalInfo": false,
    "isChildDirected": false,
    "isExportCompliant": true,
    "containsAds": true,
    "locales": {
       "en-US": {
         "privacyPolicyUrl": "https://www.example-uspolicy.com",
          "termsOfUseUrl": "https://www.example-usterms.com"
        },
        "en-CA": {
         "privacyPolicyUrl": "https://www.example-capolicy.com",
          "termsOfUseUrl": "https://www.example-caterms.com"
        }
    }
}

Step 4: Test and certify your skill

Before you submit your skill for certification, verify that your skill handles the opt-in, opt-out, and reset options for customer preferences.

To avoid delays in certification, make sure that your skill meets the policy requirements for Alexa advertising ID. After you run validation, you can submit your skill for certification.

After your skill receives certification, Alexa includes the advertising object in requests to your skill.

Was this page helpful?

Last updated: May 29, 2024