# teia — prompts prontos / ready-made prompts

Cole um destes prompts no seu agente de código (Claude Code, Cursor, Codex…) dentro do repositório
do seu site ou app. / Paste one of these into your coding agent, inside your site's or app's repo.

Antes / before: ask us (contact@loco.ltd) for your **site key** and **placement keys** — we create
them when we approve your site. API reference: https://api.useteia.com/openapi.json

---

## 1. Website: add the teia tag

```text
Add teia ads to this website.

- Site key: <SITE_KEY>. Placements and their sizes per breakpoint (mobile <768px, tablet <1024px,
  desktop ≥1024px): <PLACEMENT_KEY: e.g. rail 300x600 desktop only; footer 728x90 desktop, 320x100 mobile>.
- Load the tag once per page, async, at the end of <head>:
  <script async src="https://px.useteia.com/t.js" data-site="<SITE_KEY>"></script>
  (If the site runs behind our Cloudflare Worker proxy, use src="/_t/t.js" instead.)
- Where each spot goes, add <div data-teia="<PLACEMENT_KEY>"></div>.
- Reserve each slot's size in CSS so nothing shifts: min-height = slot height + 20px (the disclosure
  line), max-width = slot width, width 100%, per breakpoint.
- Single-page apps: call window.teia?.refresh() after each route change.
- Never use "ad", "ads", "banner" or "sponsor" in file names, CSS classes, ids or data attributes
  (ad blockers hide them). Name things "spot" or "teia".
- Don't add cookies or consent banners for this: teia sets no cookies and stores nothing in the browser.
Show me the diff and where each placement ended up.
```

## 2. App or game: use the JSON API

```text
Integrate teia's JSON API in this app to fill the placement <PLACEMENT_KEY> of site <SITE_KEY>.
The OpenAPI spec is at https://api.useteia.com/openapi.json — read it first.

- On the screen that shows the spot, POST https://px.useteia.com/v1/serve with
  { "site": "<SITE_KEY>", "pv": <random id per screen view, never persisted>,
    "slots": [{ "id": "0", "placement": "<PLACEMENT_KEY>", "bp": "mobile" }],
    "page": { "lang": <the UI language, e.g. "pt-BR"> }, "ctx": { <optional key-values, e.g. "place": "beach"> } }.
  ctx: at most 20 keys (letters, digits, "-" and "_"); values are strings (up to 100 characters),
  numbers or booleans. Send only what describes the screen, never anything about the player.
- Send a User-Agent that names the app, e.g. "<AppName>/1.2 (Android 14)". Generic ones such as
  "okhttp/4.12.0" are counted as bots.
- Render slots[0].items[0] and always show `disclosure` with it: an image item has `img`/`img2x`
  at `w`×`h`, a text item `title`/`body`/`cta`. On a pixel-art placement every item has `pixel`
  instead: a PNG at exactly `w`×`h`, to draw at an integer scale with nearest-neighbour filtering.
  If `items` is empty and `advertise` is present, you may show a small "advertise here" card
  linking to `advertise.href`; otherwise show nothing.
- Resolve every `href` (and image URL) against https://px.useteia.com/ and open `href` in the system
  browser on tap: the server counts the click and redirects.
- Report events with POST https://px.useteia.com/v1/e and body { "e": [{ "o": <item.offer>, "t": "render" }] }
  when shown, and { "t": "viewable", "ttv": <ms since shown> } once at least half of it has been
  visible for 1 second. Send each once per item, fire and forget; never block the UI on it.
Keep it in one small module with a test that mocks both endpoints.
```

## 3. Cloudflare Worker: first-party proxy (optional, recommended)

```text
In this Cloudflare Worker, proxy /_t/* to https://px.useteia.com so teia's tag, serving and clicks are
first-party. Before serving static assets:

- target = new URL(pathname.slice(3) + search, "https://px.useteia.com") ("/_t/v1/serve" → "/v1/serve").
- Copy the request headers, delete "cookie" and "host", and set:
  x-teia-edge: env.TEIA_EDGE_SECRET (a secret we give you; add it with `wrangler secret put TEIA_EDGE_SECRET`),
  x-teia-ip: the cf-connecting-ip header, x-teia-country / x-teia-region / x-teia-asn from request.cf.
- fetch(target, { method, headers, body (not for GET/HEAD), redirect: "manual" }) so click redirects
  reach the browser unchanged; strip any set-cookie from the response.
Then change the tag's src to /_t/t.js. Add a test for the path rewrite and the header handling.
```