Articles in this section

See more

Integrate ChurnZero using Javascript

Avatar
Peter Watt
  • Updated
Follow

Quick Links

Before using ChurnZero, you will need to integrate it with your application by including javascript in your page.

Install the required Code Snippet on Every Page 

The following code snippet must be included on all pages in your application

HTML

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

IMPORTANT: The endpoint for sending data to ChurnZero is personalized to your specific instance. The example above include a general URL to show the syntax. To find your exact endpoint, please login to your ChurnZero tenant and visit the Application Key Page in Admin.

Tell ChurnZero Who You and the User Are

The following code snippet must be set on every page after login:

JavaScript

ChurnZero.push(['setAppKey', 'XXX']); // AppKey from ChurnZero
ChurnZero.push(['setContact', '{accountExternalId}', '{contactExternalId}']);

This snippet allows ChurnZero to identify the user and determine your instance. The syntax of ChurnZero.push allows these methods to be called regardless of whether the asynchronous javascript load is complete. The following methods are supported/required.

App Identification (Required)

  • setAppKey (required): This is the unique ID of your app in the ChurnZero system. This can be found within the ChurnZero Application under Admin>Application Keys

Contact Identification (Required)

The integration requires a way to link a Contact to your application. This is done by identifying the contact and the account.
The AccountExternalID is your unique record to identify your account. This ID should be in your CRM.
The contactExternalId must be unique within the account. This could be a email address, a unique record that is also contained in your CRM, or the ID of the contact record of your CRM.

Page Refreshes

If you opt to identify during your login code, be sure to account for page refreshes. If your app allows users to refresh the page without having to login again make sure the identity is set during the auto-login code as well.

The simplest way to avoid this situation is to put the identifying snippet at the bottom of every page in its own script tag.

 

Looking for advanced security verification?

Check out our documentation on configuring Enhanced Identity Verification

_________________________________________________________________________________________________________________

Verify

Once the appKey and setContact calls have been made your app is successfully connected! You can verify the details of your connection by opening the developer tools and calling verify from the ChurnZero object.

JavaScript

ChurnZero.verify();
This will provide you with the current details about the connected app, account, contact, and connection status.
_________________________________________________________________________________________________________________

Track Event

Events are a key element of ChurnZero as it allows you to track what a user is doing. For events to be tracked the setCustomer, etc code must have executed. To track an event add the following code wherever you want to track an event:

JavaScript

ChurnZero.push(['trackEvent', eventName, description, quantity, customFields]);
  • eventName (Required)- This is the unique name of the event (i.e Sent Blog Post). If the Event Name is not found it will be created.
  • description (optional)- A description of the Event (i.e Blog Title).
    • Note: There is a 255 character limit on this field. If there are more than 255 characters included we will still process the event, the value will just be truncated to be within the limit. 
  • quantity (optional)- The number related to this event (Commonly used to track things like email sent, etc)
  • customfields (optional)-Additional custom fields in a name/value pair. Important Note: At this time, custom fields cannot be created on the fly. Please make sure to request any required custom field(s) before attempting to send any data. Requests can be made through your ChurnZero Implementation Specialist or by reaching out to support@churnzero.net.

Example:

In the example below, the event 'Email Sent' is being tracked with a description being set to 'Email Subject' and a quantity of '5' with two custom fields "field1" and "field2".

JavaScript

ChurnZero.push(['trackEvent', 'Email Sent', 'Email Subject', 5, {field1: 'field1Value', field2: 'field2Value'}]);

_________________________________________________________________________________________________________________

Set Attribute on Account or Contact

Attributes about the account or features can be tracked in ChurnZero by using the setAttribute method. Attributes can be set one at a time or in batch via a document.

JavaScript for Setting One Attribute

ChurnZero.push(['setAttribute', entity, name, value]);
  • Entity (Required)- Can be either 'contact' or 'account'
  • Name(Required)- Name of the field to be updated
  • Value (Required)- Value to be used for the update. This value must be type compatible.

Example:

In the example below, the contact's custom field 'Profile Enabled' is going to be true

