The DataHub React application can be configured to emit a set of standardized product analytics events to multiple backend providers including
- Mixpanel
- Amplitude
- Google Analytics
This provides operators of DataHub with visibility into how their users are engaging with the platform, allowing them to answer questions around weekly active users, the most used features, the least used features, and more.
To accomplish this, we have built a small extension on top of the popular [Analytics](https://www.npmjs.com/package/analytics) npm package. This package was chosen because it offers a clear pathway to extending support to many other providers, all of which you can find listed [here](https://github.com/DavidWells/analytics#analytic-plugins).
## Configuring an Analytics Provider
Currently, configuring an analytics provider requires that you fork DataHub & modify code. As described in 'Coming Soon', we intend to improve this process by implementing no-code configuration.
- This plugin requires use of Universal Analytics and does not yet support GA4. To create a Universal Analytics Property, follow [this guide](https://www.analyticsmania.com/other-posts/how-to-create-a-universal-analytics-property/).
- Google Analytics lacks robust support for custom event properties. For that reason many of the DataHub events discussed above will not be fully populated. Instead, we map certain fields of the DataHub event to the standard `category`, `action`, `label` fields required by GA.
2. Uncomment the `googleAnalytics` field within the `config` object.
3. Replace the sample `trackingId` with the one provided by Google Analytics.
4. Rebuild & redeploy `datahub-frontend-react` to start tracking.
```typescript
const config: any = {
googleAnalytics: {
trackingId: 'UA-24123123-01',
},
};
```
## Verifying your Analytics Setup
To verify that analytics are being sent to your provider, you can inspect the networking tab of a Google Chrome inspector window:
With DataHub open on Google Chrome
1. Right click, then Inspect
2. Click 'Network'
3. Issue a search in DataHub
4. Inspect the outbound traffic for requests routed to your analytics provider.
## Development
### Adding a plugin
To add a new plugin from the [Analytics](https://www.npmjs.com/package/analytics) library:
1. Add a new file under `src/app/analytics/plugin` named based on the plugin
2. Extract configs from the analytics config object required to instantiate the plugin
3. Instantiate the plugin
4. Export a default object with 'isEnabled' and 'plugin' fields
5. Import / Export the new plugin module from `src/app/analytics/plugin/index.js`
If you're unsure, check out the existing plugin implements as examples. Before contributing a plugin, please be sure to verify the integration by viewing the product metrics in the new analytics provider.
### Adding an event
To add a new DataHub analytics event, make the following changes to `src/app/analytics/event.ts`:
1. Add a new value to the `EventType` enum
```typescript
export enum EventType {
LogInEvent,
LogOutEvent,
...,
MyNewEvent
}
```
2. Create a new interface extending `BaseEvent`
```typescript
export interface MyNewEvent extends BaseEvent {
type: EventType.MyNewEvent; // must be the type you just added
... your event's custom fields
}
```
3. Add the interface to the exported `Event` type.
```typescript
export type Event =
| LogInEvent
| LogOutEvent
....
| MyNewEvent
```
### Emitting an event
Emitting a tracking DataHub analytics event is a 2-step process:
1. Import relevant items from `analytics` module
```typescript
import analytics, { EventType } from '../analytics';
```
2. Call the `event` method, passing in an event object of the appropriate type
