User Telemetry abstraction for UI

[anandtiwary]

Ref: #937

Requirement

• Provide integration with various user telemetry third-party tools. Example: GTM and GA, FullStory, LogRocket, etc
• Customers should be able to configure a particular tool of their choice.
• Should be driven by config
• Should support multiple telemetry tools at run time

Proposed Approach

• Create an abstraction layer in UI with the following methods:

  export abstract class UserTelemetry {
   
      public construction(private readonly config: UserTelemetryConfig){}
      
      public abstract init(): void;
      
      public abstract identify(userTraits: IUserTraits): void;
      
      public abstract trackCustomEvent(name: string, eventData: Dictionary<string> | string | number | Date): void;
      
      public abstract trackPage(): void; // Reads current url
      }
  

• User telemetry service would depend on this abstract class. Therefore, this service would call appropriate abstract class methods, then relay to the corresponding telemetry tool.
• Our customers would only have to register the third-party telemetry tool of their choice. The above approach would abstract the rest.

Open question:
How would our customers provide this config to UI without forking the repository?

@aaron-steinfeld @JBAhire @kotharironak @itssharmasandeep @jyothishjose6190 @subintp

Share your thoughts and suggestions on the approach and the open question :)

[aaron-steinfeld]

A few various thoughts from my perspective:

• our default position for plugins like this should be interface over abstract class, unless there's a specific argument to the contrary
• We should support any number of user telemetry instances concurrently. I may want to use GTM and full story.
• we can and should accept contributions for any number of telemetry providers - having multiple checked in is fine as long as which ones are actually used would be based on config
• the config for each plugin may be different depending on requirements - urls etc.
• I'd treat it as a separate question as to how to get that config in at deployment time - I think this is your open question. It's required for this to be fully useful, but has come up in enough independent places that it's worth thinking about holistically. currently the best technical option here is to move it into a gql api but that's a bad option. it forces a startup blocking fetch for many cases (likely this one), and can lead to a bad separation of concerns in some cases.

[anandtiwary]

For the last point, I have created a separate discussion thread. Please use #1065

[anandtiwary]

• For 1, I don't see any strong reason to use abstract class at the moment. It would be more useful if we can have any shared code, but so far I see none. So I am fine with using interface over abstract.

• For 2, I totally agree on this one. That's part of my initial proposal too.

• For 3, Yeah. So we need to provide an easy way to a support new telemetry providers. I would think more over this

• For 4, the init config is usually the same. We just need an "orgId" or "appId". The url and the loading script itself would come from the telemetry provider and we would just need to reference that in our implementation.

For user identification data and custom event data, I would use our Dictionary<unknown> so that user can provide any type of data. This is how Telemetry tools support custom user data anyway.

[anandtiwary]

Config:

export interface UserTelemetryConfig {
  type: UserTelemetryType,
  orgId: string,
  allowPageTracking: boolean,
  allowEventTracking: boolean;
  allowErrorTracking: boolean;
  enabled: boolean
}

Directive:

**htTrack**
When `allowEventTracking` is enabled, this directive would request 
the telemetry service to send a custom event to all configured telemetry tools.

Inputs:
- name
- event data
 

Service:

UserTelemetryService
 - Maintains a list of currently configured telemetry tools
 - Depends on account service and automatically calls `init` with identification information like email, 
    customer name etc.
 - If `allowPageTracking` is enabled, this service would listen to router 'end' events 
    and would trigger a customer event automatically with relevant data. Example, page title can be used as custom event name.
 - On notification, from `htTrack`, this service can trigger the custom event on all configured tools
 - if `allowErrorTracking` is enabled, then this service can listen to any console errors and emit an event accordingly
 - **Bonus**: This service can add events to a queue and another web worker 
    can read from it and send the event to each individual telemetry tool.

Module: UserTelemetryModule

 Registers the tools and configs with the service.
 
 UserTelemetryModule.withConfigs([
   {config - 1},
   {config - 2}
])

With this approach, page views and errors will be automatically tracked (if enabled). For custom events, we would have to identify places which are interesting and accordingly we will have to use htTrack there. For example, we can use it on a logout button.

[aaron-steinfeld]

export interface UserTelemetryConfig {
type: UserTelemetryType,
orgId: string,
allowPageTracking: boolean,
allowEventTracking: boolean;
allowErrorTracking: boolean;
enabled: boolean
}

