Advanced: Using the ‘crl8’ API

Overview

Curalate’s Experience snippet adds a crl8 JavaScript global object to your webpage. The global object comes with a number of advanced features that a developer can use to interact with the Experience and control its behavior. Functionality includes:

Creating, retrieving, and destroying Experiences, including controlling the loading behavior
Listening to events
Firing metric events

Experience API

Note: Some of the Experience API is asynchronous. This is because certain methods require fetching additional resources. The Promises returned by these functions can be interacted with using normal Promise methods: See MDN’s guide to JavaScript Promises.

General

crl8.ready
@param (callback function)

The rest of the crl8 API is loaded asynchronously from the Curalate snippet, so use this hook to wrap all other calls to the crl8 API. This will ensure that you are accessing the other methods safely.

crl8.ready(() => {
  // fire other crl8 methods here
});

crl8.ready(() => {

// fire other crl8 methods here

});

Create, Retrieve, and Destroy Experience Instances

crl8.createExperience
@param (string containerId | node element)
@returns Promise[ExperienceInstance]

One common use case for this method is controlling when an Experience loads. To do so, first place a data-crl8-auto-init=false attribute on the <div> included with your Experience snippet. Then, later, call the crl8.createExperience method to boot up the Experience at a time of your choosing.

crl8.createExperience('homepage').then((instance) => doSomething());

1	crl8.createExperience('homepage').then((instance) => doSomething());

crl8.getExperience
@param (string containerId | node element)
@returns Promise[ExperienceInstance]

crl8.getExperience('homepage').then((instance) => doSomething());

1	crl8.getExperience('homepage').then((instance) => doSomething());

crl8.getAllExperiences
@returns Promise[Array[ExperienceInstance]]

crl8.getAllExperiences().then((arrayOfInstances) => doSomething());

1	crl8.getAllExperiences().then((arrayOfInstances) => doSomething());

crl8.destroyExperience
@params (string containerId | node element)

crl8.destroyExperience('homepage');

1	crl8.destroyExperience('homepage');

crl8.destroyAllExperiences

crl8.destroyAllExperiences();

1	crl8.destroyAllExperiences();

Event Listeners

The crl8.EventBus object contains a standard set of event listener capabilities. Use this to interact with various kinds of event streams being generated by the Experience.

crl8.EventBus.addEventListener
@param (string type)
@param (function callback)

crl8.EventBus.addEventListener('myEventName', myCallbackFunction);

1	crl8.EventBus.addEventListener('myEventName', myCallbackFunction);

crl8.EventBus.removeEventListener
@param (string type)
@param (function callback)

crl8.EventBus.removeEventListener('myEventName', myCallbackFunction);

1	crl8.EventBus.removeEventListener('myEventName', myCallbackFunction);

crl8.EventBus.dispatchEvent
@param (string type)
@param (various data)

crl8.EventBus.dispatchEvent('myEventName', data);

1	crl8.EventBus.dispatchEvent('myEventName', data);

Events

crl8ExperienceRenderStatus
@callback crl8ExperienceRenderStatusCallback
@param ({ experienceContainer: string, isExperienceRendered: boolean }) – Event Data

Experience event fired when experience is rendered. This allows you to programmatically adjust the display of other items on the page based on whether content is displayed in the experience. This is most commonly used to show/hide a header on the experience that is controlled by the client.

Metrics

The crl8.metrics object adds capabilities to allow you to send metric events from your Experience into the Curalate system. For more information on the functionality available, see this additional guide.

API Examples

Manually Initialize Experience

Here is an example on how the API can be used to defer auto-loading of an Experience and to set up an event listener.

// somewhere in the <body>
<div data-crl8-container-id="homepage" data-crl8-auto-init="false"></div>

// somewhere in the <body>

// in your Javascript
crl8.ready(() => {
	crl8.EventBus.addEventListener('myCustomEvent', (evtData) => doSomething(evtData));
	crl8.createExperience('homepage');
});

// in your Javascript

crl8.ready(() => {

crl8.EventBus.addEventListener('myCustomEvent', (evtData) => doSomething(evtData));

crl8.createExperience('homepage');

});

Hide Header if No Content is Displayed

Here is an example of how the API can be used to show or hide a custom heading when the experience renders. (Requires manual experience initialization).

<!-- Your Experience Container in the <body> element of the page -->
<div id="homepage-experience-header" style="display: none">#homepage | Check us out!</div>
<div data-crl8-container-id="homepage" data-crl8-auto-init="false"></div>
<script>
	(function () {
		// This is the event you want to subscribe to
		var EVENT_NAME = "crl8ExperienceRenderStatus";
    
		// This is your container name for the event your experience wants to watch
		var CONTAINER_NAME = "homepage";

		// Callback function for when event is received
		function handleExperienceStatus(eData) {
			if (eData.experienceContainer === CONTAINER_NAME && eData.isExperienceRendered) {
				// Replace with any code you want to run when experience is rendered
				document.getElementById("homepage-experience-header").style.display = "block";
			}
		}

		// Function to subscribe to event
		function subscribeToExperienceEvent() {
			window.crl8.EventBus.addEventListener(EVENT_NAME, handleExperienceStatus);
		}

		function handleSubscriptionAndExperienceInitialization() {
			if (window.crl8.EventBus) {
				// subscribe to event
				subscribeToExperienceEvent();

				// create experience
				window.crl8.createExperience(CONTAINER_NAME);
			}
		}

		if (window.crl8 && window.crl8.ready) {
			window.crl8.ready(handleSubscriptionAndExperienceInitialization);
		}
	})();
</script>

<div id="homepage-experience-header" style="display: none">#homepage | Check us out!</div>

(function () {

// This is the event you want to subscribe to

var EVENT_NAME = "crl8ExperienceRenderStatus";

// This is your container name for the event your experience wants to watch

var CONTAINER_NAME = "homepage";

// Callback function for when event is received

function handleExperienceStatus(eData) {

if (eData.experienceContainer === CONTAINER_NAME && eData.isExperienceRendered) {

// Replace with any code you want to run when experience is rendered

document.getElementById("homepage-experience-header").style.display = "block";

}

// Function to subscribe to event

function subscribeToExperienceEvent() {

window.crl8.EventBus.addEventListener(EVENT_NAME, handleExperienceStatus);

}

function handleSubscriptionAndExperienceInitialization() {

if (window.crl8.EventBus) {

// subscribe to event

subscribeToExperienceEvent();

// create experience

window.crl8.createExperience(CONTAINER_NAME);

}

if (window.crl8 && window.crl8.ready) {

window.crl8.ready(handleSubscriptionAndExperienceInitialization);

}

})();

</script>