Skip to content
Peekbird

JavaScript API

Your pages talk to Peekbird through window.peekbird, one push call per command. This page lists every command and the details that trip people up; the page on each kind of data has its fields.

Calling it

window.peekbird = window.peekbird || [];
peekbird.push(['track', 'signup']);

The first line lets your call work whether or not the snippet has loaded yet: until it has, peekbird is a list that holds your calls. Once it has, peekbird is Peekbird itself and runs each call at once.

  • Calls held before the snippet loads run once it does, in order, except that set calls go first: attributes then count for that page's experiments.
  • Every command goes through push: there's no peekbird.track() on your pages. A misspelled command is ignored, without an error.
  • Always write the first line as it is. A plain window.peekbird = [] after the snippet has loaded replaces Peekbird, and later calls go nowhere.
  • In the browser console, peekbird.version shows the snippet's version once it's running.

The commands

peekbird.push(…)What it doesFields
['consent', true]The visitor agreed; false: they declined, or withdrew their consent.Consent
['consentMode', callback]Tells your consent banner what to show this visitor: callback(mode, answer).Consent
['set', { … }]Facts about the visitor, for audiences and recording filters.Visitor attributes
['track', name, { … }]An event; with revenue, an order.Other eventsPurchases
['identify', { … }]Who the visitor is.Who the visitor is
['flag', key, callback]Whether a feature flag is on for the visitor: callback(true or false).Feature flags
['variation', key, callback]The visitor's variation of an "In your code" experiment: callback(key, or null). Asking counts them in it.Experiments

Before consent

Where your site waits for consent, nothing runs until the visitor agrees, but your calls aren't lost: set, track and identify wait on the page, and run once the visitor agrees on it. The same goes while Peekbird looks up where a visitor is, to know whether to ask first.

['consent', true] is the only way to agree: a literal true. Anything else, 'true' and 1 included, counts as declining, which clears Peekbird's cookies and what it stored in the visitor's browser.

Good to know about track

  • Events are sent when your site has analytics on (the default), or when the visitor is in an experiment: given a variation of one that's running, or previewing one. Otherwise track calls are dropped, not held.
  • Any event name up to 128 characters can be tracked; longer ones are cut. Only names made of letters, digits and _ . : - can become a goal, so sign_up works where Sign up can't.
  • revenue and value take numbers, or text that is one ('49.90'); anything else is left out. currency must be three letters, and is sent in capitals; otherwise the currency is left out and the event still goes.
  • Other properties must be text, numbers or true/false. Objects, arrays and null are left out without an error.
  • An event with an orderId is stored once per site: sent again with the same name and order ID, it's left out.
  • These count once a visit, whoever sends them: begin_checkout, add_contact_info, add_address_info, add_shipping_info, add_payment_info.

Flags and variations without a callback

Once the snippet has run, peekbird.flag('key') answers true or false and peekbird.variation('key') the variation's key or null, at once. Before it has run (or before consent, where your site waits for it), they answer off and null: the push form waits for the real answer.

React

Two small hooks wrap the commands above for React components:

import { useEffect, useState } from 'react';

/** Whether a feature flag is on: false until Peekbird answers. */
export function useFlag(key) {
  const [on, setOn] = useState(false);
  useEffect(() => {
    window.peekbird = window.peekbird || [];
    window.peekbird.push(['flag', key, setOn]);
  }, [key]);
  return on;
}

/** The visitor's variation of an "In your code" experiment: null until Peekbird answers. */
export function useVariation(key) {
  const [variation, setVariation] = useState(null);
  useEffect(() => {
    window.peekbird = window.peekbird || [];
    window.peekbird.push(['variation', key, setVariation]);
  }, [key]);
  return variation;
}

A component first renders with the default (off, or no variation), then with Peekbird's answer, so a change visitors can see may flash. For what's above the fold, decide on the server instead (see Node.js SDK: Next.js middleware and server components), or render nothing until the answer arrives.

Code you write in Peekbird

Variation code and custom JavaScript goals run with a peekbird of their own, which holds helpers for that code, not the commands above.

Variation code gets peekbird.experiment and peekbird.variation (their keys, as in ?peekbird_force=experiment:variation), waitFor and track:

// Runs in the <head>, before the page's body exists.
peekbird.waitFor('.hero h1', function (h1) {
  h1.textContent = 'Free shipping on every order';
});
peekbird.track('saw_free_shipping');

// The main API, from variation code:
window.peekbird.push(['set', { saw_offer: true }]);
  • It runs as the snippet loads, in the <head>, before the page's body exists: reach elements with waitFor(selector, fn), which runs fn once for every element that matches, those already on the page and any added later.
  • It runs later where your site waits for consent (once the visitor agrees), and when the experiment's audience needs the visitor's location and Peekbird doesn't know it yet (once it does). waitFor works either way.
  • For set, identify and the other commands, use window.peekbird.push.
  • Errors in it are caught, so your page still shows, and the experiment's page lists them.

Custom JavaScript goals get convert() and waitFor(). The code runs on the goal's pages, for the visitors whose events are sent (above), and as early as variation code: reach elements with waitFor. Each convert() call counts a conversion, so call it once per conversion. Errors in it show only in the browser console, with ?peekbird_debug=1.

peekbird.waitFor('.cart-notification', function () {
  peekbird.convert();
});

An audience's JavaScript condition returns true for visitors who match. It's checked only for visitors not yet in the experiment, and one that throws an error doesn't match. More on each in Experiments and Goals and audiences.

See what your visitors see.

Start free in a few minutes: one snippet, every feature. Move to a bigger plan when you need more tracked visits.