ChurnZero

A framework-agnostic library for interacting with the ChurnZero API.

![Main][github-badge-release]

Table of Contents

- Installation
- Usage
- Configuration
- Inject the ChurnZero snippet
- Settings
- Initialize: Set app key and contact
- Stop URL tracking
- Silent mode
- Stop
- Debug
- Interactions
- Set attribute
- Set module
- Track event
- Register events
- Push: The escape hatch

Installation

Usage

Configuration

$3

The first step is to inject the ChurnZero snippet into your application. This is done by adding the following script
tag to your application's HTML.

You can add the snippet directly to your HTML, or you can inject it via the injectSnippet method.

HTML snippet

``html

`

Inject via method

Calling injectSnippet will look for a div with the ID of ChurnZero to inject the snippet into.

``typescript

`tsx
const ChurnZero = ChurnZero();
ChurnZero.injectSnippet();
``

Alternatively, you can pass a custom ID to the injectSnippet method and the snippet will be injected into that div.

`typescript
const ChurnZero = ChurnZero();
ChurnZero.injectSnippet('MyCustomId');
`

$3

#### Initialize: Set app key and contact

The initialize method is used to configure the ChurnZero instance. It should be initialized as soon as the user is
identified (usually as part of the log in process).

It accepts a single object with the following properties:

| Property | Type | Description |
| ------------ | ---------------------------- | ----------------------------------------------- |
| setAppKey | string | The application ID for your ChurnZero instance. |
| setContact | ChurnZeroSetContactPayload | The user details for current user. |

`typescript
ChurnZero.setAppKey('your-app-key');
ChurnZero.setContact({ accountExternalId: '12345', contactExternalId: '67890' });
`

#### Toggle URL tracking

URL tracking can be enabled/disabled at any time:

`typescript
ChurnZero.toggleUrlTracking(boolean);
`

#### Toggle Silent mode

Silent mode is to continue tracking but hide all visible elements. The silent mode can be enabled/disabled.

`typescript
ChurnZero.toggleSilentMode(boolean);
`

$3

You can stop the ChurnZero instance by calling the stop method at any time. This is often used in conjunction with
tracking the user's session.

`typescript
ChurnZero.trackEvent('Logout');
ChurnZero.stop();
`

$3

For troubleshooting purposes, you can enable debug mode by calling the debug method. Calling it a second time will disable debug mode.

`typescript
ChurnZero.debug();
`

Interactions

$3

The entity must be either contact or account and any number of attributes can be set at once:

`typescript
ChurnZero.setAttribute({
entity: 'account', // 'contact | 'account'
attributes: [{
'name': 'Email Enabled',
'value': true,
}, {
'name': 'Max users',
'value': 100,
}]
});
`

$3

As the user moves through the application it can be useful to track when they move between modules:

`typescript
ChurnZero.setModule('Module Name');
`

$3

Any number of events can be tracked via this method:

`typescript
ChurnZero.trackEvent({ eventName: 'My cool event' });
`

Optionally you can pass a payload with additional information:

`typescript
ChurnZero.trackEvent({
eventName: 'My cool event',
description: 'This is a description of the custom event.',
quantity: 12,
customFields: {
'Custom Field 1': 'Custom Field 1 Value',
'Custom Field 2': 'Custom Field 2 Value',
},
});
`

$3

If for any reason you need to access the underlying ChurnZero instance, you can do so by calling the push method.

`typescript
ChurnZero.push(['trackEvent', eventName, description, quantity, customFields]);
``

[//]: # 'LINKS'
[github-badge-release]: https://github.com/GetFlowPath/open-source/workflows/main/badge.svg