Installa con un agente
Affida l’installazione a un agente di programmazione invece di configurarla manualmente.
Utenti Claude Code
Il plugin Vibiz include questo come skill, quindi puoi semplicemente chiedere: installa Vibiz analytics. Vedi Claude Code. Il prompt qui sotto è per tutti gli altri agent e per una sessione senza plugin.
Incollalo in Claude Code, Cursor, Codex o in qualunque coding agent con accesso al tuo repository. Sostituisci l’org id sulla prima riga con il tuo, che trovi nella schermata Intelligence. Oppure copialo da Leads > Intelligence, dove il tuo org id è già compilato.
Manda l’agent a leggere la documentazione invece di ribadirla, così non può diventare obsoleta rispetto al prodotto come succede con una checklist copiata.
Install Vibiz analytics in this repository. My org id is org_REPLACE_ME.
Read these first, they are the source of truth and they are short:
https://www.vibiz.ai/docs/analytics/install.md
https://www.vibiz.ai/docs/analytics/events.md
https://www.vibiz.ai/docs/analytics/identify.md
https://www.vibiz.ai/docs/analytics/consent.md
https://www.vibiz.ai/docs/analytics/packages.md
https://www.vibiz.ai/docs/analytics/verify.md
Then work in this order and do not skip a step:
1. Detect the framework and check whether Vibiz is already installed
(@vibiz/analytics, data-vibiz-id, sdk/v1/v.js). If init is already wired,
report what you found and continue from step 4: only add what is missing
(allowed domains reminder, identify, sign_up/login, purchase). Do not
remove a working install to start over.
2. Install @vibiz/analytics with the package manager this repo already uses
(current API uses init({ orgId }), not the old workspaceId name from 0.2.0;
install @vibiz/analytics@^0.4.1)
and call init({ orgId }) once at the app root, on the client.
3. For anything the browser cannot see, a webhook, a background job, a payment
confirmed after the tab closed, use @vibiz/analytics/node. Those calls must
carry the visitor's own url, clientIp, clientUserAgent and clientCountry, not
my server's. Capture them on the request that came from the browser and store
them with the record you will report later.
4. STOP and tell me which exact origins to allow. Do not skip this and do not
try to do it yourself: it is behind my login, and until it is done nothing
sent from a browser is kept. Give me full origins, not domains, because the
match is exact: https://www.example.com and https://example.com are
different, and so is http://. Include every host the site serves from.
5. Only after I confirm the origins, finish event instrumentation the
autocapture cannot know:
- Consent: call setConsent({ advertising: true }) when my CMP grants it, or
wire it to the consent tool already on the site. Without advertising
consent, identify contact details are never stored.
- On signup or login: identify(userId, { email, ... }) FIRST, then
track('sign_up') or track('login'). identify alone sends nothing; contacts
travel on the next track. Never put email in track props.
- purchase (and subscribe / refund) after payment is confirmed, with value,
currency and order_id.
Do not re-instrument page views, clicks, form submits, rage clicks or scroll
depth, which are already captured.
6. Verify. /api/ingest answers 204 to everything, including a wrong org id and a
disallowed origin, so a 204 proves the event was sent and nothing else. The
only proof is that the events appear in my workspace. Do not report success
from a status code.
7. Run this project's own typecheck and linter over the files you touched, and
only those. Tell me which events you instrumented and which you left to
autocapture, so nobody adds them twice later.Perché il passaggio 4 è scritto a lettere maiuscole
Ogni workspace parte con una lista di origini consentite vuota e una lista vuota non conserva nessun dato ricevuto dal browser. È deliberato: è l’unica cosa che si frappone tra il tuo workspace e chiunque legga il tuo org id dal sorgente di una pagina, e l’org id è pubblico per progettazione.
La conseguenza per un agent è che un’installazione perfettamente corretta sembra rotta.
Scrive il codice, carica una pagina, vede 204, non trova eventi e conclude di
aver commesso un errore. Lasciato a se stesso, inizierà a cambiare codice funzionante.
Dirgli di fermarsi e restituire il passaggio a te costa un solo messaggio ed elimina l’intero errore. Non devi nemmeno sapere quale origin dargli: carica una pagina con il tag installato e Intelligence indica l’origin da cui sta ricevendo, con un pulsante per consentirlo.