Web SDKv8.21.10MIT License

JavaScript SDK

acai-js is the browser SDK for vanilla JavaScript projects. It persists events to localStorage, manages sessions, and auto-captures UTM parameters, referrer, and click IDs.

Using React, Vue, or Svelte? Consider the TypeScript Browser SDK — it has a plugin system, autocapture, and first-class TypeScript support.

Installation

Shell

npm install acai-js
# or
yarn add acai-js

Or load via async snippet — paste in your <head>:

HTML

<script>
  (function(e,t){var n=e.acai||{};window.acai=n;
  var r=t.createElement("script");r.type="text/javascript";
  r.async=true;r.src="https://cdn.acaiplatform.ai/acai-js.min.js";
  var s=t.getElementsByTagName("script")[0];s.parentNode.insertBefore(r,s);
  n._q=[];var i=["init","logEvent","setUserId","setUserProperties",
  "identify","setGroup","logRevenueV2","setOptOut","regenerateDeviceId"];
  i.forEach(function(t){n[t]=function(){n._q.push([t,arguments])}});
  })(window,document);
  acai.init("YOUR_API_KEY");
</script>

Initialise

JavaScript

import acai from 'acai-js'

acai.init('YOUR_API_KEY', 'user@example.com', {
  apiEndpoint:    'events.yourdomain.com', // collector host, no https://
  includeUtm:      true,
  includeReferrer: true,
  batchEvents:     false,
  logLevel:        'WARN',
})

Multiple named instances:

JavaScript

const instance2 = acai.getInstance('instance2')
instance2.init('OTHER_API_KEY')

Track events

JavaScript

// Simple event
acai.logEvent('Button Clicked')

// With properties
acai.logEvent('Purchase Completed', {
  product_id: 'prod_123',
  price:      49.99,
  currency:   'USD',
})

// With callback
acai.logEvent('Sign Up', { method: 'email' }, (code, body) => {
  if (code === 200) console.log('Event sent')
})

Identify users

JavaScript

// Set the authenticated user ID
acai.setUserId('user_abc123')

// Set user properties directly
acai.setUserProperties({ plan: 'pro', company: 'Acme Corp' })

// Fine-grained control with the Identify builder
const identify = new acai.Identify()
identify.set('plan', 'pro')                   // overwrite
identify.setOnce('signup_date', '2024-01-15') // write once
identify.add('login_count', 1)                // increment
identify.append('tags', 'power-user')         // append to array
identify.prepend('recent_events', 'login')
identify.unset('trial_active')               // remove property
identify.clearAll()                          // remove all user props

acai.identify(identify)

To log out a user:

JavaScript

acai.setUserId(null)
acai.regenerateDeviceId() // start a new anonymous session

Groups

JavaScript

acai.setGroup('company', 'Acme Corp')
acai.setGroup('project', ['proj_1', 'proj_2']) // multiple values

Revenue

JavaScript

const revenue = new acai.Revenue()
revenue
  .setProductId('prod_premium')
  .setPrice(99.00)
  .setQuantity(1)
  .setRevenueType('subscription')
  .setEventProperties({ coupon: 'LAUNCH20' })

acai.logRevenueV2(revenue)

Config reference

Option	Type	Default	Description
`apiEndpoint`	string	`api.acai.yourdomain.com`	Collector host (no `https://`).
`forceHttps`	boolean	`true`	Always use HTTPS for requests.
`batchEvents`	boolean	`false`	Buffer events and send in batches.
`eventUploadThreshold`	number	`30`	Batch size that triggers a flush.
`eventUploadPeriodMillis`	number	`30000`	Flush interval in ms.
`saveEvents`	boolean	`true`	Persist unsent events to `localStorage`.
`savedMaxCount`	number	`1000`	Max events saved to storage.
`sessionTimeout`	number	`1800000`	Session inactivity timeout (30 min).
`includeUtm`	boolean	`false`	Auto-capture UTM parameters.
`includeReferrer`	boolean	`false`	Auto-capture page referrer.
`includeFbclid`	boolean	`false`	Auto-capture Facebook click ID.
`includeGclid`	boolean	`false`	Auto-capture Google click ID.
`logLevel`	string	`WARN`	`DISABLE` · `ERROR` · `WARN` · `INFO`
`optOut`	boolean	`false`	Disable all tracking.
`disableCookies`	boolean	`false`	Use `localStorage` instead of cookies.
`cookieExpiration`	number	`365`	Cookie expiry in days.
`sameSiteCookie`	string	`Lax`	`Lax` · `Strict` · `None`
`transport`	string	`http`	`http` or `beacon` (sendBeacon API).
`deferInitialization`	boolean	`false`	Delay tracking until `enableTracking()` is called.
`onError`	function	—	Called when an event fails to send.