How to embed checklists to custom elements

Product Fruits checklists have two possible display modes. The default option is using a Launcher button. This mode will add a floating button to your application that will open the checklist popup. It works without any developer needed, you just build as many checklists as you need directly in your Product Fruits administration.

If you want to embed the checklist into a custom element in your application, choose the Embedded mode. This will allow you to display the checklist as if it was a part of your application, i.e. on the dashboard.

How to embed checklists

Start with setting the particular checklist to the Embedded display mode on the first tab of the checklist page.

To insert the checklist to your selected element, call this JS API method:

const checklistId = 123456;
const yourElement = document.getElementById(....);

window.productFruits.api.checklists.injectToElement(checklistId, yourElement);

The checklistId variable can be obtained from the URL in the Product Fruits administration. When you open the checklist detail page, it is the last number in the URL.

The element must be a JS HTML DOM element instance, not a CSS selector or a jQuery method.

Checking URL filters and segmentation

By default, the injectToElement method doesn't check if the checklist matches all display rules. No matter what URL filters and/or segmentation is set, the checklist will be injected. If you want to avoid this, you have two options:

A. You can pass an options object like this:

window.productFruits.api.checklists.injectToElement(checklistId, yourElement, { checkEligibility: true });

The checkEligibility option will check all display rules and injects the checklist only if the checklist is eligible to be injected.

B. If you want to read the current state, use the isChecklistEligible(id) method. It returns a promise:

// isChecklistEligible returns a promise. You can use await in async functions or then() to get the result
if (await productFruits.api.checklists.isChecklistEligible(checklistId, yourElement) == 'eligible') {
	productFruits.api.checklists.injectToElement(checklistId, yourElement);
}

Important notes

The isChecklistEligible is rate limited per given checklistId. If you call it too often, you will get a cached result that doesn't necessarily reflect the current state of the user. The current rate limit is once per 700ms, but we might change this limit without prior notification. You should optimize your code to call this method only when you're about to inject your checklist.

We don't automatically hide embedded checklists when rules change dynamically.

Listen when the checklist is dismissed or completed

window.productFruits.api.checklists.listen('dismissed', (checklistId) => {
	console.log('The checklist was dismissed by the user.');
});