Loop Analytics Library
This library makes use of the LDK's Network aptitude to support analytics within loops through builtin analytics services or can be extended to support custom services
Currently supported out of the box:

How to Use

1. Add the necessary aptitude permissions to your loop's package.json

The only required aptitude is network to make requests to the analytics service you choose. Some other aptitudes that can be helpful are user for getting the user's information and system for getting the user's operating system.
Note: Use the information from user and system aptitudes at your own risk. PII and PHI should NEVER be sent to an analytics service, only the minimum required info that is helpful for metrics should be used. If you are unsure whether your information would be considered PII or PHI or you don't need this info for your metrics, err on the side of caution and omit these aptitudes altogether.
Network Aptitude URLs for the provided Transports
Transport
URL
Google
google-analytics.com
Segment
api.segment.io
1
{
2
...
3
"ldk": {
4
"permissions": {
5
"whisper": {},
6
"system": {},
7
"user": {
8
"optionalClaims": [{ "value": "email" }]
9
},
10
"network": {
11
"urlDomains": [{ "value": "google-analytics.com" }]
12
}
13
}
14
}
15
}
Copied!

2. Set up the Analytics Client with your desired Transport

In this example we setup and export the Google Analytics client in a separate file to make it accessible across the loop
1
// analytics.ts
2
import { user, system } from '@oliveai/ldk';
3
import { AnalyticsClient, Transports } from '@oliveai/loop-analytics';
4
import jwtDecode from 'jwt-decode';
5
6
import { LOOP_NAME } from './index';
7
8
const createAnalyticsClient = async () => {
9
// Helper function to fetch the user's JWT and decode the payload
10
const getUserInfo = async () =>
11
jwtDecode<{ email: string; org: string; sub: string }>(
12
await user.jwt({ includeEmail: true })
13
);
14
15
// Get the info we need from LDK
16
const { sub: userId, email, org } = await getUserInfo();
17
const os = await system.operatingSystem();
18
19
// Define required and custom category/action pairings
20
// Export outside of this function to use across the loop for custom events if you'd like
21
const categoryActionMap: Transports.GoogleTransportTypes.CategoryActionMap = {
22
// === Required ===
23
whisperDisplayed: {
24
category: 'Whispers',
25
action: 'Whisper Displayed',
26
},
27
whisperClosed: {
28
category: 'Whispers',
29
action: 'Whisper Closed',
30
},
31
componentClicked: {
32
category: 'Click Events',
33
action: 'Component Clicked',
34
},
35
componentCopied: {
36
category: 'Click Events',
37
action: 'Component Copied',
38
},
39
// === Custom (Optional) ===
40
customEvent: {
41
category: 'Custom',
42
action: 'Custom Event',
43
},
44
};
45
46
// An example of how to set custom dimensions, use whatever is appropriate
47
const customDimensions: Transports.GoogleTransportTypes.CustomDimensionOrMetric[] =
48
[
49
{
50
index: 1,
51
name: 'Loop Name',
52
value: LOOP_NAME,
53
},
54
{
55
index: 2,
56
name: 'User ID',
57
value: userId, // The user's generated ID in Loop Library, not considered PII
58
},
59
{
60
index: 3,
61
name: 'Email Domain',
62
value: email.split('@')[1], // ONLY send the email domain, full email would be PII
63
},
64
{
65
index: 4,
66
name: 'Organization',
67
value: org,
68
},
69
{
70
index: 5,
71
name: 'Operating System',
72
value: os,
73
},
74
];
75
76
const transportConfig: Transports.GoogleTransportTypes.GoogleTransportConfig =
77
{
78
trackingId: 'UA-12345678-90',
79
// Can be whatever you want but is required for Google's request headers
80
userAgent: LOOP_NAME,
81
categoryActionMap,
82
customDimensions,
83
};
84
85
const userConfig: Transports.UserConfig = {
86
id: userId,
87
};
88
const loopConfig: Transports.LoopConfig = {
89
name: LOOP_NAME,
90
};
91
92
return new AnalyticsClient(
93
new Transports.GoogleTransport(transportConfig, userConfig, loopConfig)
94
);
95
};
96
97
// One example of how to export the client in a way that is accessible across the loop
98
export default await createAnalyticsClient();
Copied!

3. Use the new Analytics Client wherever it's needed

1
// index.ts
2
import { whisper } from '@oliveai/ldk';
3
import GA from './analytics';
4
5
export const LOOP_NAME = 'My Awesome Loop';
6
7
(async () => {
8
const label = 'Hello World!';
9
10
whisper.create({
11
label,
12
components: [],
13
onClose: () => GA.trackWhisperClosed(label),
14
});
15
16
GA.trackWhisperDisplayed(label, false);
17
})();
Copied!
Copy link
Contents
How to Use