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
setcalls go first: attributes then count for that page's experiments. - Every command goes through
push: there's nopeekbird.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.versionshows the snippet's version once it's running.
The commands
| peekbird.push(…) | What it does | Fields |
|---|---|---|
['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
trackcalls 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, sosign_upworks whereSign upcan't. revenueandvaluetake numbers, or text that is one ('49.90'); anything else is left out.currencymust 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
nullare left out without an error. - An event with an
orderIdis 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 runsfnonce 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).
waitForworks either way. - For
set,identifyand the other commands, usewindow.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.
