How to Create Telemetry Dashboards for Adobe Express Add-ons

Adobe Developer Champion Michael Scherotter has created an open-source solution that collects user analytics for Adobe Express add-ons. Here he explains how you install and use it.

This article is aimed at Adobe Express add-on developers who are interested in gaining deeper insights into how people are using their add-ons. It’s also helpful to new developers who want to understand how to take advantage of data visualization tools like Microsoft Power BI and cloud services like Microsoft Azure.

With its intuitive design and user-friendly interface, even non-designers can create professional-quality graphics, web pages, and videos quickly and easily with Adobe Express. Developers building add-ons for this platform need to understand their users and their behavior, monitor performance, and troubleshoot issues.

Throughout my 30-year career, I have been crafting creative apps and tools including CAD and mind-mapping software, 360-degree sketching apps, 3D-generated virtual art galleries, and most recently Adobe Express add-ons. I jumped into the latter area because the developer platform is easy to use, well-supported by Adobe and their developer community, and continually improving.

In this article, I’ll walk you through an open-source solution that I developed to capture and visualize detailed user analytics for Adobe Express add-ons.

Why telemetry matters

If developers know more details about who their users are, how those users experience their add-ons and where they are having problems, then they can build better add-ons. For example, through the telemetry, a developer may see that certain errors are only occurring when using a particular browser in a specific language.

I found that I could generalize the way that I collected the telemetry data from my add-ons — Galeryst, Creative Coding, and Perspective Grids — and build a solution that could work for any Adobe Express add-on developer.

Developers are free to use third-party analytics tools like Google Analytics or Adobe Analytics, but I wanted to create something that gives developers full control of the data processing and presentation of the telemetry data.

Collecting and visualizing user analytics for Adobe Express add-ons

So, as an Adobe Developer Champion eager to help other developers, I created a public, open-source project called express-analytics that does just that.

Here’s what it includes:

• The source code for the express-addon-analytics NPM package that add-on developers can add to their own add-on project
• The source code for a Microsoft Azure function that serves as an endpoint for testing and deployment
• A Microsoft Power BI dashboard template that shows how to use the data coming from the Azure function
• A sample add-on project for Adobe Express that uses the express-addon-analytics package and demonstrates the API usage.

The end result of using these components together is the business intelligence that a software developer can gain from a telemetry dashboard. This dashboard has four pages showing user data, session data, custom event data, and errors. Once I added the analytics packages to my add-ons, I better understood where users were located and how they used my add-ons.

Based on that intelligence, I then added more event and error tracking to my add-ons. Now I also know when users encounter errors, what may have caused them, and the stack-trace of when the errors happened. Because I have built multiple add-ons, I can see trends in installs and usage across add-ons and even understand where some people are using multiple add-ons that I published.

The solution is modular, which means you can swap out any of the components:

• You can modify or swap out the adobe-addon-analytics to fine-tune the data collection.
• You can use a different hosting provider than Microsoft Azure.
• You can use a different business intelligence and dashboard platform than Microsoft Power BI.

Below you can see an example of the dashboard after five days of collecting data across two add-ons available to the public (Creative Coding and Galeryst) and three add-ons still in development (Perspective Grids, Resume Builder, and Test Express App). With the slicer at the top left, I can include or exclude testing users.

Adobe Express Add-on Analytics users page.

The dashboard shows data from all add-ons that you monitor with the express-addon-analytics package so you can see data from all, some, or just one of the add-ons that you build.

In the dashboard you can add specific details of users that you know to include as “Testing users” so any of their telemetry will not skew the analytics.

Step-by-step guide to implementation

Here’s how to install and use the Adobe Express add-on analytics package:

Preparation

1. Ensure you have a Microsoft Azure account.
2. Install Microsoft Visual Studio Code.
3. Install the Visual Studio Code Azurite extension.
4. Download the Ngrok API gateway for local testing.
5. Download and install the Azure Storage Explorer.
6. Download and install Microsoft Power BI (Windows only).

A. Local machine function deployment for testing