• What's the type on UserTelemetryType ? is this an enum? That would require a library code change to add a new type. A looser coupling would allow using this telemetry service with a new telemetry provider without modifying its source.
• Perhaps enableXTracking instead of allowXTracking? It's more config-y.
• What case would I have for providing a config but disabling it?
• It still feels more correct to me to separate the args for the telemetry service (the type, the allow/enaable stuff), and the args for the specific provider (in this case, org id). Certain providers could require some different information (or just use different names for it), and the library itself doesn't need to read it.

All together, my proposed tweaks:

export interface UserTelemetryConfig<T> {
  telemetryProvideKey: string,
  telemetryProviderConfig: T,
  enablePageTracking: boolean,
  enableEventTracking: boolean;
  enableErrorTracking: boolean;
}

// Setup
UserTelemetryModule
  .definingProviders([{ key: 'my-provider', provider: MyProviderService}]) // Registered a custom telemetry provider
  .usingProviders([...]) // configures a custom or out of the box provider

htTrack
When allowEventTracking is enabled, this directive would request
the telemetry service to send a custom event to all configured telemetry tools.

Inputs:

• name
• event data

Is this proposal like a *htTrack="name: someEventName; data: someData" ? I think the part we have to be very careful of is when it should evaluate. For example, if we ngIf something and it appears and disappears, do we want it to fire a new message if the args are the same? and what if we navigate away then back again? I think there are use cases either way, but certainly could lead to ambiguity. Also, what if I want it to track on an action other than load? For example, how would you propose sending an event on a button click? That feels like an MVP use case to me, so we should make sure we have a straightforward story there.

UserTelemetryService

• Maintains a list of currently configured telemetry tools
• Depends on account service and automatically calls init with identification information like email,
  customer name etc.
• If allowPageTracking is enabled, this service would listen to router 'end' events
  and would trigger a customer event automatically with relevant data. Example, page title can be used as custom event name.
• On notification, from htTrack, this service can trigger the custom event on all configured tools
• if allowErrorTracking is enabled, then this service can listen to any console errors and emit an event accordingly
• Bonus: This service can add events to a queue and another web worker
  can read from it and send the event to each individual telemetry tool.

I'd reverse that init relationship. Call in with the init information, once available - the reason being that we want the telemetry service available at a library from my understanding, but the init information will be coming from the application. I think the same argument could be made for the router, too - but given that we're within angular, I wouldn't hold on that point too much.

[anandtiwary]

I should have broken it down into separate posts. :)

• I am fine with the telemetry config related suggestions. telemetryProviderConfig can probably come later.
• htTrack would only emit when user clicks on the host element. We are only trying to record useful events and they would be defined ahead of time by the product team.
• May be we can rename this directive to htTrackClick to convey this better. But I would honestly prefer to keep it generic so that later we can capture other event types through config options (like right click or double click).
• For User exp and UI performance, we should probably record everything including element load. For these type of use cases, there are tools like full story which does auto track on its own.

[aaron-steinfeld]

htTrack would only emit when user clicks on the host element. We are only trying to record useful events and they would be defined ahead of time by the product team.
May be we can rename this directive to htTrackClick to convey this better. But I would honestly prefer to keep it generic so that later we can capture other event types through config options (like right click or double click).

Could you post an example usage? would it be like our event blocker (but a directive) ? I feel like there's a reason we made that a component over directive, but can't recall.

I think a concern here is if we're working with native events, A. are we limited for application-level things like an onchange output? I guess they could work the service directly? B. I think some of our components use things like event blocker, stop propagation etc. So those wouldn't be received, right?

[anandtiwary]

We would likely have to maintain or depend on the init script of each supported telemetry platform. This would be small js snippet or an npm module depending upon availability.

[aaron-steinfeld]

I think here, we'd have to hopefully strive to find a module version of each. Yes, we could always do the global snippet if no other options, but the module would allow us to load conditionally if configured. We could also add a script from code, although that feels to me like we're getting into a bit dangerous waters - I know they're set up like that to capture load information, do they depend on that for non-load behavior (because we certainly won't have the org key available at load time in the current structure)?

[anandtiwary]

Unfortunately, some of the these tools don't have an npm module. We would have to add their script from the code. Btw, we are already doing this for the chat library.

These scripts are independent of init behavior. They expose a JS object which has methods like init, track etc. Unless we init them, they won't do anything.

[aaron-steinfeld]

They may not be called by default, but we'd still be loading them into the browser even if not using them. If that's our only option, so be it, but I'd think we have some options there even if it has to come via a script tag.

[anandtiwary]

Do you want to load them at init time?

[anandtiwary]

I am going ahead with this proposal. If you guys want to add anything more to the requirement then now is your chance :)

[JBAhire]

Late to the party, but this looks good! :)