Tracking script

The tracking script sends events from your website: product views, sign-ups, items added to a cart. It needs no setup call; the tracking key is part of its URL. This page explains how to create a key, add the script, track events and tie them to your visitors.

Before you begin

• The tracking script is included with Pro, Business and Custom plans. On Pay as you go you can’t create tracking keys, and the script’s requests return 403, also with keys created before a move to Pay as you go.
• To create tracking keys in the dashboard, you need the Admin role in the workspace. With the API, use a key with Full Access.
• You need to be able to edit your site’s HTML, or add a custom HTML tag in your tag manager.

Create a tracking key

Tracking keys are public: they go into your web pages, so anyone can read them. They can only send workspace and custom events, never read data, and you can limit them to your own sites.

curl -X POST https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Online shop", "allowed_origins": ["https://shop.example.com"] }'

Add the script

Paste both tags into every page, ideally before </head>, with your key in place of TRACKING_KEY:

<script>window.emailit=window.emailit||function(){(window._emailitq=window._emailitq||[]).push(arguments)};</script>
<script async src="https://js.emailit.com/track/TRACKING_KEY/events.js"></script>

The first tag queues calls made before the script loads, so you can call emailit(...) right away. The script loads asynchronously, never throws into your page and also works from a tag manager.

• If the Emailit forms script is on the page too, keep both. They share window.emailit.
• If your site uses a Content Security Policy, allow https://js.emailit.com in script-src and connect-src.

Track events

// Custom event: any name after "c:", any properties
emailit("track", "c:product.viewed", { sku: "TS-42", price: 19.9 });

// Workspace event: checked against its definition
emailit("track", "w:customer.type", { segment: "b2b" });

The type must start with c: or w:; the script ignores other calls. Properties that aren’t an object are sent as {}. You can pass a third argument with occurred_at, an ISO 8601 date-time, for events that happened earlier.

The script doesn’t record page views by itself. Track the pages and actions you care about, for example a c:page.viewed event on each route change of a single-page app.

Shop commands

For online shops, the script also has product, cart, purchase and page commands. They record product views, carts and orders for Commerce and send them to the event log as the system events product.viewed, cart.updated and order.placed. Commerce is in alpha and open to the Emailit team only; elsewhere these commands are rejected. See Connect your shop.

Identify visitors

Once you know who the visitor is, for example after they sign in or subscribe, tell the script:

emailit("identify", { email: "jane@example.com" });
// or, if you store Emailit contact IDs:
emailit("identify", { contact_id: "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9" });

Every later event carries that email or contact ID, on this page and on later visits, so Emailit can tie it to the contact. When the visitor signs out, forget them:

emailit("reset");

reset also starts a new anonymous visitor ID, so the next person on a shared computer isn’t mixed up with the last one.

Events with an email that no contact has are kept, and they show on the contact once it exists. A contact_id that doesn’t match a contact is dropped from the event, without an error, so a public key can’t be used to test which contact IDs exist.

Anyone with your tracking key can call identify with any address, so Emailit doesn’t let the script’s events drive automations. They’re recorded, show on the contact and reach webhooks, but don’t start, end or advance automation runs. Send events that should do that from your server with the Events API. Each event from the script that names a contact has identity_verified: it’s true only when a signed link in one of your emails identified the visitor, which is part of the Commerce alpha, and those events do drive automations.

What the script sends

Each event carries, besides your type and properties:

Emailit adds identity_verified to events that name a contact (see Identify visitors) and stores the browser’s user agent. It doesn’t store IP addresses, and the script sets no cookies. It keeps the visitor ID under emailit:aid and the identity under emailit:identity in local storage; if local storage is blocked, they last only for the page.

Events are collected for a moment and sent together, at most 20 at a time. When the visitor leaves the page, the rest are sent with sendBeacon.

If you need consent for analytics on your site, load the script only after the visitor agrees.

Allowed sites

allowed_origins limits which sites can send events with a key. Each entry is one of:

An empty list accepts any site. Emailit checks the Origin header that browsers send with every request, so other websites can’t send events with your key. A script outside a browser can set any header, though, so treat browser events as untrusted input and send orders and payments from your backend.

Invalid events

Unlike the API, the script’s endpoint stores the valid events of a request even when others are invalid. Invalid events are dropped, for example a w: event with a property of the wrong type, or an event of a new type once the workspace uses its plan’s number of event types. Use debug to see why.

Debug

Turn on logging in the browser console in any of these ways:

• Call emailit("debug", true).
• Add data-debug to the script tag.
• Open the page with ?emailit_debug=1 in the URL.

The console then shows each event and Emailit’s answer, including the reasons for rejected events.

Troubleshooting

Related