@churnassassin/sentry-beacon/README.md

NPM loader for the Churn Assassin Sentry Beacon tracking agent

# @churnassassin/sentry-beacon

The official NPM loader for the **Sentry Beacon** and **Sentry Panel** tracking agents used by [Churn Assassin](https://churnassassin.com).

This lightweight module allows you to initialize customer activity tracking from within your frontend JavaScript app (React, Vue, etc.) without needing to manually embed `<script>` tags.

---

## 🚀 Installation

```bash
npm install @churnassassin/sentry-beacon
```

---

## ✅ Usage

Import and initialize the beacon in your frontend app (e.g., React, Vue, plain JS):

```js
import { initSentryBeacon } from '@churnassassin/sentry-beacon'

initSentryBeacon({
token: "[Provided By Churn Assassin]",
useragent: navigator.userAgent,
activity: window.location.pathname,    // or other variable containing the event
qs: window.location.search,            // or other variable containing event details
company_name: 'ABC-123',               // Alpha-numeric company name
companyid: 'ABC-123',                  // Alpha-numeric company id
enduser_email: 'user@example.com',     // email of end user logged into your app
enduser_firstname: 'Jane',             // first name of end user logged into your app
enduser_lastname: 'Doe',               // last name of end user logged into your app
enduserid: 'user-789',                 // unique id of end user logged into your app
productid: '1',                        // Numeric, default: 1
platformid: '2'                        // Numeric, default: 2
})
```

---

## 💡 What It Does

When called, this function:
1. Assigns a global `window.assassindata` object with all user/session metadata.
2. Injects the Sentry Beacon script:  
   `https://api.churnassassin.com/static/js/churnassassin.js`
3. Injects the Sentry Panel script (optional UI module):  
   `https://api.churnassassin.com/static/js/engagement.js`

These scripts then begin reporting usage and engagement activity within your application to Churn Assassin.

---

## 🔐 Notes

- Make sure `token` and user-specific fields are injected dynamically based on your current logged-in user.
- Scripts are only injected once per page load (duplicate protection is built-in).
- This module is intended to run in the browser only (not SSR).
- SPA's (single page applications): Should use a custom router to populate the [activity] and [qs] properties

---

## 🛠️ Support

Need help? Email [support@churnassassin.com](mailto:support@churnassassin.com) or contact your onboarding specialist.

---

## 📄 License

MIT © Brian Polackoff / Churn Assassin