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: One or more groups the user is a member of. Each group may have traits which are common across all users in a group
  groups: [{ id: "group-1", traits: { name: "GROUP_NAME" } }],
  // 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',
  // Optional: callbacks are used to add interactivity to your documents. See below for guide.
  callbacks: { onButtonClick: () => 'callback' }
});

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

Full documentation for callbacks can be found here

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;
  group: (groupId: string, traits?: 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.

Triggering Content Programmatically

For most use cases we recommend placing content with the Candu Extension , but for advanced use cases you may need to trigger content programmatically.

You'll need to implement any conditional logic when setting up the trigger on your side, as they do not apply any placements, i.e. URL rules you have set up in Candu. Trigger content will still abide by Segmentation rules.

As a best practice, we recommend removing the trigger snippet from your code when you no longer want the content to be triggered as triggering content programmatically bypasses publish state.

Candu.renderContent

To render a piece of Inline Content. You can target either an element or a CSS selector

window.Candu.renderContent({
  // Mandatory: the slug of a content that you'd like to render.
  slug: 'your-content-slug',
  // Optional: a reference to the DOM element you would like to render the content inside
  element: document.getElementById('candu-target'),
  // Optional: a string containing the CSS selector you would like to render indo
  selector: '#candu-target',
  // Optional, used to specify if Candu Content should be added at the start, end or replace the target element
  // 		Valid values are: 'Start' | 'End' | 'Replace'. Defaults to 'Start'
  selectorLocation: 'End'
});

Content rendered into an element are added for the given page load, until the Element is removed from the DOM.

Selector based renders use DOM Observer APIs to listen for matches that occur later. The first match is always used.

Here is an example selector based renderContent call:

window.Candu.renderContent({
  slug: 'your-content-slug',
  selector: '#candu-target',
});

Candu.triggerModal

Used to trigger Overlays, pop-ups and slide-outs. On-screen position is configured within the Candu Editor. Note: Modals can also be triggered on page load guide or from Candu content guide.

window.Candu.triggerModal({ slug: 'your-modal-slug' })

Candu.triggerTour

Used to trigger Tours that guide users within your product. Individual Tour Step locations can be configured within the Candu Editor. Note: Tours can also be triggered on page load or from Candu content guide.

window.Candu.triggerTour({ slug: 'your-tour-slug' })

Candu.triggerHotspotGroup

Used to trigger a group of Beacons that can be clicked to open Tooltips. Beacon locations are configured within the Candu Editor. Note: Hotspots can also be triggered on page load or from Candu content guide.

window.Candu.triggerHotspotGroup({ slug: 'your-hotspots-slug' })