Javascript API
This page will help you get started with Candu Dev Docs. You'll be up and running in a jiffy!
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:
- Initialize an instance of Candu.
- 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:
- Remove a users session and Candu content when a user logs out of your page.
- 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
});
Updated 2 months ago