Adding Custom Usage Analytics Context and Events

Oftentimes, you will want to record custom usage analytics events, which you can use to better navigate Coveo Usage Analytics (Coveo UA) on the Coveo Cloud platform (see Coveo Usage Analytics).

There are several ways in which you can add custom events in Coveo for Salesforce.

Send Custom Context Without Resorting to Custom Code

Coveo Lightning components allow you to send custom context information without having to write custom code.


Send Custom Context With Custom Code

It is also possible to implement your own custom code to send custom analytics events.

When implementing your own code, you should bind yourself to events (see Events).

To understand the recommended syntax for sending custom analytics through code, see:

Code written in a script tag of a Coveo Lightning component will not be executed. You should instead create a wrapper for that component (see Adding JavaScript to the Coveo for Salesforce Lightning Components With Custom Code - Deprecated).

Refer to the Usage Analytics API documentation for further customization (see Coveo Usage Analytics API).

Send Custom Events with the Coveo JavaScript Search Framework

With a custom component that uses the Coveo JavaScript Search Framework, you may need to send your own usage analytics events, or to modify the standard ones (see Sending Your Own Search, Click, or Custom Events and Sending Custom Metadata with Search, Click, or Custom Events).

When doing so, you are encouraged to follow consult the following documentation to ease your implementation:

When sending custom events, you need to add a custom dimension in Coveo Cloud to be able to use those events in Usage Analytics. Ensure that you have enough custom dimensions left before implementing your code (see Coveo for Salesforce Edition Comparison).

For more information on Custom Dimensions, see Usage Analytics Dimensions.

For a concrete example on how to send custom analytics events in a Coveo for Salesforce context, see Adding Custom Usage Analytics Events in a Coveo Case Creation Component.

Sharing Dimensions Across Events

To add Dimensions common to any event recorded, use the changeAnalyticsCustomData event of the Analytics component.

The example below adds dimensions to the metaDataAsString object similar to username as the key and caseContext.username as the value. You need to declare these Dimensions within the Coveo Cloud platform (see Adding and Managing Dimensions on Custom Metadata).

$('#CoveoBoxboxid').on('changeAnalyticsCustomData', function(e, args) {
    args.metaObject.username = caseContext.username;
    args.metaObject.caseid =;
    args.metaObject.casesubject = caseContext.subject.toLowerCase();
    args.metaObject.casenumber = caseContext.number;
    args.metaObject.caselanguage = caseContext.lang;
    args.metaObject.casestatus = caseContext.status;

Adding Parent Record Fields in SearchContextHandler

Coveo for Salesforce 3.36 (July 2018)

Parent records, up to five levels, can now be attached to the context when using a SearchContextHandler. In the Record Fields, write the desired parent record field using the following syntax:

  • Case_Account.Id

  • Case_Account.Owner.Name

  • Case_Account.Owner.Phone

  • Case_Contact.Account.Owner.Name

  • Case_CustomObject__c

  • Case_CustomObject__r.CustomField__c

  • Case_CustomObject__r.OtherCustomObject__c

  • Case_CustomObject__r.OtherCustomObject__r.Name

Separate each parent record field by a comma.

Recommended Articles