Your Alexa Consoles

Your Alexa Consoles
- Skills
- Products

感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Debug Your Smart Home Skill

As you build your smart home skill, you have the following options for debugging it:

State reporting test tool – This tool enables you to view the properties of the smart home devices associated with your skill, and whether your skill is queried for these properties or it proactively reports them to Alexa.
Smart home live debugger – This feature enables you to see the ChangeReport events that Alexa receives for the smart home devices associated with your skill, including processing errors.

These tools enable you to see information about the smart home devices associated with your skill in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. These tools don't show information from other Amazon accounts.

For more information about building a smart home skill with state reporting, see the following topics:

Overview
Prerequisites
How to use the state reporting test tool
How to use the smart home live debugger

Overview

Your smart home skill should notify Alexa when a property of your smart device changes. Your skill notifies Alexa by sending a ChangeReport event to the Alexa event gateway. For more information, see Send Events to the Event Gateway. Sometimes Alexa sends ReportState directives to your skill, in which case your skill should respond with a StateReport.

The state reporting test tool and the smart home live debugger help you understand what Alexa knows about the state of your smart home devices, and why. Specifically, these tools can help you understand the following information:

State reporting test tool

The current state of the smart device's properties.
Whether Alexa received the state in the response to a ReportState directive.

Smart home live debugger

The ChangeReport events that Alexa receives.
Processing errors (if any) for the received ChangeReport events.
Whether the state of the smart device's properties were sent in the payload or the context of the ChangeReport.

You can use these tools together to see a more complete picture of how your skill interacts with Alexa.

Prerequisites

To use the tools, testing tips, and troubleshooting ideas in this topic, you must have a smart home skill that sends state update (ChangeReport) events to the Alexa event gateway when the properties of your smart device change. This means that your discovery response (Discover.Response) indicates "proactivelyReported": true for all capabilities supported by the smart device. If your skill supports proactive reporting for only a subset of the smart device's properties, then you cannot use the tools described in this topic.

How to use the state reporting test tool

The state reporting test tool enables you to see when your skill is queried for the current state of your smart device's properties, or when Alexa relies on the proactive ChangeReport events that your skill sends. The following sections explain how to use it.

Step 1: Get access to the tool

To request access to the state reporting test tool, complete the following steps:

On the Amazon developer portal, sign in with the developer account that is associated with the smart home skill you want to test.
Open the Customer Details page and note your customer ID. You need your customer ID, not your vendor ID.
Open the Developer Support contact page. Use the contact form to send the following information. Replace customer ID with your customer ID from the previous step.

Subject: Alexa

Message: Requesting access to the state reporting test tool for the following customer ID: customer ID

You will be contacted when you are granted access to the tool, or if we need more information.

The state reporting test tool is an add-on to the existing web-based Alexa app. Make sure to use the Alexa app for your region and sign in with the same developer account that you used to request access to the tool.

Important: The tool described in this topic is supported only in the web-based Alexa app and all references to the Alexa app refer to the web-based version.

The following is a list of regions and the corresponding URL for the web-based Alexa app:

United States: alexa.amazon.com
United Kingdom: alexa.amazon.co.uk
Germany: alexa.amazon.de
Japan: alexa.amazon.co.jp
Canada: alexa.amazon.ca
Australia: alexa.amazon.com.au
India: alexa.amazon.in

If you haven't already done so, enable and account-link your smart home skill. For more information about how to do this, see Steps to Build a Smart Home Skill.

Step 3: View and understand the state information

In the Alexa app, navigate to Smart Home and then Devices. If the tool is enabled for your developer account, you see extended debugging information for each device. The following image shows an example device:

Each Capability states line in the tool represents a smart device capability (property) that you marked as proactively reported in your discovery response. It also shows the current state for each property, and whether Alexa queried your skill to determine that state.

For example, in the preceding image the Wireless In-wall Dimmer device has the following property states:

