Javascript API

Candu's Javascript API is accessible via the window object, using the window.Candu object.

Candu.init

Candu.init a method used to initialize Candu.

At a high level, Candu.init performs the following actions:

1. Initialize an instance of Candu.
2. Talks to Candu servers to get a user's state.

Candu.init takes only one parameter, an init object. This is the same object that you pass in when you install the script tag.

Here is how to call Candu.init:

window.Candu.init({
  // Required: your client token
  clientToken: 'YOUR_CLIENT_TOKEN',
  // Optional: provide a User Id
  userId: 'USER_ID_TO_TRACK',
  // Optional: Traits provide a way to pass information about your users for segmentation and variables
  traits: { email: '[email protected]', name: 'Georgia' },
  // Optional: Only used for "secret" variables as they are never logged to a server.
  variables: { customerSecret: 'my variable secret'},
  // Optional: hmac secret for a given userId. Required if you turned on identity verification.
  hmac: 'hmac computed using the userId. The user id value must match the userId above.',
  // Optional: callbacks are used to add interactivity to your documents. See below for guide.
  callbacks: { onButtonClick: () => 'callback' }
});

callbacks functions have the following signature:

(e: Event, node: object, action: object) => void;

Candu.init may be called multiple times if the logged in user changes.

Please refer to the Script Installation Guide to see a full details about how to install Candu

Candu.getEventing

Candu.getEventing returns a javascript object that you can use to send us additional eventing data, such as button clicks or page views. It's useful in case you want to track events that occur outside of Candu.

Candu.getEventing takes no parameters, and returns an object with the following interface:

interface Eventing {
  identify: (userId: string, traits?: object) => void;
  track: (eventName: string, properties?: object) => void;
  page: (pageName: string, properties?: object) => Promise<void>;
  screen: (screenName: string, properties?: object) => void;
}

Here is how to call Candu.eventing:

const eventing = window.Candu.getEventing();
eventing.track('cart.button.click', { amountPaidInUSD: 30 });

Candu.tearDown

Candu.tearDown is used to destroy and teardown a client. This can be useful to:

1. Remove a users session and Candu content when a user logs out of your page.
2. Free up browser resources in case you don't need Candu anymore on a page.

Candu.tearDown takes no parameters.

Here is how to call Candu.tearDown:

window.Candu.tearDown();

Calling Candu.tearDown is not necessary if a logout reloads the page.

Candu.getMembership

This call returns the Segment IDs that the current customer belongs to in Candu Segmentation. Segment IDs correspond with individual segments configured within the Candu dashboard.

This can be used to determine if a customer falls in to a specific Candu Segment to provide supporting content.

window.Candu.getMembership();

Example usage:

window.Candu.getMembership().then((segments) => {
  if (segments.contains('xlGqv7gQMY')) {
  	showAdditionalNavigation(); // external function to show extra supporting content
  }
});

Candu.refreshMembership

This call is used to force the Candu client to reload Candu Segmentation.

window.Candu.refreshMembership();

You should refresh membership if an event occurs that you expect to have updated Segment membership and want the customer to see this in real-time.

For example, firing a conversion event that would lead to seeing a different banner.

This may be combined with a call to eventing like this:

const afterEnterprisePurchase = () => {
  const eventing = Candu.getEventing();
  eventing.track('Purchased Enterprise Plan').then(() => {
    Candu.refreshMembership();
    // On-page Candu content that uses segmentation based off this event should now be updated
  });
}

You should only need to do this if state has updated since Candu was initialized.

If you don't explicitly refresh membership then it will be refreshed on the call to Candu.init, typically on the next page load.

Candu.renderContent

Candu.renderContent is used to programmatically render a piece of Content. This is an advanced method, and we don't encourage using it directly. Please refer instead to our guide on how to place content.

Here is how to call Candu.renderContent:

window.Candu.renderContent({
  // Mandatory: the slug of a content that you'd like to render.
  slug,
  // Optional: the DOM element that you'd like to render into.
  //           You must provide either `element` or `selector`.
  element,
  // Optional: an HTML selector that you'd like to render into.
  //           You must provide either `element` or `selector`.
  selector
});