npm package: @nguyenquan241208/analytics-browser
Description: Aicactus Analytics Browser is the JavaScript SDK - enabling you to send your data to Aicactus Customer Insight Platform (CIP).
Latest version: 0.0.11

# @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](#-quickstart)
  - [💡 Using with CIP Portal](#-using-with-cip-portal)
  - [💻 Using as an `npm` package](#-using-as-an-npm-package)
- [🔌 Plugins](#-plugins)
- [🐒 Development](#-development)

---

# 🏎️ Quickstart

The easiest and quickest way to get started with Analytics Browser is to [use it through CIP Portal](#-using-with-cip-portal). Alternatively, you can [install it through NPM](#-using-as-an-npm-package) and do the instrumentation yourself.

## 💡 Using with CIP Portal

1. Create an integration at [CIP Portal](https://cip-portal.aicactus.io) - 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](https://docs.aicactus.io)).

2. Start tracking!

## 💻 Using as an `npm` package

1. Install the package

```sh
# 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)!

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

const analytics = AnalyticsBrowser.load({ secretKey: '<YOUR_SECRET_KEY>' },
 {
        attributeType: 'email', // change with your type
        attributeValue: 'abcd@gmail.com', // Change with your value
    }) // destinations loaded, enqueued events are flushed)

analytics.identify('hello world')


// With properties and option
analytics.identify(
   eventName || '', // Change with event name
   properties || {}, // Change with properties
   options || {} , // Change with options
   )



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

document.body?.addEventListener('click', () => {
  analytics.track(
    eventName || '', // Change with event name
    properties || {}, // Change with properties
    options || {} , // Change with options
  )
})



document.body?.addEventListener('click', () => {
  analytics.delivery(
    code, // change with delivery code
    secretKey, // change with secret key
    options || {}// Change with options
  )
})




```

## 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_.

```ts
export const analytics = new AnalyticsBrowser()

analytics.identify("hello world")

// With properties and option
analytics.identify(
   eventName || '', // Change with event name
   properties || {}, // Change with properties
   options || {} , // Change with options
   )

if (userConsentsToBeingTracked) {
    analytics.load({ secretKey: '<YOUR_SECRET_KEY>' },
    {
        attributeType: 'email', // change with your type
        attributeValue: 'abcd@gmail.com', // Change with your value
    }) // destinations loaded, enqueued events are flushed
}
```
This strategy also comes in handy if you have some settings that are fetched asynchronously.
```ts
const analytics = new AnalyticsBrowser()
fetchSecretKey().then(secretKey => analytics.load({ secretKey },
 {
    attributeType: 'email', // change with your type
    attributeValue: 'abcd@gmail.com', // Change with your value
  }
))

analytics.identify("hello world")

// With properties and option
analytics.identify(
   eventName || '', // Change with event name
   properties || {}, // Change with properties
   options || {} , // Change with options
   )


    analytics.delivery(
    code, // change with delivery code
    secretKey, // change with secret key
    options || {}// Change with options
  )
```
## 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:
```ts
export const analytics = new AnalyticsBrowser();
analytics
  .load({ secretKey: "YOUR_SECRET_KEY" },
 {
    attributeType: 'email', // change with your type
    attributeValue: 'abcd@gmail.com', // Change with your value
  })
  .catch((err) => ...);
```

## Examples / Usage in Common Frameworks and SPAs

### Vanilla React
```tsx
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>' },
 {
    attributeType: 'email', // change with your type
    attributeValue: 'abcd@gmail.com', // Change with your value
  })

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

// With properties and option
const App = () => (
  <div>
    <button onClick={() =>   analytics.track(
    eventName || '', // Change with event name
    properties || {}, // Change with properties
    options || {} , // Change with options
  )}>Track</button>
  </div>
)




```



### Vue

1. Export analytics instance.

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

export const analytics = AnalyticsBrowser.load({
  secretKey: '<YOUR_SECRET_KEY>',
},
 {
    attributeType: 'email', // change with your type
    attributeValue: 'abcd@gmail.com', // Change with your value
  })
```

2. in `.vue` component

```tsx
<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`
```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
```jsonc
// tsconfig.json
{
  ...
  "compilerOptions": {
    ....
    "typeRoots": [
      "./node_modules/@types",
      "./typings"
    ]
  }
  ....
}
```