connectivity: OK
brightness: 0
powerState: OFF

The following image explains each part of the capability states line.

Pay special attention to the DeepQuery value. This is a boolean that indicates whether your proactive state update (ChangeReport) events and other event data are being used, or Alexa queried to obtain the value.

DeepQuery: False: Indicates that Alexa used your proactive state update (ChangeReport) events to determine this property's value.
DeepQuery: True: Indicates that Alexa sent a ReportState directive to the skill. The property's value was received in the StateReport event sent by the skill in response.

Step 4: Troubleshoot

If you believe you have properly implemented proactive state updates (ChangeReport events), but the tool shows DeepQuery: True, check the following:

If you are working with a newly discovered device, Alexa's state cache might be empty. Try refreshing the Alexa app in your browser. If your device's properties are not sent in the response to a ReportState directive (if "retrievable": false), you need to send a ChangeReport to populate the cache.
Make sure you indicate "proactivelyReported": true for all of your device's properties, and that you report all property values. This includes the connectivity property of the EndpointHealth interface.
Make sure you only report the values of properties that are defined and reportable for your device. For example, if your device implements the BrightnessController interface, do not report brightnessDelta as proactivelyReported because this is not a reportable property.
For thermostat devices, you might need to toggle between HEAT/COOL and AUTO modes to make sure that Alexa has cached data for all the supported set points that were reported during device discovery.

Step 5: Perform additional tests

After you confirm that all of your device's properties show DeepQuery: False, you should test all of the scenarios for your device that trigger proactive state updates. For each scenario, make sure that the expected property values are shown in the state reporting test tool.

Important: While testing, you should close the Alexa mobile app on any devices where you are logged in as your test user. If the Alexa mobile app is open, it might change the test results because it might periodically send ReportState directives to your skill.

The following are examples of some scenarios that you might want to test.

Change your device state without using Alexa. For example, use another application or the physical device controls to turn a device on or off or change its settings. This should cause your skill to send one or more proactive state updates to the Alexa event gateway. In your browser, refresh the Alexa app to confirm that DeepQuery: False and that the device's properties show the expected state.
Test EndpointHealth proactive state updates. To do this, remove the power or power source from your device and wait for the device's health polling or heartbeat interval to pass. When your skill reports that the connectivity value has changed, refresh your browser and check the Alexa app for the device state. Then restore power to the device and make sure that all properties are correctly updated in the Alexa app.

Note: There is a known issue with the tool that occurs when you are testing EndpointHealth and the skill response is an error. When the tool receives an ErrorResponse, it displays Failed to retrieve state with no additional information. Until this issue is resolved, you should validate this scenario by checking your logs to make sure you are sending the appropriate JSON response and error codes.
Make sure that you are sending proactive state updates for all Amazon accounts that have enabled and account-linked the skill, not just the first or more recent accounts. Commonly, customers in the same household share smart home devices but have their own Amazon accounts associated with the skills for those devices.

The state reporting test tool enables you to see information about the smart home devices associated with your skill only in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. The tool doesn't show information from other Amazon accounts. To test this scenario, enable and account-link the skill from different Amazon accounts using the same device credentials. Then change the state of the device without using Alexa. Sign in with each Amazon account, then use the state reporting test tool to confirm that the property states are accurate and that DeepQuery: False. This helps confirm that your skill is correctly sending ChangeReport events for each Amazon account.

To test this scenario, you must have at least two Amazon accounts that are enabled to use the tool. Refer to Step 1 if you need to enable additional accounts. Make sure to log in from the account you want to enable before you send the contact form.

Note: If you receive a 403 Forbidden response when you send events to the Alexa event gateway, this indicates that the user has disabled your skill and you can stop sending messages for that user.
Inspect your log responses to make sure that your proactive state updates are sent correctly to the Alexa event gateway.

If you encounter problems with the state reporting test tool, use the Developer Support contact form to let us know.

How to use the smart home live debugger

