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

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

Inject the ChurnZero snippet

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

<script>
  var ChurnZero = ChurnZero || [];
  (function () {
    var cz = document.createElement('script');
    cz.type = 'text/javascript';
    cz.async = true;
    cz.src = 'https://yourvanitydomain.churnzero.net/churnzero.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(cz, s);
  })();
</script>

Inject via method

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

```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.

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

Settings

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

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

Toggle URL tracking

URL tracking can be enabled/disabled at any time:

ChurnZero.toggleUrlTracking(boolean);

Toggle Silent mode

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

ChurnZero.toggleSilentMode(boolean);

Stop

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.

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

Debug

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

ChurnZero.debug();

Interactions

Set attribute

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

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

Set module

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

ChurnZero.setModule('Module Name');

Track event

Any number of events can be tracked via this method:

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

Optionally you can pass a payload with additional information:

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',
  },
});

Push: The escape hatch

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

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