Quick Start

Push data to Attribuly Quick Start Guide

Overview

Attribuly EventJS is a lightweight event tracking library that helps you collect user behavior data from your website. This guide will walk you through the basic installation and usage of EventJS.

Prerequisites for Custom-Built Websites

If you're using a custom-built website (not using platforms like Shopify, Shoplazza, Shopline, WooCommerce), you'll need to obtain your Attribuly pixel ID by following these steps:

Sign up for an Attribuly account at https://app.attribuly.com
Log in to your Attribuly dashboard
Navigate to the Integration section in the dashboard
Select "Custom Cart" as your platform[https://app.attribuly.com/cherry/#/select-store]
Copy your unique pixel ID from the provided code snippet
Use this pixel ID in the initialization code below

Quick Installation

Add the following code to the <head> section of your webpage:

<!-- Attribuly Event JS -->
<script>
!function(w,d,e,v,n,t,s){
    if(w.AttribulyEventQueue) return;
    n=w.AttribulyEventQueue=function(){
        n.callMethod?
        n.callMethod.apply(n,arguments):n.queue.push(Array.prototype.slice.call(arguments))
    };
    if(!w._aejs) w._aejs=n;
    n.push=n;
    n.loaded=!0;
    n.version='1.0';
    n.queue=[];
    t=d.createElement(e);
    t.async=!0;
    t.src=v;
    s=d.getElementsByTagName(e)[0];
    s.parentNode.insertBefore(t,s)
}(window,document,'script','https://app.attribuly.com/sdk/tr/1.0/attribuly-eventjs.min.js');

// Initialize event tracking
AttribulyEventQueue('init', 'YOUR-PIXEL-ID');

// Track page view event
AttribulyEventQueue('trackEvent', 'page_viewed');
</script>

Basic Usage

1. Initialization

// Basic initialization
AttribulyEventQueue('init', 'YOUR-PIXEL-ID');

2. Event Tracking

Track Simple Events

// Track simple events
AttribulyEventQueue('trackEvent', 'page_viewed');

Track Events with Data

// Track events with data
AttribulyEventQueue('trackEvent', 'product_viewed', {
    productVariant: {
        id: "123456",
        product: {
            id: "789",
            title: "Example Product",
            price: {
                amount: 99.99,
                currencyCode: "USD"
            }
        }
    }
});

Track Events with Custom Event ID (Optional)

// Track events with custom event ID
AttribulyEventQueue('trackEvent', 'product_viewed', {
    productVariant: {
        id: "123456",
        // ... other data
    }
}, {
    eventId: 'custom-event-123'  // Custom event ID
});

Supported Event Types

Event Name	Description
page_viewed	Page view event, records user page visit behavior
product_viewed	Product view event, records user product browsing behavior
collection_viewed	Collection view event, records user browsing of product categories, collections, etc.
product_added_to_cart	Add to cart event, records user adding products to cart
product_removed_from_cart	Remove from cart event, records user removing products from cart
cart_viewed	Cart view event, records user viewing cart
checkout_started	Checkout started event, records user entering checkout process
checkout_completed	Checkout completed event, records user successfully completing order
search_submitted	Search submitted event, records user performing search operations
lead_form	Lead form submission event, records user submitting marketing lead collection forms

Important Notes

The script loads asynchronously and won't block page loading
All calls made before the script loads are queued and executed automatically once loaded
All event data automatically includes device, browser, and other context information
It's recommended to track page view events at the bottom of the page to ensure more accurate page load times

Advanced Features

Custom Event IDs

By default, EventJS automatically generates a unique event ID for each event. If you need to use your own event ID system, you can specify it as follows:

Single Event with Custom Event ID

// Single event with custom event ID
AttribulyEventQueue('trackEvent', 'product_viewed', {
    productVariant: {
        id: "123456",
        // ... event data
    }
}, {
    eventId: 'my-custom-event-id-123'
});

Batch Events with Custom Event IDs

// Batch events, each with independent custom ID
AttribulyEventQueue('trackEvents', [
    {
        type: 'product_viewed',
        data: { productId: '123' },
        eventId: 'pv-custom-1'  // Custom ID for first event
    },
    {
        type: 'product_added_to_cart',
        data: { productId: '123', quantity: 1 },
        eventId: 'cart-custom-2'  // Custom ID for second event
    },
    {
        type: 'page_viewed',
        data: { pageUrl: '/products' }
        // This event doesn't specify eventId, will use auto-generated ID
    }
]);

Batch Events with Global Default Event ID

// Batch events with global default eventId, individual events can override
AttribulyEventQueue('trackEvents', [
    {
        type: 'product_viewed',
        data: { productId: '123' }
        // Uses global default eventId: 'global-default'
    },
    {
        type: 'product_added_to_cart', 
        data: { productId: '123', quantity: 1 },
        eventId: 'override-custom-id'  // Overrides global default
    }
], {
    eventId: 'global-default'  // Global default eventId
});

Implementation Best Practices

Place the script in the <head> section for optimal loading
Initialize with your unique pixel ID obtained from the Attribuly dashboard
Track page views at the bottom of the page or when the DOM is fully loaded
Use descriptive event names that clearly indicate user actions
Include relevant event data to provide context for analysis
Implement error handling for critical event tracking
Test event tracking to ensure data is being collected correctly
Respect user privacy and comply with data protection regulations

Troubleshooting

Events not appearing: Check your pixel ID and network connection
Duplicate events: Ensure events are only tracked once per user action
Performance issues: Use batch tracking for multiple events to reduce network requests
Data inconsistency: Verify event data structure matches expected format