If you’re an ISV partner who’s developing managed packages for AppExchange, the #1 enterprise app marketplace, we have very exciting news to share! Our new, powerful custom interactions feature is generally available as part of our Spring ’24 release.
Since its launch in Spring ’20, developers have been able to use AppExchange App Analytics usage data to determine how your customers are using components within your managed packages. For example, usage data helps you understand when:
- Users created a record in a managed custom object, and how many records exist
- A managed Apex class was invoked
- A user interacted with a Lightning component
This usage data is valuable because it helps you understand your customers and users. For example, it can help you prioritize your roadmap decisions or identify customers at early risk of attrition.
We heard from partners that, with very large volumes of App Analytics data, it’s sometimes difficult to understand which events are relevant to the business decisions they need to make. After all, App Analytics processes billions of events per day! We hear you, and we appreciate your feedback: if a managed package has heavy usage, it’s not easy to sift through this data.
These conversations with our partners inspired us to create custom interactions, a truly game-changing feature for App Analytics. For the first time ever, we’re allowing ISV partners to fully instrument their managed packages in Apex to log the user interactions that they care about. The best part is that you use custom interactions today!
Set up labels for custom interactions
Trust is our #1 value at Salesforce. As we were designing custom interactions, we wanted to give you the ability to log a user interaction that you care about at the right point in time, while ensuring that customer data is always kept safe. We did so by creating a new logCustomInteraction Apex method that you can now use to instrument your code, with three available signatures:
This Apex method is available under the new IsvPartners.AppAnalytics namespace and class.
interactionLabel is always required, and this is where the magic happens to help you understand what type of interaction is taking place. It must be an Apex enum value that is defined as part of your managed package. It can’t be generated on the fly or belong to a different package namespace.
Optionally, you can also use Apex IDs or UUIDs to group interactions that belong together. These are always hashed and tokenized, ensuring that customer data is always protected.
Here’s an example of how you define an enum in Apex to use with custom interactions:
In this example, we defined five labels within the MyCustomInteractions enum that we can use anywhere in packaged Apex code to call logCustomInteraction. We use them to understand when a user has created an invoice, called the AWS API to post the invoice, and interacted with a specific button within a Lightning web component to increase/decrease the quantity of products being sold.
This is just an example. In your capable hands, custom interactions can be quite powerful. You have a much greater degree of control over when a particular interaction gets logged — and at what level of granularity — so you can focus on those interactions that truly matter to you.
To get you started, here are some example use cases of how to use custom interaction labels:
- Understand which high-level features are being used
- Understand how users flow through a particular user journey
- Understand which specific Lightning web components are being interacted with
- Understand which business processes are taking place, grouping together similar transactions
- Understand whether older custom objects are no longer being used and can be safely removed
- Track an Apex process across synchronous and asynchronous transactions
- Train an AI model
To top it off, there’s no specific limit on the number of labels that you can use within your package. Take time to think through which interactions are most valuable to you, define the corresponding labels as enum values, and once you’re ready, start instrumenting your managed package.
Instrument Apex code with custom interactions
Once you’ve created your labels, it’s time to add corresponding calls to the logCustomInteraction method throughout your Apex code. You are in the world of Apex, so don’t forget to take full advantage of programmatic logic as required to log a custom interaction exactly where it makes sense.
There’s one particular limitation that you should bear in mind. We will only log 50 interactions as part of a single user request. If you do log more than 50 interactions, this will not generate any customer-facing errors, and therefore it won’t break your customers. However, you will not see any usage data coming in via App Analytics related to those additional interactions that exceed the limit. In practice, this means that you should avoid calling logCustomInteraction from within a loop.
When a user interacts with your managed package and logCustomInteraction gets called, you will see that data come through in App Analytics as part of your package usage log. There’s a caveat, though. Package usage logs are made available to you only if your managed package is running in a sandbox, trial, or production org.
This would otherwise make it difficult for you to debug your custom interactions as you instrument your code. To make this process simpler, we provide messages in your debug log as you develop. By setting your Apex debug log level to FINE, you can find events in your debug logs called APP_ANALYTICS_FINE, APP_ANALYTICS_WARN, or APP_ANALYTICS_ERROR to confirm that your custom interactions are being logged. Here’s an example of a successful call:
Once you’ve instrumented code in your managed package, upload a new version and ensure that your customers are using it. You can do so by taking advantage of push upgrades for managed packages. As users interact with the latest version of your package, you will start receiving new custom interactions events in your App Analytics logs.
Analyze usage data from custom interactions
Analyze custom interactions with your packaged components by downloading your package usage log; look for a log_record_type of CustomInteraction and a custom_entity_type of CustomInteractionLabel. The custom_entity column contains the custom interaction label, such as MyCustomInteractions.CREATED_RECORD_WITH_RECORD_TYPE_RECEIPT above, that you created as an Apex enum.
Here’s a JSON example of how a custom interaction event would show up in your log:
If you’re already using App Analytics today, you should already be familiar with the above data structure. However, note the following information specific to custom interactions:
log_record_typeisCustomInteractioncustom_entity_typeisCustomInteractionLabelcustom_entityisMyCustomInteractions.CREATED_RECORD_WITH_RECORD_TYPE_RECEIPT, the Apex enum value that we use to label our interactioninteraction_id_tokenis the hashed and tokenized version of the optional ID provided when we log the interaction
You can use additional data points, such as class_name, method_name, and line_number, to know exactly where in Apex the custom interaction was logged.
When all goes to plan, you will receive custom interaction data in your log. However, sometimes we are unable to successfully log a custom interaction. In this case, you’ll see different error codes coming up in custom_entity associated with a custom_entity_type of CustomInteractionFailure. For instance, the OVER_CALL_LIMIT error code is used when you try to log over 50 custom interactions in a single user request. You can learn about other error codes and what they mean in our docs.
Finally, custom interaction data is aggregated on a monthly basis as part of your package usage summary. Here you can also see the new custom_entity_type values, such as CustomInteractionLabel and CustomInteractionFailure, as well as the relevant values for custom_entity.
Conclusion
For the first time ever, you can instrument your Apex code to have access to those usage metrics that you really care about. And we made it very easy for you to test and debug your implementation before including it in your managed package.
We truly believe that custom interactions are going to be game-changing for our ISV partners and, in your capable hands, it can help you add a ton of value to your customers.
We are excited to learn more about how you will use custom interactions, so feel free to drop us a line! If you are an ISV partner, please share your feedback in the Partner Community.
That’s it! Now go ahead and instrument your managed package, and get ready for powerful insights!
Resources
- Second Generation Managed Packaging Guide: Considerations for Custom Interactions
- Second Generation Managed Packaging Guide: Custom Interactions
About the authors
Stephen Carter is a father of six kids and Lead Engineer with more than four years of experience at Salesforce. He has contributed primarily to the development of AppExchange App Analytics, including custom interactions, but he has recently joined the Salesforce Code Analyzer team.
John Belo is Director, Product Management for Platform Developer Experience focusing on Salesforce Code Analyzer, AppExchange App Analytics, DevOps Center Testing & Quality, and Package Migrations. He’s been with Salesforce for over eight years, always working closely with AppExchange partners.