Custobar API Documentation

Appearance

Set up site tracking ​

Are you looking into how to integrate your sites with Custobar to track customer activity and enable adding forms and call-to-actions to your web stores? This guide helps you to take the newest version of Custobar.js site tracking into use.

Are you a customer of Custobar rather than a partner? If you say yes, please contact support@custobar.com, and we will help you set this up!

Two different versions are in use ​

Currently, two different versions of the Custobar.js site tracking script are being used in Custobar. This guide refers to the newest version of site tracking, which you can find in Custobar from Campaigns - Sites.

What is new? ​

The most significant change is that Custobar's site tracking is now easier than ever to enable. Custobar's customers are responsible only for inserting the tracking code into the head of their website. Custobar's Customer Success team or customer's partner can take care of the configuration on the customer's behalf within Custobar. Of course, this option is available for the customers themselves as well.

Installing the tracking script ​

  • In Custobar, go to Campaigns - Sites.
  • On the Sites page, you can see the "Add new tracked site" button; start by pressing that.
  • To get the ball rolling, you only need to add the URL of the site to the domain field and then click on "Save" at the top of the page.
  • After saving, you will see a small pop-up window where the script is visible. You should send the script to the customer and have them place it in their site's <head> section or install it in GTM as a Custom HTML Tag or in the head section of the page.
  • Once installed, you can configure in Custobar what field to use for the Product ID, Customer ID, etc.

Configuring the tracking script ​

Once the tracking script is installed on the customer's site, you can configure how Custobar identifies customers, products, and tracks events. All configuration is done in Custobar under Campaigns - Sites - Edit tracked site. Usually the tracking script configuration is taken care of during your onboarding to Custobar, or automatically by the e-commerce platform integration. Contact support@custobar.com for assistance on configuring the tracking script.

Tracking scripts for different e-commerce platforms ​

  • Shopware 6 - follow the guide
  • Shopify - automatically installed along with the integration
  • Vilkas - automatically installed along with the integration

Site Domain ​

Enter the primary domain where the tracking script is installed (e.g., shop.example.com).

If the script needs to work across multiple domains or subdomains, add them in the Additional domains section.

Choose how Custobar handles user consent for tracking:

  • Load only with consent: Only tracks users who have accepted marketing cookies (recommended for GDPR compliance)
  • Use Cookiebot: Integrates with Cookiebot for consent management
  • Custom consent code: Write custom JavaScript to check consent

Customize Initialization ​

Track page views automatically:

  • On page load - DOMContentLoaded: Tracks automatically when the page loads
  • When script is loaded: Tracks automatically when the script is loaded
  • Never: You control when to track with custom code

Initialization code snippet: Add custom JavaScript to run when the script loads (optional).

For example a event listener:

javascript
document.addEventListener('DOMContentLoaded', function() {
  // Track button clicks
  document.querySelectorAll('.cta-button').forEach(button => {
    button.addEventListener('click', function() {
      window.custobar.push({
        type: 'CUSTOM_EVENT',
        data: { button_id: this.id }
      });
    });
  });
});

Customer Identification ​

Tell Custobar how to identify customers by adding a code snippet that returns the customer ID.

Option 1: Leave empty
Customers are identified only by cookies.

Option 2: Return customer ID from dataLayer
If you track login events in your dataLayer:

javascript
return window.dataLayer.find(
  dl => dl.event === 'login'
)?.userId;

What this does: Searches the dataLayer for a 'login' event and returns the userId from that event.

Settings:

  • ☑ Only send tracking events that include identified customer: Check this to only send events where a customer has been identified, either through the customer_id in the datalayer or through a cookie.

Product Identification ​

Tell Custobar how to identify products by adding a code snippet that returns the product_id.

Example: From product view event
If you track product views in your dataLayer:

javascript
return window.dataLayer.find(
  dl => dl.event === 'view_item'
)?.ecommerce?.items?.[0]?.item_id;

What this does: Finds the 'view_item' event in dataLayer and returns the product ID from the first item in the ecommerce object.

Settings:

  • ☑ Only send tracking events that include identified products: Check this to only track events where a product id is defined. Leave unchecked to track all pages.

Extra Page View Events ​

Track custom events that should fire automatically on every page load.

Example: Shopping Basket Add
Track when users add items to their basket by returning a JSON object with type and product_id:

javascript
const basketEvent = window.dataLayer.find(
  dl => dl.event === 'add_to_cart'
);

if (basketEvent) {
  return {
    type: 'BASKET_ADD',
    product_id: basketEvent.ecommerce?.items?.[0]?.item_id
  };
}

What this does: Finds the 'add_to_cart' event in dataLayer and returns a JSON object with type 'BASKET_ADD' and the product_id.

Additional Event Types ​

Add custom event types beyond the standard ones by clicking Add new. Examples include:

  • Video plays
  • Form submissions
  • File downloads
  • Wishlist additions

Disallow standard event types: Check this to only track your custom events and disable standard Custobar events.

Quick Code Reference ​

Common patterns for writing code snippets:

Read from HTML:

javascript
const el = document.querySelector('.sku');
return el.textContent;

Use JavaScript variable:

javascript
return window.productId;

With conditional logic:

javascript
const user = window.dataLayer.find(dl => dl.user);
if (user) {
  return user.id;
} else {
  const el = document.querySelector('.username');
  return el?.textContent;
}

Need Help? ​

For additional support or questions about advanced tracking, contact support@custobar.com.