@nguyenquan241208/analytics-browser

Aicactus Analytics Browser is the JavaScript SDK - enabling you to send your data to Aicactus Customer Insight Platform (CIP).

Table of Contents

• 🏎️ Quickstart
  • 💡 Using with CIP Portal
  • 💻 Using as an npm package
• 🔌 Plugins
• 🐒 Development

---

🏎️ Quickstart

The easiest and quickest way to get started with Analytics Browser is to use it through CIP Portal. Alternatively, you can install it through NPM and do the instrumentation yourself.

💡 Using with CIP Portal

1. Create an integration at CIP Portal - new sources will automatically be using Analytics Browser! Aicactus will automatically generate a snippet that you can add to your website. For more information visit our documentation).

2. Start tracking!

💻 Using as an npm package

1. Install the package

# npm
npm install @nguyenquan241208/analytics-browser

# yarn
yarn add @nguyenquan241208/analytics-browser

# pnpm
pnpm add @nguyenquan241208/analytics-browser

2. Import the package into your project and you're good to go (with working types)!

import { AnalyticsBrowser } from '@nguyenquan241208/analytics-browser'

const analytics = AnalyticsBrowser.load({ secretKey: '<YOUR_SECRET_KEY>' })

analytics.identify('hello world')

document.body?.addEventListener('click', () => {
  analytics.track('document body clicked!')
})

Lazy / Delayed Loading

You can load a buffered version of analytics that requires .load to be explicitly called before initiating any network activity. This can be useful if you want to wait for a user to consent before fetching any tracking destinations or sending buffered events to segment.

• ⚠️ ️.load should only be called once.

export const analytics = new AnalyticsBrowser()

analytics.identify("hello world")

if (userConsentsToBeingTracked) {
    analytics.load({ secretKey: '<YOUR_SECRET_KEY>' }) // destinations loaded, enqueued events are flushed
}

This strategy also comes in handy if you have some settings that are fetched asynchronously.

const analytics = new AnalyticsBrowser()
fetchSecretKey().then(secretKey => analytics.load({ secretKey }))

analytics.identify("hello world")

Error Handling

Handling initialization errors

Initialization errors get logged by default, but if you also want to catch these errors, you can do the following:

export const analytics = new AnalyticsBrowser();
analytics
  .load({ secretKey: "YOUR_SECRET_KEY" })
  .catch((err) => ...);

Examples / Usage in Common Frameworks and SPAs

Vanilla React

import { AnalyticsBrowser } from '@nguyenquan241208/analytics-browser'

// We can export this instance to share with rest of our codebase.
export const analytics = AnalyticsBrowser.load({ secretKey: '<YOUR_SECRET_KEY>' })

const App = () => (
  <div>
    <button onClick={() => analytics.track('hello world')}>Track</button>
  </div>
)

Vue

1. Export analytics instance.

import { AnalyticsBrowser } from '@nguyenquan241208/analytics-browser'

export const analytics = AnalyticsBrowser.load({
  secretKey: '<YOUR_SECRET_KEY>',
})

2. in .vue component

<template>
  <button @click="track()">Track</button>
</template>

<script>
import { defineComponent } from 'vue'
import { analytics } from './services/segment'

export default defineComponent({
  setup() {
    function track() {
      analytics.track('Hello world')
    }

    return {
      track,
    }
  },
})
</script>

How to add typescript support (snippet users only)

1. Install npm package @nguyenquan241208/analytics-browser as a dev dependency.

2. Create ./typings/analytics.d.ts

// ./typings/analytics.d.ts
import type { AnalyticsSnippet } from "@nguyenquan241208/analytics-browser";

declare global {
  interface Window {
    analytics: AnalyticsSnippet;
  }
}

3. Configure typescript to read from the custom ./typings folder

// tsconfig.json
{
  ...
  "compilerOptions": {
    ....
    "typeRoots": [
      "./node_modules/@types",
      "./typings"
    ]
  }
  ....
}