Web pages

A script tag that tracks page views and clicks, and a feedback button, with no build step.

Anything in a web page can be read by the people who open it, so use a public key here. A public key can only add events, and can be limited to the channels a page needs. See Keys.

The script

<script async src="https://api.snekot.co/snekot.js"></script>
<script>
  window.snekotq = window.snekotq || [];
  window.snekot = window.snekot || ((...args) => window.snekotq.push(args));
  window.snekot('setConfig', 'YOUR_PUBLIC_KEY', 'your-project');
</script>

Calls made before the script has loaded wait in a queue and run in order when it arrives. The script’s source is public, at github.com/snekot-co/snekot-browser, so you can read what runs on your pages.

Command
snekot('setConfig', key, project, options) Required once. The options are described below: remember, outbound, downloads, channel and endpoint.
snekot('setUserId', id) Who is signed in. Pass null when they sign out. Remembered in the browser.
snekot('clearUserId') The same as setUserId(null).
snekot('track', { channel, event, … }) Posts an event, with the same fields as the API.
snekot('identify', { properties }) Sets properties on the signed-in user.
snekot('experiment', name, variants, callback) Which variant of an A/B test this visitor gets.
snekot('subscribe', email, properties) Puts an address on the project’s newsletter list.
snekot('remember', true) Keeps a visitor id on the device from now on; false stops and removes it. See below.
snekot('setDebug', true) Logs what would be sent to the console, and sends nothing. The console says so once: [snekot] debug is on: nothing is sent to Snekot.

Page views

Each page view is recorded: on load, and when the address changes without a load, as it does in a single-page app. A visitor nobody has named is counted too, with no id and nothing kept in the browser. Once a user id is set, their page views are tied to them.

A visitor who arrives through a link page link with Carry the visitor over turned on has a visitor id in the address. The script keeps it, takes it out of the address, and uses it until setUserId names the person, at which point everything they did as a visitor is joined to them.

Clicks, without code

Give an element a data-event and a click on it posts that event:

<button data-event="Upgrade clicked" data-channel="billing" data-icon=":moneybag:" data-tag-plan="Pro">
  Upgrade
</button>
Attribute
data-event Required. The event’s name.
data-channel The channel. events if left out.
data-icon An emoji or a shortcode.
data-description The description.
data-user-id Overrides the signed-in user for this element.
data-tag-<name> A tag. data-tag-plan="Pro" sends the tag plan.

A <form> with data-event posts on submit, and adds each filled-in field as a tag. Password fields are left out, and so are card fields and any field whose name contains pass, secret, token, csrf, card, cvc, cvv, ssn or iban.

A signup form, without code

A <form> with data-snekot-subscribe and an email field sends the address to the project’s list of subscribers when it is submitted. See Newsletter signups.

<form data-snekot-subscribe>
  <input type="email" name="email" required>
  <button>Subscribe</button>
</form>

The script can record two more kinds of click by itself. Both are off until you ask for them:

<script>
  window.snekot('setConfig', 'YOUR_PUBLIC_KEY', 'your-project', { outbound: true, downloads: true });
</script>
Option Records As
outbound: true A click on a link to another site. Outbound link clicked, with the tags host, url and page.
downloads: true A click on a link to a file, or on a link with a download attribute. File downloaded, with the tags file, type, host and page.
channel: 'web' The channel both are posted to. web unless you name another.

The visitor is not held back: the event is sent as the click happens, in a request the browser finishes after the page has gone. A click with the middle button, which opens a new tab, counts too. url is the address without its query string, and page is the page the link was on.

A file is a link whose address ends in one of: pdf, zip, gz, tar, rar, 7z, dmg, pkg, exe, msi, apk, deb, rpm, iso, csv, xls, xlsx, doc, docx, ppt, pptx, txt, rtf, epub, mp3, wav, mp4, mov, avi, mkv.

These are events like any other: they show in the feed, can be charted and used as funnel steps, and count against the month. Views has a panel for each. If your public key is limited to some channels, add the channel these are posted to.

Remembering visitors

By default the script keeps nothing on a visitor’s device. Visitors are told apart for one day, so the same person tomorrow, or on another network, counts as someone new.

To follow a visitor for longer, ask the script to remember them. It then makes up a random id, keeps it in the browser’s local storage, and sends it with every page view and event:

<script>
  window.snekot('setConfig', 'YOUR_PUBLIC_KEY', 'your-project', { remember: true });
</script>

Keeping an id on someone’s device is the kind of thing a site usually has to ask its visitors about first; that decision is yours for your site. If you ask, leave remember out of setConfig and call snekot('remember', true) once a visitor agrees, and snekot('remember', false) if they change their mind, which also removes the id.

The feedback button

A button that asks whether it is an issue, an idea or something else, takes a note, and posts it as an event.

<script type="module" src="https://api.snekot.co/feedback.js"></script>

<button
  data-feedback
  data-feedback-token="YOUR_PUBLIC_KEY"
  data-feedback-project="your-project"
  data-feedback-channel="feedback">
  Send feedback
</button>

The event is named Feedback Submitted, carries the note as its description and a type tag of issue, idea or other, and notifies unless data-feedback-notify="false" is set. Add data-feedback-user-id to say who sent it, and data-feedback-tag-<name> for tags of your own.

With no button of your own, EventsFeedback.init({ token, project }) adds a floating one.