Tracker command reference

ap() is the only entry point#

The install snippet is three lines. The first creates the ap function and opens a queue for it, the second fetches the tracker file asynchronously, and the third calls init. Until the file arrives, every call is queued and then replayed in order — so you can write ap(...) anywhere on the page without worrying about timing.

The name __sov points at the same function and stays permanently for compatibility with older installs. You do not need to use it, and you do not need to remove it.

The tracker never throws into your page. An unknown command or a malformed argument is ignored silently.

The command list#

init — startup#

ap('init', { id: 'AP-XXXXXXXXXX', endpoint: 'https://collect.adpix.net' });

This is the only command that must be called, and the snippet the console generates already contains it. On its own, init:

• sends the first page_view;
• installs the History hook, so single-page apps send a page view on every URL change;
• writes cookies on the widest domain it is allowed to set, so subdomains are one visitor;
• fetches the property configuration and uses it to turn on enhanced measurement, heatmaps and the consent banner;
• attaches the automatic form-identify listener and the cross-domain linker.

A second init with the same measurement ID is a no-op; even with two copies of the tracker file on the page, only one starts.

page — a page view#

ap('page');

Takes no arguments. The URL, title and referrer are read from the page itself.

Within one page load, exactly one page view is sent per unique URL. "URL" means path plus query string; the fragment after # does not count. So if your app calls replaceState to sort a table or open a tab, no extra page view is recorded. A full page load resets the counter, so a refresh is still a new view.

In practice you almost never need to call page manually. The only real case is having turned autoPage off, or having configured enhanced measurement with page views disabled.

track — a custom event#

ap('track', 'signup_completed', { plan: 'pro', trial_days: 14 });

The first argument is the event name, and it is exactly what you will see in the Events report. The second is optional: a flat object whose every key becomes an event property.

A few notes that will save you time:

• Keep event names stable, lowercase, underscore-separated. signup_completed and SignupCompleted are counted as two different events.
• Keep values flat. A nested object is stored but is awkward to read in reports.
• If the event carries money, use the value key — that is the key read for key-event revenue.
• Never put a password, a card number, or any data you have no right to keep into properties.

ecommerce — a commerce event#

ap('ecommerce', 'add_to_cart', {
  currency: 'IRR',
  value: 2450000,
  items: [{ item_id: 'SKU-42', item_name: 'Leather bag', price: 2450000, quantity: 1 }],
});

Behaves like track, except that the items array is sent in a separate context so the e-commerce report can count products row by row. The allowed names, the fields of each item, and whether a purchase is better sent from your server or the browser are covered in E-commerce events.

identify — identifying a user#

ap('identify', 'user_8421', { email: 'ali@example.com', phone: '09121234567', plan: 'pro' });

The first argument is the user's ID in your own system. If you do not have one you can pass an empty string and send only an email or a phone number.

The second is a traits object. email and phone have special meaning: the server normalises and hashes them and uses them as deterministic keys for stitching identity. Every other key — name, company, plan, anything — is accumulated on the user.

After a successful identify, the anonymous events from before sign-in are attached to that same user.

google — Google sign-in#

google.accounts.id.initialize({
  client_id: '…',
  callback: (r) => { ap('google', r); },
});

Pass the Google Identity Services response through exactly as it is. The tracker opens the token in the browser, pulls out the email and the Google ID, and calls identify with them. If the token carries no email, nothing happens.

reset — clearing the touches#

ap('reset');

Deletes the first-touch and last-touch cookies, and nothing else. The visitor ID, the session and any recorded events are untouched.

Do not use this for "sign the user out" or "delete the user's data" — that is not what it does. Its only real use is your own test page, when you want to start attribution from scratch.

Events you do not send yourself#

Beyond these seven commands, if enhanced measurement is on for the stream, the tracker sends events like scrolls, outbound clicks, file downloads, site search, form starts and submits, and video plays on its own. Each can be turned off individually; the full list and how to configure them is in Enhanced measurement.

A user_engagement event is also sent when the page is hidden, carrying the real time spent. That number is what produces average session duration.

Rules that apply to every command#

• Consent. page, track, ecommerce, identify and automatic identification are all tied to the "statistics" category. Under opt-in, none of them run until the visitor has chosen, and the default behaviour is closed, not open.
• Opt-out. If the __sov_x cookie is set to 1 on the browser, no event is created and none is accepted.
• Batching. Events do not leave immediately; they collect in a queue and are sent together every 5 seconds, on reaching 20 events, or when the page is hidden. So do not expect a report number to move the instant after a track.
• No loss. If a send fails the batch returns to the queue, and the queue is mirrored in the browser's local storage, so closing the browser abruptly does not burn the events. The queue is bounded so a broken destination cannot grow it without limit.

Frequently asked questions#

Related#