Everything bluebarry shows on your store (quizzes, search, product chat and popups) runs on one small script. That script also gives your developer a JavaScript helper on the page, window.barry, to open a quiz from their own code, tell bluebarry who a visitor is or track an order. Most stores never need it. This article is for the moment you do.
Load the script
On Shopify, WooCommerce, CCV Shop and Magento, the app, plugin, module or integration already loads the script. Everywhere else, copy the Funnel script from a quiz's Launch tab and put it in the <head> of every page. In short, it does this:
<script>
window.barry = window.barry || {};
window.barry.tenantId = "YOUR_TENANT_ID";
</script>
<script async src="https://api.bluebarry.ai/sdk/YOUR_TENANT_ID/advisor.js"></script>- The script loads in the background and only pulls in the parts your store uses. See Built for a fast storefront.
- Installed twice by accident? No harm: the first copy wins.
- Call the methods below from a click handler or after the page has loaded, so the script is there when your code runs.
Open a quiz
You don't need code for a quiz button: a link to #bluebarry:QUIZ_ID opens the quiz. For your own buttons and events, use openAdvisor. The quiz ID is in the quiz link on the Implementation tab.
barry.openAdvisor("QUIZ_ID");
// Product check: ask about one product
barry.openAdvisor("QUIZ_ID", "PRODUCT_ID");
// Start over instead of resuming earlier answers
barry.openAdvisor("QUIZ_ID", undefined, { restart: true });A few hooks let your page react to the quiz:
barry.onOpened = (quiz) => { /* the quiz overlay opened */ };
barry.onResultOpened = (result) => { /* the shopper reached the results */ };
barry.onClosed = () => { /* the quiz overlay closed */ };
// Don't reopen the quiz when a shopper comes back with the back button
barry.autoOpenOnBackNavigation = false;Tell bluebarry who a visitor is
When a shopper logs in or signs up for your newsletter, pass their email. bluebarry attaches it to the visitor, so their browsing, searches and quiz answers join one customer profile. Only do this for shoppers who agreed to it.
barry.identify({ email: "[email protected]" });More in Use the Identify API.
Track an order
Shopify and WooCommerce send orders to bluebarry for you. On other platforms, call trackConversion on your order confirmation page, with the real order data:
barry.trackConversion({
conversionId: "ORDER-12345",
currencyIso: "EUR",
orderProductTotal: 250.00,
orderTaxTotal: 62.50,
orderGrandTotal: 312.50,
items: [
{ itemId: "SKU-001", quantity: 2, priceExclTax: 100.00, priceInclTax: 125.00, taxPercentage: 25 },
],
});bluebarry links the order to the quiz the shopper took, even if that was days ago. Without the main script on your confirmation page, use the ready-made script from Implementing the performance tracking script.
Open search
Once search is live, it attaches to your store's search box by itself. Use these when you have your own search button, or want the full results page on a page of your own:
barry.openSearch();
barry.closeSearch();<!-- On your search results page -->
<div data-bluebarry-serp></div>See Launch search on your store for the setup snippet.
Product chat
Open or close the chat from your own button, or give it a fixed spot on the page:
barry.openChat();
barry.closeChat();
// Is the chat available on this page? "ready", "disabled", "error" or "missing_target"
barry.chatStatus?.state;<!-- Where the embedded chat should appear, for example above the product grid -->
<div data-bluebarry-product-chat-embed></div>On a store that changes pages without reloading, tell the chat where the shopper is now with barry.updateChat(...). See Install product chat on your store.
Popups
Popups with a trigger open by themselves, no code needed. To open one from your own button or link, use its ID from the popup editor:
barry.openPopup("POPUP_ID");
barry.closePopup();
// On stores that don't reload between pages: say what the shopper is looking at
barry.setPopupContext({ productId: "PRODUCT_ID", cartState: "nonempty" });More in Create a popup.
Add to cart
The quiz, search and chat all add to the cart through the same helper. You can use it too, on Shopify, WooCommerce, CCV Shop and Magento:
const result = await barry.cart.add([{ reference: "VARIANT_ID", quantity: 1 }]);
// { success: true, skipped: [] }, or failure: "soldOut" | "error"
barry.cart.reveal(); // open the cart drawer, or go to the cart pageThe reference is what your store's cart expects: on Shopify the variant ID, on CCV Shop and Magento the product ID (on Magento the ID of a configurable product's variant, not of the product itself).
Listen to events
bluebarry announces a few moments on the page, so your own scripts (or your analytics) can respond:
document.addEventListener("barry:cart:added", (e) => {
console.log("Added to cart", e.detail.items);
});
document.addEventListener("barry:chat:status", (e) => { /* e.detail.state */ });
document.addEventListener("barry:chat:product-click", (e) => { /* e.detail is the product */ });barry:cart:added fires for every add from any bluebarry feature, so one listener covers them all.
How bluebarry recognises a visitor
The script sets one first-party cookie, bb_uid, on your own domain. It holds a random visitor ID and lasts two years. Because it sits on your main domain, it is shared by every feature and every subdomain: a quiz on quiz.yourstore.com and search on yourstore.com see the same visitor. That is how quiz answers, searches, popup sign-ups, chats and orders end up in one profile.
- After a quiz, two more cookies (
bb_sessionandbb_advisor) remember that quiz for 30 days, so a later order can still be credited to it. barry.getUid()returns the visitor ID, if you want to match it in your own systems.- Without cookies, everything still works for the shopper: quizzes, search, chat and popups behave as usual. What you lose is the connection between visits. Each page view counts as a new visitor, so answers and searches don't build up a profile and orders can't be traced back to a quiz.