Projects and write keys

A project is one website or one browser extension. Each has its own write key, its own reports and its own limits. An extension and the site that sells it are two projects, usually in the same account.

Creating a project

From Projects, choose New project, give it a name and say whether it is a website or a browser extension. The choice decides the words the reports use, visitors or users, and whether installs and uninstalls are counted. It needs the Write role.

The project opens on its Setup screen, which shows the write key and the install steps for that kind of project. Until the first event arrives, the Overview points you back to them.

The write key

The write key, which starts wk_, is how the SDK says which project an event belongs to. It is public by design: it ships inside your extension or your page, where anyone can read it. It only lets a browser send events to that one project. It cannot read anything back, and it opens nothing in your account.

Copy it from Setup or Settings into the SDK's init. See the install guides for Chrome, Firefox and websites.

Limit which sites can send events

Because the write key is public, someone can copy your snippet onto their own site, and their visitors then count as yours. Each project can list who may send it events. Open the project's Settings and fill in Allowed domains.

• A website lists hostnames, one per line. example.com allows that host, on any port and over http or https. *.example.com allows its subdomains, but not example.com itself, so list both when you use both. localhost can be listed for testing.
• An extension lists its IDs: the 32 letters in its Chrome Web Store or Edge Add-ons address. One extension has a different ID in each store, so list both.
• Firefox and Safari give an extension a new address on every install, so no ID can be listed for them. Accept events from Firefox and Safari is on by default. It lets in any Firefox or Safari extension, not only yours.

An empty list accepts events from anywhere, which is how every project starts. Events from anywhere else are turned away and nothing of them is stored. The collector answers filtered: "origin", so the SDK does not retry.

Settings also lists where events came from in the last 30 days, with how many were accepted and how many were turned away, and an Allow button beside each. When events arrive from more than one domain, or are turned away, the overview says so.

What it cannot do. This stops your snippet being reused on someone else's site, and stray traffic from copies of your extension. It cannot stop someone who sends events from a script, because a script can claim to come from any domain.

Sending from a server. A request made outside a browser carries no origin. Once a project has a list, such requests are turned away, so a project that also receives events from a server should keep its list empty.

Rotating the key

Rotate the key under Settings if it is being used to send junk to your project. The new key works at once and the old one stops being accepted at once, so every installed copy that still has the old key goes quiet until it is updated. For an extension, that means until your users install a release with the new key. The screen asks you to confirm for that reason.

Rotating needs the Write role.

Deleting a project

Under Settings, an admin can delete a project by typing its name. Its events, its daily totals and its write key go with it. It cannot be undone.

How long data is kept

Individual events are kept for 90 days and then deleted. Daily totals and active-user counts are kept indefinitely, so the reports' history survives after the detail ages out. The limits page lists the rest.