JavaScript

ChurnZero.push(['setAttribute', 'contact', 'Profile Enabled', true]);
In the example below, you can set the account's maximum number of users allowed.

JavaScript

ChurnZero.push(['setAttribute', 'account', 'Max Users', 100]);

 JavaScript for Setting Multiple Attributes

ChurnZero.push(['setAttribute', entity, attributes]);
  • Entity (required)- can be either 'contact' or 'account'
  • Attributes (required)- Attributes in a name/value pair

Example:

In the example below, you can set the Account Attribute "Email Enabled" to true and "Emails Sent to 100"

JavaScript

ChurnZero.push(['setAttribute', 'account', {'Email Enabled': true, 'Emails Sent': 100}]);
Updatable Standard Fields (Account and Contact)

For both forms of the setAttribute method, only the following standard fields (in addition to the custom fields) can be updated.

IMPORTANT:  If your company's ChurnZero instance will be connected to your company's CRM (Salesforce, HubSpot, Pipedrive, etc.), by default ALL of these standard account and contact attributes will be populated by your CRM. If your CRM is not the best source of accurate data for these fields, you can provide these values through the JS instead. But please coordinate with your ChurnZero CSM to make sure that your CRM sync will not update fields you will be updating via the JS. The same field in ChurnZero should not have two sources of data.

Standard Account Fields

  • Name (string)
  • NextRenewalDate (date)
  • TotalContractAmount (double)
  • IsActive (Boolean)
  • BillingAddressLine1 (string),
  • BillingAddressLine2 (string)
  • BillingAddressCity (string)
  • BillingAddressState (string)
  • BillingAddressZip (string)
  • StartDate (datetime)
  • EndDate (datetime)
  • LicenseCount (int)
  • OwnerUserAccount (string - matches on UserName)
  • ParentAccountExternalId (string)

Standard Contact Fields

  • FirstName (string)
  • LastName (string)
  • Email (string)

_________________________________________________________________________________________________________________

Increment Attribute on Account or Contact

Numeric attribues can be incremented via the incrementAttriubute Method. Like the setAttribute method, numeric values can be incremented one at a time or batch via a document.

JavaScript for Incrementing One Attribute

ChurnZero.push(['incrementAttribute', entity, name, value]);
  • Entity (Required)- Can be either 'contact' or 'account'
  • Name(Required)- Name of the field to be updated
  • Value (Required)- Value to increment attribute by (can be negative)

Example:

This example increments the Account Attribute 'Total Email Sent' by 3

JavaScript