The smart home live debugger enables you to see the ChangeReport events associated with your smart home devices.

Important: The smart home live debugger is in beta and is subject to change at any time without notice.

Step 1: Access the tool

To view the ChangeReport events for your smart home devices, complete the following steps.

Open the Alexa Skills Kit developer console.
Open the smart home skill associated with your smart home device.
Open the Test page.
At the top of the page, make sure that Device Log and Alexa Smart Home (Beta) are selected.
In the Smart Home (Beta) section of the page, make sure the Smart Home live debugger is enabled toggle is on.

When Alexa receives a ChangeReport event for a smart home device associated with your smart home skill, the event information is added to the device log. For example, see the following image.

Note: The ChangeReport events that you see in the device log are not persistent. When you close your browser tab, the events disappear from the device log. If you open the tool in more than one browser tab, the ChangeReport events appear only in the most recent active browser tab.

For help understanding ChangeReport events in the device log, see the following sections.

If you encounter problems with the smart home live debugger, use the Developer Support contact form to let us know.

Step 2: Understand ChangeReport events

After you complete the steps in the preceding section, the device log shows the ChangeReport events that Alexa receives for the smart home devices associated with your smart home skill in the Amazon account that you use to sign in to the Alexa Skills Kit developer console. You don't see ChangeReport events for devices in other Amazon accounts. Each event in the device log contains a JSON document with details about the ChangeReport that Alexa received.

When your skill sends a ChangeReport event to the Alexa event gateway, you receive an HTTP response from the gateway. For the full list of possible HTTP response codes, see Success and Errors in the Send Events to the Event Gateway topic.

Even when your skill receives a 202 Accepted response from the gateway, there might be errors with the ChangeReport that prevent Alexa from processing it correctly. You can see these processing errors (if any) in the device log. For a complete list of potential errors, see the following section.

ChangeReport processing errors

The following table lists the processing errors that you might see in the smart home live debugger and the reason why. For more information about the ChangeReport event schema, see ChangeReport.

