Skip to content
DocsSearch the docsEnglishBack to siteOpen console

Tracker command reference

The AdPix tracker has exactly eight commands, all called through one function. This page covers what each one takes, what it sends, and when you should call it.

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#

Command Arguments What it sends
ap('init', options) options object the first page_view + starts everything
ap('page') none a page_view, if the URL is new
ap('track', name, props) event name, properties object a custom event with that name
ap('ecommerce', name, data) commerce event name, ecommerce object a commerce event + item context
ap('identify', id, traits) user ID, traits object an identify event
ap('google', response) Google sign-in response an identify event using the email inside the token
ap('reset') none sends nothing; starts a new visitor on this browser and clears the touch cookies
ap('debug', code) pairing code, or false sends nothing; pairs this tab with the Debug view

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 website 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.
Key Default Meaning
id none the data stream's tag ID, starting with AP-. If omitted it is read from the ?id= parameter on the script's own URL.
endpoint none where events are sent. Under Tag Gateway, your own domain.
autoPage true set false and init sends no page view; counting them becomes your responsibility.
autoIdentify true automatic identification from sign-in and sign-up forms. false turns it off.
Do not put an ap('page') next to init

init already sends the first page view. Writing ap('page') straight after it is ignored for that same URL — but older installs carrying that line were the root cause of the multi-counting. Take the snippet from the console and do not edit it.

A second init with the same tag 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 websites.

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.

Another customer on the same browser. When identify is called with a different user ID from the last one on this browser, the tracker first starts a new visitor, so two customers who share a computer are never counted as one person. The earlier events stay with the first customer. The user ID is kept on the browser only as a hash. The server applies the same rule to an identify that arrives without this check, for example from an older snippet or from your server.

You usually do not need to call this yourself

On form submit the tracker reads email and phone inputs and identifies automatically. Passwords and other fields are never read. If your sign-in uses an ordinary form, that is probably enough; keep identify for sign-ins that happen without a form submit, or when you want to send additional traits.

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 — a new visitor, on sign-out#

ap("reset");

Starts a new visitor on this browser: the visitor ID is replaced and the first-touch and last-touch cookies are deleted. Events already recorded are untouched.

Call it when a customer signs out, so the next person on the same browser does not continue their visit. It does not delete anyone's data; erasure is a separate request.

Events you do not send yourself#

Beyond these eight commands, if enhanced measurement is on for the data 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#

Can I call ap before the tracker file has loaded?

Yes. The first line of the snippet creates a queue, so any call made before the file arrives is queued and replayed in order. That is why you copy the snippet whole, without reordering it.

What is the difference between ap and __sov?

None. Both point at the same function. ap is the current name; __sov is the older one, kept permanently for sites running an older snippet. Both queues are drained.

Why is the event I sent missing from the report?

Three common reasons. The visitor may not have accepted the "statistics" category, an opt-out cookie may be set on the browser, or the event may still be waiting in a batch — batches flush every 5 seconds, every 20 events, and when the page is hidden.

Does ap('reset') clear everything?

No. It starts a new visitor on this browser — a new visitor ID — and clears the first-touch and last-touch cookies. Events already recorded are untouched and no one's data is deleted. Call it when a customer signs out.

Build with the APIUnderstand where revenue comes from.
Was this page helpful?