---
name: add-snekot
description: Add Snekot to a website or app, so its owner sees page views and events such as sign-ups, orders and errors as they happen. Use when asked to add Snekot, analytics, page views, event tracking or "tell me when someone signs up or pays" to a project, or to change which events a project sends.
---

# Add Snekot

Snekot shows a product's owner what happens in it: page views without cookies, and named events (a sign-up, an order,
a failed payment) in a live feed with charts and push notifications.

The full, current instructions are at https://snekot.co/llms.txt. Read that first if you can fetch it; what follows
is the same thing in short, for when you cannot.

## 1. Ask for what you need

The person signs up at https://app.snekot.co and creates a project. Ask them for:

- the project's slug, such as `acme-store`
- a public key (`pk_…`), for anything that runs in a browser or an app
- a private key (`sk_…`), only if you will send events from a server

Never put a private key in a web page, an app or the repository, and never print it back. Read it from an
environment variable named `SNEKOT_TOKEN`, and send nothing when it is unset, so local development and tests stay quiet.

## 2. Page views

Add this once, in the shared layout or `<head>`:

```html
<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', 'PUBLIC_KEY', 'project-slug');
</script>
```

It follows address changes in single-page apps by itself and sets no cookie. As it comes, without `remember` or `setUserId`, it keeps nothing on the visitor's device: do not add a cookie banner for it.

## 3. Events

Choose the handful the owner would want to know about. Each has a `channel` (lowercase letters, digits, dashes) and an
`event` name in plain words.

In markup, with no code:

```html
<button data-event="Upgrade clicked" data-channel="billing">Upgrade</button>
<form data-event="Contact form sent" data-channel="contact">…</form>
```

In the browser:

```js
window.snekot('track', { channel: 'signups', event: 'Signed up', icon: '👋' });
window.snekot('setUserId', 'user-123'); // on sign-in; 'clearUserId' on sign-out
```

From a server, in any language:

```bash
curl -X POST https://api.snekot.co/v1/log \
  -H "Authorization: Bearer $SNEKOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel":"orders","event":"Order placed","icon":"📦","notify":true,"user_id":"user-123","tags":{"total":49}}'
```

`notify: true` pushes to the owner's phone: use it for the few events worth an interruption.

From a server, with an SDK. The libraries are open source at https://github.com/snekot-co and install from their
repositories, not yet from npm, PyPI or crates.io, so use these exact lines:

```bash
npm install https://github.com/snekot-co/snekot-js/releases/download/0.2.0/snekot-sdk-0.2.0.tgz
pip install "snekot-events @ git+https://github.com/snekot-co/snekot-python@0.3.0"
cargo add snekot-events --git https://github.com/snekot-co/snekot-rust --tag 0.3.0
```

```ts
import { Client } from '@snekot/sdk';

const events = new Client({ token: process.env.SNEKOT_TOKEN ?? '', project: 'project-slug', disableTracking: !process.env.SNEKOT_TOKEN });
await events.track({ channel: 'orders', event: 'Order placed', icon: '📦', notify: true, user_id: 'user-123' }).catch(() => {});
```

```python
from snekot_events import Client

events = Client(token=token, project="project-slug")
events.track(channel="orders", event="Order placed", icon="📦", notify=True, user_id="user-123")
```

Swift is the package `https://github.com/snekot-co/snekot-swift` from `0.3.0`; Kotlin is two files to copy from
`https://github.com/snekot-co/snekot-kotlin`. In React, Next.js or Vue, `@snekot/sdk/react` and `@snekot/sdk/vue`
wrap the script tag, so do not add the tag as well. The calls for each are at https://snekot.co/docs/sdks.

## 4. Payments and forms: connect, do not code

If the product uses Stripe, Paddle, Polar, WooCommerce, Gumroad, Tally or Typeform, do not write code for orders,
failed payments, refunds or form submissions. Tell the person to open Setup, Connections in the app and connect the
service; it sends those events by itself. Do not also send them from code, or they are counted twice.

## 5. Check that it works

Before you say you are done, prove the call without sending anything. A dry run checks the key, project, channel
and fields, and stores nothing:

```sh
curl -X POST "https://api.snekot.co/v1/log?dry_run=1" \
  -H "Authorization: Bearer $SNEKOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"project":"project-slug","channel":"orders","event":"Order placed"}'
```

`200` with `"dry_run": true` means the real call will be accepted. A refusal's `message` says what to fix.

If nothing arrives from a browser, read the console before anything else. After `snekot('setDebug', true)` the
script sends nothing and logs each call as `[snekot] …`; without `setConfig` it warns "not configured". It does not
skip localhost by itself. A 403 naming "Allowed senders" means the project only accepts its listed sites; ask the
person to add the preview address under Setup. A sent event answers `201` with its `id` in the network tab.

Do not send made-up events to test: they land in the person's real feed and count towards their plan. If they ask
for a real one, send exactly one, call it "Setup check", and say so.

## Rules

- Send an event when the thing has really happened: after the order is saved, not when the button is pressed.
- A failed call must never break the product. Do not let it fail a request; catch its errors.
- No passwords, card numbers, or other secrets in a description or a tag. Leave out email addresses unless asked.
- When done, list the events you added and where, and ask the person to open the app and watch the first one arrive.
