LogoLogo
Developer HubGitHubContact Us
  • Welcome!
  • Olive Helps
    • Platform
      • How Olive Helps Works
      • Installation
      • Account Creation
      • Distributing Olive Helps
    • FAQs
      • General Loop FAQs
      • Loop Development FAQs
      • Olive Helps User FAQs
      • Security / IT FAQs
    • Data Security
      • User Data
      • Antivirus and Firewalls
  • Loop Development Kit
    • Your First Loop
      • Become a Loop Author
      • Creating a Loop
      • Build Your Loop
      • Local Loop Installation
      • Restarting Local Loops
    • Troubleshooting
    • Loop Security
      • Permissions
      • Environment Permissions
    • Loop Publication
      • Loop Approval Checklist
    • Loop Analytics Library
    • Examples
  • Documentation
  • Interfaces
  • Type Alias
  • Enumerations
  • Whisper Components
    • Base Attributes
    • Autocomplete
    • Box
    • Breadcrumb
    • Button
    • Chart
    • CollapseBox
    • Grid
    • Checkbox
    • Date Time
    • Divider
    • DropZone
    • Email
    • Icon
    • List Pair
    • Link
    • Pagination
    • Number
    • Markdown
    • Message
    • Password
    • Progress
    • Radio
    • Rating
    • RichTextEditor
    • Section Title
    • Select
    • Text Input
    • Telephone
    • Typography
  • APTITUDES
    • What are Aptitudes?
    • Browser
    • Clipboard
    • Config
    • Cursor
      • Screen Scaling Behavior
    • Document
    • Filesystem
    • Keyboard
    • Network
    • Process
    • Screen
    • Search
      • Index
    • System
    • UI
      • Loop UI Handlers
    • User
      • JWT
    • Vault
    • Whisper
      • Whisper Updates
      • JSX Whispers
    • Window
      • Screen Scaling Behavior
  • Release Notes
    • What's New
      • Olive Helps v0.55.0
      • Olive Helps v0.54.1
      • Olive Helps v0.53.1
      • Olive Helps v0.51.2
      • LDK v4.0.0
      • Olive Helps v0.50.3
      • Olive Helps v0.49.5
      • LDK v 3.18.0
      • Olive Helps v0.47.2
      • Olive Helps v0.46.2
      • LDK v 3.17.0
      • Olive Helps v0.45.4
      • Olive Helps v0.44.2
      • Olive Helps v0.43.1
      • Olive Helps v0.42.1
      • Olive Helps v0.41.4
      • Olive Helps v0.40.2
      • Olive Helps v0.39.4 & LDK v3.16.0
      • Olive Helps v0.38.8 & LDK v3.15.0
      • Olive Helps v0.36.5
      • Olive Helps v0.36.4
    • Archive
      • Olive Helps v0.36.3 & LDK v3.14.0
      • Olive Helps v0.34.4
      • LDK v3.13.0
      • Olive Helps v0.32.2 & LDK v3.12.0
      • Olive Helps v0.31.2 & LDK v3.11.0
      • Olive Helps v0.30.2 & LDK v3.10.0
      • Olive Helps v0.29.4
      • Olive Helps v0.29.3 & LDK v3.9.0
      • Olive Helps v0.28.3 & LDK v3.8.0
      • Olive Helps v0.27.7
      • Olive Helps v0.27.5
      • Olive Helps v.027.4
      • Olive Helps v0.27.2 & LDK v3.7.0
      • Olive Helps v0.25.3 & LDK v3.5.1
      • Olive Helps v0.24.6 & LDK v3.4.0
      • Olive Helps v0.23.2 & LDK v3.3.0
      • Olive Helps v0.22.3 & LDK v3.2.0
Powered by GitBook
On this page

Was this helpful?

  1. Loop Development Kit

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

PreviousLoop Approval ChecklistNextExamples

Last updated 2 years ago

Was this helpful?

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

{
  ...
  "ldk": {
    "permissions": {
      "whisper": {},
      "system": {},
      "user": {
        "optionalClaims": [{ "value": "email" }]
      },
      "network": {
        "urlDomains": [{ "value": "google-analytics.com" }]
      }
    }
  }
}

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

// analytics.ts
import { user, system } from '@oliveai/ldk';
import { AnalyticsClient, Transports } from '@oliveai/loop-analytics';
import jwtDecode from 'jwt-decode';

import { LOOP_NAME } from './index';

const createAnalyticsClient = async () => {
  // Helper function to fetch the user's JWT and decode the payload
  const getUserInfo = async () =>
    jwtDecode<{ email: string; org: string; sub: string }>(
      await user.jwt({ includeEmail: true })
    );

  // Get the info we need from LDK
  const { sub: userId, email, org } = await getUserInfo();
  const os = await system.operatingSystem();

  // Define required and custom category/action pairings
  // Export outside of this function to use across the loop for custom events if you'd like
  const categoryActionMap: Transports.GoogleTransportTypes.CategoryActionMap = {
    // === Required ===
    whisperDisplayed: {
      category: 'Whispers',
      action: 'Whisper Displayed',
    },
    whisperClosed: {
      category: 'Whispers',
      action: 'Whisper Closed',
    },
    componentClicked: {
      category: 'Click Events',
      action: 'Component Clicked',
    },
    componentCopied: {
      category: 'Click Events',
      action: 'Component Copied',
    },
    // === Custom (Optional) ===
    customEvent: {
      category: 'Custom',
      action: 'Custom Event',
    },
  };

  // An example of how to set custom dimensions, use whatever is appropriate
  const customDimensions: Transports.GoogleTransportTypes.CustomDimensionOrMetric[] =
    [
      {
        index: 1,
        name: 'Loop Name',
        value: LOOP_NAME,
      },
      {
        index: 2,
        name: 'User ID',
        value: userId, // The user's generated ID in Loop Library, not considered PII
      },
      {
        index: 3,
        name: 'Email Domain',
        value: email.split('@')[1], // ONLY send the email domain, full email would be PII
      },
      {
        index: 4,
        name: 'Organization',
        value: org,
      },
      {
        index: 5,
        name: 'Operating System',
        value: os,
      },
    ];

  const transportConfig: Transports.GoogleTransportTypes.GoogleTransportConfig =
    {
      trackingId: 'UA-12345678-90',
      // Can be whatever you want but is required for Google's request headers
      userAgent: LOOP_NAME,
      categoryActionMap,
      customDimensions,
    };

  const userConfig: Transports.UserConfig = {
    id: userId,
  };
  const loopConfig: Transports.LoopConfig = {
    name: LOOP_NAME,
  };

  return new AnalyticsClient(
    new Transports.GoogleTransport(transportConfig, userConfig, loopConfig)
  );
};

// One example of how to export the client in a way that is accessible across the loop
export default await createAnalyticsClient();

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

// index.ts
import { whisper } from '@oliveai/ldk';
import GA from './analytics';

export const LOOP_NAME = 'My Awesome Loop';

(async () => {
  const label = 'Hello World!';

  whisper.create({
    label,
    components: [],
    onClose: () => GA.trackWhisperClosed(label),
  });

  GA.trackWhisperDisplayed(label, false);
})();
Google Analytics (Universal)
Segment