Get App Smart: How to Use AppExchange App Analytics

Special thanks to my co-authors Vivek M. Chawla and Peter Martin.

In Summer ’19, Salesforce released an important new tool for Salesforce partners: AppExchange App Analytics. Partners now have access to detailed usage data about how subscribers interact with their AppExchange solutions.

Getting this type of data and related analytics has a lot of benefits for partners. It can help identify attrition risks, drive feature development decisions, and even improve user experience. The sky’s the limit once you’ve got a window into how subscribers actually use your app.

We’re going to get technical in this blog! If you want to learn more about the business case for App Analytics, make sure to check out the AppExchange Partner Intelligence Webinar Replay.

Learning By Example

In this blog, we’ll walk you through the steps to implement App Analytics by using a hypothetical app, Codey’s Code Corral.

Codey’s Code Corral connects coders to current opportunities for projects and mentorship. Six months after listing on the AppExchange, Codey’s app is a success with hundreds of installs. He’s ready to invest in additional features, but he’s not sure which ones to prioritize.

App Analytics can help because Codey’s app meets all the pre-requisite requirements:

• Distributed as a managed package
• Passed the Security Review
• Uses Custom Objects
• Associated with a License Management App (LMA)

Make sure your app also meets these requirements before getting started!

Step One: Package Activation and Permission Set Creation

First, Codey submits a case to get App Analytics activated for his package.

1. Follow the instructions on ISVForce Guide for App Analytics
2. Important: Only packages that have been through Security Review and registered to an LMA will be accepted
3. An email notification will be sent once App Analytics is activated and you’re ready to start querying

In order to create the “queries”, Codey also needs to create a permission set in his LMO (the org where his LMA is installed).

1. In setup, create a Permission Set called “App Analytics Admin”
2. Assign full-control CRUD access to the AppAnalyticsQueryRequest object
3. Assign the “App Analytics Admin” permission set to anyone who needs it

Step Two: Decide Which Insights You Want

Now that Codey has activated App Analytics for his Code Corral app, he’s ready to fetch and analyze data. Before he can get analytics, though, Codey needs to figure out what he wants to learn.

In this case, Codey wants to get details about how all of his subscribers used the Code Corral app last week.

Let’s take these requirements and translate them into what’s possible with App Analytics.

Get details…

Codey wants all details, and not just a summary, so he’ll need to target the CustomObjectUsageLog type

About all subscribers…

Codey wants all subscribers, so he’ll need to use a “wildcard” for the OrganizationIds field

Using the Codey’s Code Corral package…

Codey only wants information about his Code Corral app, so he’ll need to specify a single PackageIds.

Over the past week…

Codey can get up to a week’s worth of data using StartTime and EndTime

Step Three: Build and Submit Your Query

The phrase “build and submit a query” can be a bit confusing at first. What we actually do is insert a record of the AppAnalyticsQueryRequest object into Codey’s LMO.

Once that record is created, the App Analytics engine works behind the scenes to fetch the appropriate data from the App Analytics data lake.

Once the data is ready, the results are saved to an Amazon S3 bucket and the “query” record gets updated with a download link.

For now, the only way to create an AppAnalyticsQueryRequest record is by using the REST or SOAP API. Remember the decisions Codey made in Step Two? Here’s how they translate into the AppAnalyticsQueryRequest fields Codey needs.

Codey is going to use the Salesforce CLI to insert the record. Here’s what the command Codey used looks like:

~codey$ sfdx force:data:record:create -s AppAnalyticsQueryRequest -v “StartTime=2019-06-08T12:00:00 EndTime=2019-06-12T12:00:00 DataType=PackageUsageSummary PackageIds=0331U000000EHq2”-u CodeysPBO

After inserting the AppAnalyticsQueryRequest the CLI gives back the ID of the record that was just created. Copy that ID because you’ll need it in the next step!

In our case, the output looks like this:

Step Four: Monitor the Status of Your Query

Codey can find out when his App Analytics data is ready for download by reading the same record he created in the previous step. To do this, he’s going to use the Salesforce CLI again.

~codey$ sfdx force:data:soql:query -q “Select Id, DownloadUrl, RequestState, ErrorMessage from AppAnalyticsQueryRequest where ID=‘0XI1U000000006EWAQ’” -u CodeysPBO

Codey is going to look for a value to appear in the DownloadUrl field.

The DownloadUrl field is blank while the request is being processed. You can use the RequestState field to see what the current status is. If the request fails, then you will get an ErrorMessage.

Once the request is ready, theDownloadURL is going to look like this.

Now Codey can take that DownloadUrl to the next step.

Step Five: Retrieve Your App Analytics Log File

The DownloadUrl is unique to Codey’s request and provides a secure way for him to download the Custom Object Usage Log that resulted from his App Analytics query.

It’s important to note that Salesforce does not retain these log files. Each DownloadUrl expires after 15 minutes, so Codey will need to make sure he uses it right away.

Once downloaded, the log file will look something like this if opened in a spreadsheet tool.

As you can see, there is a lot of information in a Custom Object Usage Log file. That’s great, but begs the question, “what do I actually DO with all of this”?

To answer that question, Codey is going to need a data visualization tool. We cover that topic in the next installment of this series.

Conclusion & Resources

We covered a whole lot with our friend Codey on how to use App Analytics. These steps and technical insights are a resource for you to follow as you determine if your app meets the requirements for app analytics and so you can also create your own queries.

Have questions? Go to our Partner Intelligence — TE Experts group on the Partner Community.