Custom Event Properties

You can attach custom properties to any event captured by the Pendo Web SDK by adding an onEventCaptured callback to the events object passed to pendo.initialize.

The callback runs for every captured event — Auto Events (click, focus, change, submit), load, and track events — so you can decide per event whether and what to add.

warning

It is best practice to wrap the body of your onEventCaptured handler in proper error handling (for example, a try/catch block). The callback runs synchronously in the event capture path, and an uncaught exception thrown from your handler can cause interruptions for event collection.

API

onEventCaptured should be a function that accepts a single argument. The argument is an object with the following properties:

event

The underlying event being captured. Use event.type to identify which event type fired (click, focus, change, submit, load, track, etc.) and branch on it to add properties only when relevant.

target

The original DOM element associated with the captured event, when applicable. Some event types (such as load and track) may not have a meaningful target, so guard with a truthiness check before using it.

addEventProperty(name, value)

Adds a property to the current event. name is a string; value can be any serializable JSON value (string, number, boolean, plain object, array).

getEventProperties()

Returns the current set of event properties on this event, including any properties added by the Pendo Agent via event property definitions configured for the web app.

Example

pendo.initialize({
    visitor: { id: 'exampleUser1' },
    account: { id: 'exampleAcct1' },
    events: {
        onEventCaptured: function (eventInfo) {
            // inspect the event type and target to decide what to add
            if (eventInfo.event.type === 'click' && eventInfo.target) {
                eventInfo.addEventProperty(
                    'data-test-id',
                    eventInfo.target.getAttribute('data-test-id')
                );
            }

            // you might pull all your properties at once from app state
            var currentEventProperties = getCurrentEventProperties();
            for (var i in currentEventProperties) {
                eventInfo.addEventProperty(i, currentEventProperties[i]);
            }

            // or add them individually
            eventInfo.addEventProperty('foo', 'some string');
            eventInfo.addEventProperty('bar', true);
            eventInfo.addEventProperty('baz', 123);
            eventInfo.addEventProperty('quux', {
                stuff: 'that',
                we: 'want to save'
            });

            // inspect properties already on the current event
            eventInfo.getEventProperties();
        }
    }
});