As an Amazon Associate I earn from qualifying purchases.

[Music] how do you make sure that alexa reports to the customer the right status of the lights cameras or locks and how does alexa know when to trigger a hunch i'm josephine a solutions architect with the alexa smart home team and today we'll talk about enabling proactive experiences with the smallholm api and answer those two questions with your smart home skill you can enable proactive and predictive experiences to help your customers save energy save time and save money or even feel more secure in the smart home maybe you yourself are already using features such as hunches at home hunches are one of those proactive experiences built with state information so how could you enable those delightful experiences for your customers you start by proactively reporting the states of the endpoints that you manage as accurate device states at the foundation of all ambient proactive technology that alexa brings to customers so let's get to it first let's review why we need you to send us state updates then we'll discuss the steps that you need to take today to enable proactive reporting and finally we will review the resources available to you so let's start with the why there are two main benefits to sending state information first it ensures that we are accurately reflecting to customers the current state of the devices in the alexa app and when they ask alexa false information can hurt the trust of customers in both your products and alexa would you want to see in your app that the front door is locked when in fact it's not probably not the second benefit is the proactive features smart features free up time for customer to spend on activities that are important to them customers should be spending less time worrying about the door being locked or the robot vacuum getting started when they're gone we should let alexa worry about all that as we're building our smart home we're adding more hunches more smart features visualize that accurate endpoint states are the foundation of that house and the smart features are built on top of it those type of smart features are driving growth and innovation to make your product even smarter with alexa and provide more value to your customers and back to you we encourage you to work with us and enable your devices to report state information also important note for developers participating in the works with alexa program proactively reporting endpoint state is mandatory to maintain your works with alexa certification so how do you take advantage of these features today we're going to need you to send state and change reports we'll enable state reporting in three steps first you will enable alexa events in your developer console then you will then implement state and change reports for each of the controllers supported in your skill and finally you will test and monitor the accuracy of your reports there are several steps that you need to take in order to send events to alexa first you will enable events in the developer console so let's pause and take a look so where do you go to enable events here you are on the permission tabs of the alexa developer console in our example the option to send alexa event is already enabled when you enable notes the alexa client id and your client secret they are both listed on the same tab you will need those values to request access tokens for each of your customers great for those following at home i just show you where to enable events in the developer console now let's dive deep into what needs to happen next and get our authentication tokens for our customers note that your skill will have to go through certification again it's a big change but do not submit right away let's wait to complete all the steps and be ready first all right now let's proceed with authentication if you're not done already you need to implement the alexa dot authorization interface which is the interface that lets you obtain authentication tokens for each customer and allows your skill to send asynchronous messages to the alexa gateway for example change reports that we're going to talk about in a minute once implemented alexa will send you an accept grant directive every time a customer completes the account linking process so what happens for all your current customers that have already enabled the skill there is a backfilling process alexa will send you an acceptance directive for each and every customers that have previously enabled your skill you must handle the accept grant messages and go through the authentication process you can request support at any point using our contacts form on developer.amazon.com great we just enable events we got our authentication tokens for our customers now we're ready to implement both state reporting change reports so let's review what they do you must report states for all alexa controllers that you have implemented including endpoint health and for each of the endpoints that you manage as well there are two use cases for sending alexa as states or a change report first you need to report the state of a device as soon as you detect a change in the state that's what we call a change report so for example if i turn off my coffee maker which is powered by a smart plug the skilled developer will have to immediately send a change report to alexa to notify the new states the plug is off so let's take a another offline example so i'm walking down the hallway and manually turning off the lights because it still happens that is also a change in the light states i didn't use alexa to turn off the lights but alexa still need to be informed about the states to display the correct information in the app so the skill developer will have to send a change report to alexa as well so you detect a change in the state you send a change report to alexa the second use case for sending state information is when alexa asks you to share the state of the device sends you a report state directive and your answer with a state report that contains state information about the device so for example if i ask alexa what's the temperature in the hallway alexa will send a report state to the skill developer which will report the states in a state report and alexa will tell me that it's actually 24 degrees because sasha's rocks so to recap if the state of an endpoint is changing for any reason you send a change report to alexa if alexa sends you a report state you'll respond with a state report let's stop there for best practices if you receive a directive from alexa to change the state of an endpoint you need to reflect the new state of the device in your response to alexa so for example if i say alexa turn on the living room light alexa sends to the skill developer and alexa dot power controller dot turn on directive and the respond with the new state of the device which is power controller is on the skilled developer must also send a change report in that instance to indicate that the device has a new state so the second best practice is about the json format a change report has two sections in which you can report state a context and a payload in the context you report and change states just contextual information and in the payload you report the change could be multiple in state of the endpoints if the change report json does not include the state in the payload alexa will not know the state of the endpoint and a change report with an empty payload is most likely an error for the third recommendation do not duplicate controller's information in a change report only report the new state of the controller in the payload of the change report if i'm turning on turning off the light do not put turn off in context and turn on or turn off in the payload alexa will not know what to do so do not write in the context the same information to wrap up the implementation of states and change reporting you need to indicate in your discovery response that each of the controllers that you have implemented are supporting both state and change report this is a very important part we've noticed all the time that not updating the discovery response with the right properties is the main reason for failures so how do you update your discovery response you do that by sending the properties proactively reported as true and retrievable as true for each of your controllers proactively reported means that you will send a change report every time the device's state change and retrievable means that you will share the state of the device when alexa prompts you to do so so another important note if you send alexa states or change reports or both and properties in your discovery response are set to false alexa will not acknowledge your messages in this last section let's review the tools available to you to monitor and improve the quality of the data that you're sharing speed matters speed matters when sending reports you need to quickly report states when a customer is asking for the state of a device don't let them wait and you need to let alexa know as soon as the state of the device changes so that alexa is aware of the state of each connected device to send data fast ensure that your fleets can communicate state updates back to your cloud in real time either from the endpoints or via polling mechanisms from your cloud this is your architecture you decide just send messages fast to better explain the level of data quality we're looking for we have set an accuracy bar of 97 for our works with alexa certified partners we measure accuracy by comparing the state of an endpoint that you reported in a change report with the value being reported in the state report following a customer query if reports are always matching then the accuracy is 100 but if they're matching about a third of the time then your accuracy is going to be 33 so if you're missing a couple of change reports your accuracy is going to be lower because we're going to be missing some information so to monitor your performance you can review the analytics provided in the developer console let's take a look so how can you monitor your performance there are multiple tools available to help you monitor your skills performance when it comes to state and change reporting first let's have a look at the tools to monitor the accuracy and latency of your change reports you can access this page by going to your alexa developer console then navigating to the analytics tab of your life skill select the change report tab on the left side you will see two tabs accuracy and latency accuracy tells you how often the state report have matched with the last received change report the percentage score can be read on the left use the workspace alexa bar as a reference now on to latency latency measures the time between a change report received by alexa from the time a directive is sent to the device the clock will start ticking when alexa sends a directive to your cloud and will stop as soon as alexa receives the change report we just took a look at the accuracy and latency metrics now what should you do if you need to dive deeper and review potential issues we have two more tools to help you the smart home state reporter and the smart home debugger let's start with smart home state reporter this is your skill developer console landing page the page where you can see all your skills what you will do is scroll to the bottom and under resources select smart home state reporter we are now in the smart home state reporter on this page you will see that all the devices that are connected to your account in the developer console it is a debugging tool that lets you see what happens with state and change reports you won't be able to see any devices that are not connected to your accounts so you won't see any customer device so here's an example my table lamp is equipped with a smart light bulb which is connected to alexa it's called table lamp due to lack of inspiration the table lists all of the controllers that are supported by the skill for this endpoint and the states associated with each now on my desk my table lamp is actually turned off in the tool i can see what has been reported to alexa on row one we see that brightness controller which controls the brightness of the bulb is at zero and on row three we see power controller is off and it controls the power of the lamp so this is all consistent my lamp is off on my table and it's showing us off in the web app what we're going to do now is trigger a change let's ask alexa to set the table lamp's brightness to 20.

