JavaScript API

All calls go through one function, pandus(). Add this line before your first call, so calls made before the script has loaded wait in a queue:

window.pandus = window.pandus || function () { (pandus.q = pandus.q || []).push(arguments); };

Every call except consent does nothing until the visitor has agreed to analytics.

Custom events

pandus('event', 'signup', { plan: 'pro' });
pandus('event', 'newsletter_subscribe', { place: 'footer' });

• Name: snake_case, starts with a letter, up to 40 characters (a-z, 0-9, _).
• Parameters: up to 25; names up to 40 characters; values are numbers, true/false or text up to 300 characters.
• Text that looks like an e-mail, a phone or a card number is dropped in the browser and again on our server. Never put personal data into events.
• Names the SDK sends by itself, such as page_view or purchase, are listed in the event reference.

E-commerce

pandus('ecommerce', 'purchase', {
  transaction_id: 'A-1042',
  value: 89.9,
  currency: 'EUR',
  items: [{ item_id: 'kettle-1', item_name: 'Kettle', price: 89.9, quantity: 1 }],
});

ecommerce takes the GA4 recommended events; value and currency go to their own columns so revenue adds up. items holds up to 50 products. Every event and its parameters are on E-commerce.

A user id

pandus('identify', 'customer-48151');

The id joins visits of one signed-in customer across devices. The SDK hashes it with SHA-256 in the browser before it leaves the page; if you pass a SHA-256 hash already, it is used as it is. E-mail addresses and values that look personal are refused. Only with consent.

User properties

pandus('set', 'user_properties', { tier: 'gold', plan: 'b2b' });

Up to 10 properties per visitor, names up to 24 characters, text values up to 36 characters. They describe a group, never a person: no names, e-mails or ids.

Consent

pandus('consent', { analytics: true, recordings: false }); // the visitor's choice
pandus('consent', 'open');                                 // open the Pandus banner

See Consent for when to use it.

Events from your server

Orders and refunds that happen on your backend go through the server events endpoint, so a blocker in the browser does not lose them.

The npm package

@pandus/sdk wraps the same commands as typed functions. The source is MIT on GitHub; the package is on npm.

import { init, track, ecommerce } from '@pandus/sdk';

init({ site: 'YOUR_SITE_TOKEN' });
track('signup', { plan: 'pro' });

React and Next.js

// app/providers.tsx
'use client';
import { PandusProvider } from '@pandus/sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return <PandusProvider site="YOUR_SITE_TOKEN">{children}</PandusProvider>;
}

import { usePandus } from '@pandus/sdk/react';

export function SignupButton() {
  const { track } = usePandus();
  return <button onClick={() => track('signup', { plan: 'pro' })}>Sign up</button>;
}

Vue and Nuxt

// main.ts (Vue) or plugins/pandus.client.ts (Nuxt)
import { PandusPlugin } from '@pandus/sdk/vue';

app.use(PandusPlugin, { site: 'YOUR_SITE_TOKEN' });

import { usePandus } from '@pandus/sdk/vue';

const { track } = usePandus();
track('signup', { plan: 'pro' });

Content Security Policy

With a nonce-based Content Security Policy, pass the nonce with init({ site, nonce }); the loader then adds its modules itself, which 'strict-dynamic' allows. Otherwise allow:

script-src  https://pandus.online
connect-src https://pandus.online https://e.pandus.online