---
name: trakiie-setup
description: Set up Trakiie analytics in this project: tracking script, goals, AI crawler logging and payment attribution (Stripe, Dodo, Lemon Squeezy, Polar, Paddle). Use when the person asks to set up https://trakiie.tamilini92.workers.dev or Trakiie here.
---

# Set up Trakiie in this project

## 1. Read the app first

- The person said "Set up https://trakiie.tamilini92.workers.dev in this project". https://trakiie.tamilini92.workers.dev is this analytics service, not the app to track.
- Find the framework, package manager, shared layout or page head, hosting (Cloudflare Workers, Vercel or Next.js, or other), existing analytics, and the checkout or payment code.
- Find the app's own domain from its canonical URL, deploy config or package homepage. If it's missing or unclear, ask. Never invent one.

## 2. Sign in and create the site

- From the repository root run `npx trakiie@latest start <app-domain>` (Node 18 or newer).
- It prints a code and a link. Ask the person to open the link and approve, and keep the command running until it finishes.
- If it says the account has no plan, give the person the billing link it printed and wait for them. Never pick or buy a plan yourself.
- It writes `.trakiie.json` (the site id, safe to commit), adds `TRAKIIE_CRAWL_KEY` to `.env`, makes sure `.env` is git-ignored, and installs this file as `.claude/skills/trakiie-setup/SKILL.md`. If you are reading it there, carry on: you are the agent it's meant for.

## 3. Add the tracking script

- Add it once, in the shared layout or page head: `<script defer src="https://trakiie.tamilini92.workers.dev/t.js" data-site="SITE_ID"></script>`, with SITE_ID from `.trakiie.json`.
- Keep existing analytics. Don't add the script twice, and don't load it inside iframes.

## 4. Track a few real goals

- Pick 2 to 4 outcomes that exist in the code, like a signup, a trial start or a key action. Explain the choice in one line each.
- After the action succeeds, call `window.trakiie?.("signup")`, or add `data-goal="signup"` to the button. Extra fields go as `data-goal-plan="pro"` or a second argument.
- No emails, names or other personal data in goal fields.

## 5. Log AI readers on the server

- Cloudflare Workers: run `npx trakiie@latest snippet cloudflare` and add it to the fetch handler after the response is ready. Next.js: run `npx trakiie@latest snippet next` and merge it into `middleware.js` (keep any existing middleware logic).
- Read the key from the environment (`env.TRAKIIE_CRAWL_KEY` or `process.env.TRAKIIE_CRAWL_KEY`) instead of pasting it into code. The person sets it on their host; tell them the exact command, like `npx wrangler secret put TRAKIIE_CRAWL_KEY`.
- The snippet only reports AI bots in the background. Never block or slow a bot. Other hosting: skip this step and say so in the handoff.

## 6. Connect payments

- Supported: Stripe, Dodo Payments, Lemon Squeezy, Polar and Paddle. Find which one the checkout code uses.
- Where the checkout is created, pass the browser's `trakiie.visitor()` value through to the server and attach it as `trakiie_visitor_id`: in `metadata` for Stripe, Dodo and Polar (for Stripe subscriptions also in `subscription_data.metadata`), in `checkout_data.custom` for Lemon Squeezy, and in `customData` for Paddle. A `datafast_visitor_id` that's already there works too.
- The person then adds a webhook in their provider pointing at that provider's URL from `npx trakiie@latest status`, ticks the events listed on the site's setup page, and pastes its signing secret there. You can't do this part; give them both links.
- Any other payment provider isn't supported yet. Say so instead of building a workaround.

## 7. Check that data arrives

- The tracker ignores localhost on purpose, so local runs won't show up. Run the type check and build, and test checkout only in test mode.
- After the person deploys, run `npx trakiie@latest check`. It shows events, AI reads and payments from the last 24 hours. Don't say tracking works until it shows events.
- Don't deploy unless the person asked you to.

## 8. Hand off

- Summarize: the site and dashboard link, the goals you added, the files you changed, and what is still pending (deploy, the crawler key on the host, the payment webhook).
- Never print or commit the crawler key or the CLI token.

## Commands

- `npx trakiie@latest start <domain>`: sign in, find or add the site, write the config, install this skill.
- `npx trakiie@latest snippet cloudflare|next`: the AI crawler snippet for this site.
- `npx trakiie@latest status`: the site id, dashboard link and payment webhook links.
- `npx trakiie@latest check`: what arrived in the last 24 hours.
- `npx trakiie@latest logout`: forget the token on this machine.