let's refresh the page and click on the query button and we can see some changes now what changed my table lamp is turned on we can see that on row 1 where brightness controller is now at 20 which is what i asked and on row 3 we see that power controller is on so you might have noticed this column on the far right which is called deep query this column tells you if the state retrieved is based on a change report or a state report so if deep query is true it means that the state was retrieved via a state report so alexa sent you a report state and you responded with a state report now if deep query is false it means that the state was retrieved from the last change report you sent this could mean that you did not let alexa retrieve the state of your endpoint so take an action go verify your discovery response and ensure that for each controller you report retrievable true and proactively reported true we just took a look at the state reporter tool now let's dive deep into the smart home debugger the purpose of the debugger is to allow you to view in real time the reports that you are sending to alexa for instance change reports but also other events such as auto update report or delete report but let's just focus on change report so how do you get started you go to a developer portal you find your skill and you select the test tab in this event we just ask alexa to turn on the light and we can see the change report as sent to alexa in the payload along with a note telling us about the success or if you don't see any change report generated you're not sending change reports so take a look at all the resources provided in this video if your change report is not correctly set up or does not send the right events you will see an error message take a look at the documentation so that you can probably address it in the debugger we're seeing change reports but let's take that content out and take a look so this is a change report we see three important components that we talked about earlier endpoints that includes endpoint id a unique identifier and a token which allow alexa to securely link the device to a customer then we see the payload which includes the new states that you need to report everything that is new that has just happened but must be in the payload and finally the context so it provides the states that are unchanged so contextual information goes in the context so i'll pull this one on purpose so do you see what's wrong with this one you guessed it right so the same property is duplicated so i put it in a blue box in the payload i see that there's a new state to be reported the device is turned off so we can see that in the power controller it's highlighted in pink we see power controller off now we can see that the device is online through endpoint health which is highlighted in yellow what doesn't make sense though is to see endpoint health reported as well in the context so did it change or not so if it's in the payload it means that a new event that the device is back online but if it's in the context it means that the device was already reported online before and nothing has changed so seeing it both in payload and context doesn't make any sense alexa cannot make a decision and she will be ignoring the change report let's pause for debugging best practices as a starting point for a live skill leverage live skill monitoring with latency and accuracy metrics to measure the skill performance with this test device linked to your developer account see if the correct state is being updated through the smart home state reporter use the deep query column as an indicator a state that is not retrievable will be marked as false so you will need to address it by updating your discovery response if you see that your state cannot be retrieved at all time you should take a closer look at your state report it could be that you're not reporting the endpoint id correctly for example similarly if a state cannot be retrieved at all but your discovery response is properly set up it might be an authentication issue so try enabling the skill again to go one step further test your change reports with the smart home debugger the debugger will focus on schema validation most of the common errors such as duplicating controllers in the payload or having them both in context and payloads of the change reports or missing endpoints will be caught however there are still some errors that may not be cut such as malforming an endpoint id finally most of the issues you see with state information can be diagnosed and solved with the tools available to you in the console we encourage you to take a look so let's recap state data is the foundation of a smarter home predictive and proactive features that improve engagement and provide value back to you are based on accurate device date to implement state events you need to enable alexa events and backfill authentication tokens for your customers if needed start sending change reports each and every time you detect a change in an endpoint state send report states when alexa sends you a report state directive and speed matters send reports fast here are some good resources for you enable lxi events implement state and change reporting then you test your skill and you view your device states and finally you go to developer console and take a look at the change reports thank you and come enable proactive experiences with us [Music] you