Analyze APL viewport sizes and versions used by your customers

The Alexa Developer Console does not currently provide any information about which APL version your customers are using, but this information would be very helpful. With each new APL version developers get more features and components, Amazon's own devices are updated in a timely manner, but APL is also used on third-party devices and therefore you may need to support different APL versions for your skill to provide the same user experience to all customers.

I'll show you one way you can easily create a report using CloudWatch and Log Insights. There are of course other ways to create such a statistic.

This article assumes that you are using the Alexa Skills Kit SDK for Node.js for your skills.

I love logging information, it helps me to find out the root cause in case of an error. For this I define a request interceptor, the code for this is pretty simple.

const LambdaRequestInterceptor = {
  process({ requestEnvelope }) {
    console.log('request:interceptor request=', JSON.stringify(requestEnvelope, undefined, 2));
  }
}

In order for my Interceptor to be taken into account, it must be registered.

const skill = Alexa.SkillBuilders.custom()
  .addRequestInterceptors(
    LambdaRequestInterceptor
  )
  .create()

If you want to learn more about troubleshooting check out the blog article 3 Tips to Troubleshoot Your Custom Alexa Skill's Back End by Benoit Nachawati.

Once you have updated your skill backend, launch your skill and have a look at your CloudWatch log files, you should find entries like in the example below.

2021-10-15T19:40:29.543+02:00	Fri, 15 Oct 2021 17:40:29 GMT request:interceptor request={"version":"1.0","session":{"new":true,"sessionId":"amzn1.echo-api.sessio...

Within your CloudWatch log group, you will find a "View in Logs Insight" button at the top of the screen, this will take you to the CloudWatch Log Insights query page.

CloudWatch Logs Insights allows you to interactively search and analyze your log data in CloudWatch Logs.

To get a list of all APL versions installed on your customers' devices use this query.

fields @message
| filter @message like /request:interceptor request=/
| filter session.new = 1
| filter ispresent(context.System.device.supportedInterfaces.Alexa.Presentation.APL.runtime.maxVersion)
| stats count(*) as count by context.System.device.supportedInterfaces.Alexa.Presentation.APL.runtime.maxVersion
| sort count desc

CloudWatch stores all the information you log within your skill backend in the "@message" field. To ensure that we only consider certain log entries in our query, we first filter the entries according to the following criteria.

| filter @message like /request:interceptor request=/

All log entries containing request:interceptor request=

| filter session.new = 1

All log entries in which a new skill session was started

| filter ispresent(context.System.device.supportedInterfaces.Alexa.Presentation.APL.runtime.maxVersion)

CloudWatch Insights automatically parses our JSON, for this reason we can use any keys contained in our Lambda Request JSON.

And of course we are only interested in requests that actually support APL.

Now we use the aggregate command "stats" to count our logfile entries, but we want to group the result by our maxVersion field

At the end, we sort the result in descending order according to the most frequently used APL version.

Once you run the query, you should see something like this

We can of course build a query to retrieve the viewport sizes our customers use.

fields @message
| filter @message like /request:interceptor request=/
| filter session.new = 1
| filter ispresent(context.System.device.supportedInterfaces.Alexa.Presentation.APL.runtime.maxVersion)
| filter ispresent(context.Viewport.mode)
| stats count(*) as count by context.Viewport.pixelWidth, context.Viewport.pixelHeight, context.Viewport.mode, context.Viewport.dpi, context.Viewport.shape
| sort count desc

Not all devices seem to send the viewport property in the request, for this reason we filter our log entries additionally with the following condition.

| filter ispresent(context.Viewport.mode)

After the query is executed we get a result again.

That's it. Have fun analyzing and optimizing your APL documents! If you liked the post, leave a comment and ❤️.