Error Code	Reason
`BEARER_TOKEN_NULL_OR_EMPTY`	The bearer token is missing or empty.
`CAUSE_NULL`	The `cause` object in the `payload` is missing.
`CAUSE_TYPE_NULL_OR_EMPTY`	The `cause` object is missing a `cause` type, or the type is empty.
`CLIENT_ID_NOT_AVAILABLE`	The client ID (customer ID) is missing.
`CONTEXT_NULL`	The `context` object is missing.
`CONTEXT_PROPERTIES_EMPTY`	The `properties` object in the `context` is empty.
`CONTEXT_PROPERTIES_NULL`	The `properties` object in the `context` is missing.
`CONTEXT_PROPERTY_NULL`	A property in the `properties` object in the `context` is missing.
`DIRECTED_USER_ID_NULL_OR_EMPTY`	The directed user ID is missing or empty.
`DUPLICATE_CONTEXT_PROPERTY`	The `context` contains two identical properties.
`DUPLICATE_PAYLOAD_PROPERTY`	The `payload` contains two identical properties.
`DUPLICATE_PROPERTY_MISMATCHED_VALUE`	A single property is reported twice, each with different values.
`ENDPOINT_ID_BLANK`	The endpoint ID is empty.
`ENDPOINT_ID_NULL`	The endpoint ID is missing.
`ENDPOINT_SCOPE_NULL`	The endpoint scope is missing.
`EVENT_ENDPOINT_NULL`	The event endpoint is missing.
`EVENT_HEADER_NULL`	The event header is missing.
`EVENT_NULL`	The event object is missing.
`EVENT_PAYLOAD_NULL`	The event payload is missing.
`HEADER_NAME_NULL`	The header name in the event object is null.
`HEADER_NAMESPACE_NULL`	The header namespace in the event object is null.
`HEADER_PAYLOAD_VERSION_NULL`	The payload version in the header in the event object is null.
`INVALID_ASYNC_EVENT`	The asynchronous response is missing a correlation token.
`INVALID_CHANGE_REPORT`	The `ChangeReport` contains a correlation token. A `ChangeReport` must not contain a correlation token.
`INVALID_HEADER_NAMESPACE`	The header namespace must contain the value `Alexa`.
`INVALID_PAYLOAD`	The payload could not be processed.
`INVALID_PAYLOAD_VERSION`	The payload could not be processed.
`INVALID_PROPERTY`	A property is invalid.
`MISSING_TIME_OF_SAMPLE`	The `timeOfSample` field in the `properties` object is missing.
`MISSING_UNCERTAINTY_IN_MILLIS`	The `uncertaintyInMilliseconds` field in the `properties` object is missing.
`NEGATIVE_TIME_OF_SAMPLE_DIFFERENCE`	The `timeOfSample` field contains a time that is after the `ChangeReport` was received.
`NEGATIVE_UNCERTAINTY_IN_MILLIS`	The `uncertaintyInMilliseconds` field contains a negative number. This number must be positive.
`PAYLOAD_PROPERTIES_EMPTY`	The `properties` object in the `payload` is empty.
`PAYLOAD_PROPERTIES_NULL`	The `properties` object in the `payload` is missing.
`PAYLOAD_PROPERTY_NULL`	A property in the `properties` object in the `payload` is missing.
`REQUEST_NULL`	The body of the request is missing.
`SCOPE_INVALID`	The endpoint scope is invalid.
`TIME_OF_SAMPLE_LARGER_THAN_THRESHOLD`	The `timeOfSample` field contains a time that is more than three seconds after the `ChangeReport` was received.
`UNCERTAINTY_IN_MILLIS_LARGER_THAN_THRESHOLD`	The `uncertaintyInMilliseconds` field contains a number larger than 14,400,000.
`UNKNOWN_PAYLOAD_VERSION`	The payload version is unsupported.
`USER_IDENTIFIER_NULL_OR_EMPTY`	The user ID is missing or empty.

Example ChangeReport events in the smart home live debugger

The following are examples of ChangeReport events that you might see in the live debugger.

Example ChangeReport event (success)

{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportSuccess",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "request": {
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      },
      "event": {
        "header": {
          "messageId": "abc-123-def-456",
          "namespace": "Alexa",
          "name": "ChangeReport",
          "payloadVersion": "3"
        },
        "endpoint": {
          "endpointId": "endpoint-001",
          "cookie": {
            "path": "/path/for/this/endpoint"
          }
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}

Example ChangeReport event (processing error)

{
  "header": {
    "customerId": "A1E2P2455A5NYT",
    "skillId": "amzn1.ask.skill.awer45bc-f5f7-6f9b-5f24-c3d5f6821d4f",
    "skillStage": "development",
    "eventType": "SmartHomeChangeReportFailure",
    "messageId": "89bb25e2-9f6c-42b8-8982-ff1dc038c58c",
    "applianceId": "ALL"
  },
  "payload": {
    "errors": [
      {
        "code": "Duplicate_Payload_Property",
        "message": "duplicate property in the payload for brightness property"
      }
    ],
    "proactiveStateRequest": {
      "context": {
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 60000
          },
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "OK"
            },
            "timeOfSample": "2017-07-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      },
      "event": {
        "header": {
          "messageId": "abc-123-def-456",
          "namespace": "Alexa",
          "name": "ChangeReport",
          "payloadVersion": "3"
        },
        "endpoint": {
          "endpointId": "endpoint-001",
          "cookie": {
            "path": "/path/for/this/endpoint"
          }
        },
        "payload": {
          "change": {
            "cause": {
              "type": "PHYSICAL_INTERACTION"
            },
            "properties": [
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              },
              {
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 85,
                "timeOfSample": "2017-07-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
              }
            ]
          }
        }
      }
    }
  }
}