1. Clone the express analytics repo https://github.com/mscherotter/express-analytics.git.
2. Start Azurite to act as a storage emulator for local development, enabling the Azure Blob service.
3. Add a .env file to the azure-function directory that has the line
   AZURE_STORAGE_CONNECTION=UseDevelopmentStorage=true
   - Start debugging (in VS Code, attach to Node Functions).
4. In the debugging output window, you will see the function listed like this:
   expressAnalytics: [GET,POST] http://localhost:7071/api/expressAnalytics.
5. On a command line, start Ngrok with the command ngrok http http://localhost:7071 — host-header=localhost, making sure that the port numbers match (7071 in this case).
6. Once Ngrok starts up, you will see a forwarding line. Copy the URL up to the -> characters.

B. Create the Microsoft Azure function

1. Clone the express-analytics repo https://github.com/mscherotter/express-analytics.git.
2. Configure a Microsoft Azure Storage account on Azure.
3. Note the connection string for the storage account.
4. Deploy the express-addon-analytics function to Azure.
5. Once deployed, add the AZURE_STORAGE_CONNECTION environment variable to the Function App/Settings/Environment variables.
6. On the Function App/Overview page, click on the expressAnalytics link and then copy and note the link from the Get function URL button.
7. On the Function App/Functions/App keys page, copy and note the value from the default key.

C. Adding analytics to an add-on

1. Create an Adobe Express add-on project in JavaScript or TypeScript. If you haven’t done this yet, take a look at Adobe’s guides on building Adobe Express add-ons.
2. Create a new add-on project in the Adobe Express Your add-ons page.
3. On the add-on Settings page, note the Add-on URL — it should be something like https://abcdefg.wxp.adobe-addons.com/.
4. Follow the steps here to add the express-addon-analytics package to your Adobe express add-on project.

• For the endpoint, the URL should be the function URL from step B6 above and the key from step B7 like this:
  https://<your function app name>.azurewebsites.net/api/expressAnalytics?key=<your function key>.
• For the devEnpoint, the URL should be the Ngrok URL from step A6 appended with /api/expressAnalytics?key=test:
  https://<unique ngrok url>/api/expressAnalytics?key=_test.
• You can track the user details with trackUserAsync(), track custom events with trackEventAsync(), track errors with trackErrorAsync(), and track session duration with a pulse that is sent every 15 seconds starting with the first creation of the ExpressAnalytics object.

D. Configuring CORS

For local machine testing, add a local.settings.json file to the azure-function directory. You may need to restart debugging for this to apply.

{
“IsEncrypted”: false,
“Values”: {
“AzureWebJobsStorage”: “UseDevelopmentStorage=true”,
“FUNCTIONS_WORKER_RUNTIME”: “node”,
},
“Host”:{
“LocalHostPort”: 7071,
“CORS”: “*”
}
}

For cloud deployment in the Azure dashboard Function App/API/CORS page, add the add-on URL from step C3 above.

Testing

1. Start debugging your add-on project.
2. Keep the app running for at least 30 seconds.
3. Using the Azure Storage Explorer, validate that rows are showing up in the storage account tables expressAnalyticsUsers and expressAnalyticsEvents.

E. Creating a dashboard

Important: Power BI Desktop will only run on Windows and will NOT work with the data from the Azurite local storage emulator.

1. Download the Microsoft Power BI template Adobe Express Add-on Telemetry Dashboard.pbit.
2. Start Power BI with the template.
3. Attach the tables Users and Events to Azure Storage Data tables expressAnalyticsUsers and expressAnalyticsEvents.
4. Update the Known users table in the dashboard to include the user Ids for your development and testing team.
5. Refresh your dashboard and in a few seconds, you can see it fill in with your telemetry data.
6. Customize and adapt the dashboard to your needs.

Open source contributions

This solution is entirely open source, so if you think you can improve it, please make a pull request, open an issue, or reach out if you have feedback or want hands-on help deploying it for your organization. And if you think this is a useful open source project for Adobe Express, please consider contributing code, fixing bugs, and improving it.

-Michael S. Scherotter, Founder Galeryst.com

To stay up to date with the latest developer news, subscribe to the Creative Cloud Developer Newsletter.