Custom events (tags)

[s-jakob]

To mark special events in the recording it would be good to have the ability to add custom events. I think the type for this should be "tags". Similar to Google gtag events:
https://developers.google.com/gtagjs/reference/event

In the data field there should be fields like:

• name (e.q. 'add_to_card', 'checkout') -> string
• params (e.q. products added) -> JS Object

To add an tag an function can be added:

rrwebTag('add_to_card', {
    product: '12123',
    qty: 1,
    price: 20
})

This tags can then be displayed during the playback as custom colored marker. The color can be defined when initializing the player as an JS Object:

const events = YOUR_EVENTS;

const replayer = new rrweb.Replayer(events, {
    tags: {
        'add_to_card': '#453222',
        'checkout': '#885942'
    }
});
replayer.play();

[s-jakob]

Another option could be to add all possible custom tags when initializing the recorder and set an ID:

rrwebRecord({
     emit(event) {
         addEvent(event);
     },
    tags: {
        'add_to_card': 1,
        'checkout': 2
    }
})

This IDs then get added to an offset (e.q. 1000) and set as type in the event when a tag is added. If the custom tag is not in the list the tags is ignored. The rrweb event object would then looks like this for the event 'add_to_card':

{
    type: 1001,
    data: {
        product: '12123',
        qty: 1,
        price: 20
    }
}

This would make the DB search easier when looking for recordings with this tag.

[Yuyz0112]

Thanks for the proposal!

The custom event is one of the most frequently asked features. And I want to make sure what's the scene that an event must be stored with other rrweb events.

From your proposal, I found the replayer awareness is one of the good points that we should integrate this feature into rrweb. It would be nice if you can share more usages about the custom event.

Thanks a lot.

[s-jakob]

I need the tags to filter session recordings, which had specific events. Like in my example 'User added product to card' or 'User made a purchase'.

[Yuyz0112]

Ok, and you will try to query events/tags and find them sessions to make the filter right?

[Yuyz0112]

@s-jakob

Does something like this look good to you?

The data structure:

enum EventType {
  DomContentLoaded,
  Load,
  FullSnapshot,
  IncrementalSnapshot,
  Meta,
+ Custom,
}

+type customEvent<T = unknown> = {
+  type: EventType.Custom;
+  data: {
+    tag: string;
+    payload: T;
+  };
+};

type event =
  | domContentLoadedEvent
  | loadedEvent
  | fullSnapshotEvent
  | incrementalSnapshotEvent
  | metaEvent
+ | customEvent;

and the API:

function addEvent<T>(tag: string, payload: T) {
  emit({
    type: EventType.Custom,
    data: {
      tag,
      payload
    }
  })
}

[s-jakob]

Hi @Yuyz0112 this looks perfect. I will do the filter on the server side. So i think there is no need für any other changes on the client side.
Thank you very much. This helps a lot.

[marcospassos]

@Yuyz0112 I believe the pa tag should be part of the payload, as not every custom event requires it.

[Yuyz0112]

@marcospassos
@s-jakob shows an interesting usage of show tags in the replayer like this:

const replayer = new rrweb.Replayer(events, {
    tags: {
        'add_to_card': '#453222',
        'checkout': '#885942'
    }
});

So I think it is a good idea to add the first-class support for the tag system than a general key in the payload.

[Yuyz0112]

Has added the client-side addCustomEvent function, will update the docs later.

[heathdutton]

Looks like this is a live feature, but undocumented. Is it safe to use? I ask because of the reversions :)

[Yuyz0112]

@heathdutton Yep, it's stable now.

[rifaideen]

@Yuyz0112 - Is this added?

Displaying tag colors on the player timeline like the below:

const replayer = new rrweb.Replayer(events, {
    tags: {
        'add_to_card': '#453222',
        'checkout': '#885942'
    }
});

I'm trying to test this functionality in rrweb-player adding tags options doesn't reflect any changes in the player timeline.

import Player from 'rrweb-player';

const player = new Player({
        target: document.getElementById('preview'),
        data: {
          events: recordings,
          autoPlay: false,
        },
        tags: {
          foo: '#453222',
        },
      });

[Yuyz0112]

@rifaideen nope, not implmented yet.

[rifaideen]

@Yuyz0112 - ah ok. It would be great if you have any examples on achieving the similar result.