ChurnZero.push(['incrementAttribute', 'account', 'Total Email Sent', 3]);
JavaScript for Incrementing Multiple Attributes
ChurnZero.push(['incrementAttribute', entity, attributes);
  • Entity (Required)- Can be either 'contact or 'account'
  • Attributes (Required)- Attributes in a name/value pair where value is the amount to increment (can be negative)

Example:

This example increments the Account Attribute "Total Email Sent" by 3 and increments the Account Attribute "Total Tweets" by 10.

JavaScript

ChurnZero.push(['incrementAttribute', 'account', {'Total Email Sent': 3, 'Total Tweets': 10}]);

_________________________________________________________________________________________________________________

Stop

Shut down the ChurnZero instance. This is mostly used for single page applications (SPA) that have a login/logout page within their SPA. A scenario could arise where a user logs in successfully, does some stuff , and then logs out without ever triggering a new page. In this case, once your app has logged the user out your development team would want to tell the ChurnZero instance to stop (and maybe even fire a logout event!).

*Because calling stop resets the ChurnZero instance, both the appKey and the contactKey are cleared and will be required to start a new ChurnZero Instance.

Example:

Here is an example where after your logout code you want to track a logout event and then tell the ChurnZero instance to shutdown
JavaScript

//Your Login Code 
ChurnZero.push(['setAppKey', 'XXX']); // AppKey from ChurnZero
ChurnZero.push(['setContact', '{accountExternalId}', '{contactExternalId}']);

...

//Your Logout Code
ChurnZero.push(['trackEvent', 'Logout']);
ChurnZero.push(['stop']);

_________________________________________________________________________________________________________________

Track Time in Module

Time in app is recorded to a standard "Default" module if no other module is set but if you would like to track time in app at a more granular level you can specify which module is currently active. The last set module will be active until either the page reloads or a new module is set.
JavaScript

ChurnZero.push(['setModule', module]);
  • module (required)- The Name of the module

Example:

This example sets the module to Dashboard

JavaScript

ChurnZero.push(['setModule', 'Dashboard']);

_________________________________________________________________________________________________________________

Stop URL Based Tracking

By default the URL and the title of the page are transmitted with the event data and the time in module data but if you would prefer not to include this data simply turn off URL tracking at any time. If you want to be sure no URL data is ever sent be sure to turn it off prior to setting the contact identity.

JavaScript

ChurnZero.push(['urltracking', false]);

_________________________________________________________________________________________________________________

Silent Mode

If a situation arises where you would like to hide all visible aspects of the Success Panel including any currently displayed or future announcements but you still want usage tracking you can activate Silent Mode.

JavaScript

ChurnZero.push(['silent',true]);
_________________________________________________________________________________________________________________

Programmatically Open/Close the Success Panel or Success Center using Javascript

If you would like to open the success panel via an action other than clicking the launch avatar this can be done using a single javascript command:

ChurnZero.push(['open']);

If you would like to close the panel via an action other than clicking the close button within the panel this can be done using a single javascript command:

ChurnZero.push(['close']);

_________________________________________________________________________________________________________________

Troubleshooting

If you are setting up the ChurnZero Javascript and things dont seem to be lining up properly it might be useful to turn on the debug logging.

JavaScript

ChurnZero.debug();
Once the debug logging has been turned on two things will happen. First a verification table will be logged to the console (See Verify above for more info). The second thing that will happen is that any calls to ChurnZero.push will now be logged out to the console in addition to being processed. This will continue to happen until ChurnZero.debug() is called a second time.

The most common scenario here is debugging the actual values that are pushed for appKey, externalAccountId, and externalContactId. Simply refresh the page after calling ChurnZero.debug() and both the setAppKey and setContact calls will be logged to the console with the pushed values.

Using the Dev Console

The Dev Console can be a useful troubleshooting tool, as it allows for increased visibility into the information being sent to ChurnZero via JS as well as the status of those calls. It can be used to search for failures as well as the causes for missing data. The Dev Console is available in all environments you have access to, so you can test JS calls to your development instance before implementing it in your production environment.

Registering Event Callbacks

Certain ChurnZero events can have callbacks registered against them so that when they occur your code can respond.

Connected Event

The call back receives 1 parameter that has 2 properties: hasCenter and hasPanel.

  • The hasCenter property will reflect if the current connection is to display a SuccessCenter.
  • The hasPanel property will reflect if the current connection is to display a panel.

If called after the connection has been established the callback is called immediately.

This event can be used if you wish to hide something else that might be in the place where the success panel launcher will be displayed.

Example:

 ChurnZero.push(['ChurnZeroEvent:on', 'connected', function (data) { console.log('This contact has a SuccessCenter', data.hasCenter); console.log('This contact has a panel', data.hasPanel); }]);

Deregistering Event Callbacks

if you wish to remove a specific callback that was previously registered you must pass in a reference to the callback that was registered. This means that inline functions can not be specifically deregistered. If you know you will want to deregister a callback you must create a reference to the callback function and keep that reference until the time you wish to deregister it.

Example:

//register 

const myCallback = (data) => { console.log('This contact has a panel', data.hasPanel); }; ChurnZero.push(['ChurnZeroEvent:on', 'connected', myCallback]);
 … some amount of code … 

//deregister ChurnZero.push(['ChurnZeroEvent:off', 'connected', myCallback]);
You can deregister all callbacks for an event type by omitting a callback function in the off call.

Example:

//deregister 
ChurnZero.push(['ChurnZeroEvent:off', 'connected']); 

Related articles

Comments

0 comments

Article is closed for comments.