# Quick start guide Source: /docs/quickstart # Quickstart From nothing to a verified event in about 15 minutes. You need Docker with Compose, and a page you can edit (any local HTML file served over `http://localhost` works). ## 1. Start Trace (one command) You need [Docker](https://docs.docker.com/get-docker/). Then: ```sh git clone https://github.com/trace-id/trace.git cd trace ./setup.sh # Windows PowerShell: .\setup.ps1 ``` That's all. The script creates `docker/.env` with random secrets the first time (and keeps it afterwards), starts the database, Redis, the server and the dashboard, waits until they are ready, and prints: ```text Trace is running. Dashboard: http://localhost:3000 API: http://localhost:8080 ``` The first start builds the images and takes a few minutes; later starts take seconds. Stop with `docker compose -f docker/compose.yml down`.
Ports in use?
Set `SERVER_PORT` or `DASHBOARD_PORT` in `docker/.env` and run the script again. If you change the dashboard's address, also set `DASHBOARD_URL` to exactly the URL you open in the browser.Origin not allowed?
The page's origin must match an allowed origin on the public key exactly, including the port. `file://` pages have no usable origin; serve the page over `http://localhost`.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your page. The [quick start guide](quickstart.md) gets you both in about five minutes. Using [embedded mode](embedded.md)? Your endpoint is the route you mounted, for example `https://api.yourapp.com/trace`.Do not decide in the browser
Anything the browser returns can be changed by the person using it. Use the `eventId` only as a reference and read the real result on your server.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app's URL (for example `http://localhost:5173`). The [quick start guide](quickstart.md) covers both.Show the visitor id while you build
Leave `immediate` at its default (`true`) on a test page and render `data?.visitorId`. Open the page in a private window: the id stays the same.Before you start
You need a running Trace server, a **public key** (`pk_...`) that allows your site's origin, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both. Prefer no separate server? Mount Trace inside this app with [embedded mode](embedded.md) and verify with `trace.verify()` instead.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick your thresholds. The numbers above are a starting point, not defaults.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.Before you start
You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.Already using @trace-id/sdk-vue directly?
That still works: install the plugin yourself in a `plugins/trace.client.ts` with `createIdentify(...)`. The module is the shorter path.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.Before you start
You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app (for example `http://localhost:4200`). The [quick start guide](quickstart.md) covers both.Before you start
You need a running Trace server and a **public key** (`pk_...`). The [quick start guide](quickstart.md) covers both. The SDK works in Expo Go, in development builds and in bare React Native apps with Expo modules installed. It has no config plugin and no native code of its own.Not covered yet
Cloned apps, Frida and other hooking tools, factory resets, active calls, mocked GPS and on-device VPNs need native code beyond the Expo modules. They are on the roadmap for native iOS and Android SDKs.Partly verified
The core of this SDK (the payload, the hashes and the identify call) is plain Dart and is tested against the TypeScript SDK's output. The Flutter glue that reads the device through plugins (`lib/flutter.dart`) was written without a Flutter build and has not been run on a device yet. Test it in your app before you rely on it.Before you start
You need a running Trace server and a **public key** (`pk_...`). The [quick start guide](quickstart.md) covers both. The SDK asks for no permission and has no native code of its own. Android and iOS only: it relies on 64-bit integers, which Flutter web does not have.Partly verified
The core library (the payload, the hashes and the identify call) is plain Kotlin and is tested against the TypeScript SDK's output. The Android module that reads the device and stores the token (`sdks/kotlin/android`) was written without the Android SDK and has not been built or run on a device. Test it in your app before you rely on it.Before you start
You need a running Trace server and a **public key** (`pk_...`). The [quick start guide](quickstart.md) covers both. The SDK asks for no permission.Partly verified
The core (payload, hashes and the identify call) passes its tests in CI on macOS: payload and hash parity with the TypeScript SDK, and the client against a stubbed network. The UIKit code that reads the device and stores the token in the Keychain only compiles for iOS, so CI does not build it and it is untested on a device. Try it in your app first.Before you start
You need a running Trace server and a **public key** (`pk_...`). The [quick start guide](quickstart.md) covers both. The SDK asks for no permission.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page, and a frontend that already sends an `eventId` (see [JavaScript](javascript.md), [React](react.md) or [Next.js](nextjs.md)). Node.js 18.17 or later.Thresholds are yours
Trace scores; your app decides. The 25 and 60 above are a starting point. Run in shadow mode first (log, do not block) and tune on your own traffic.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, log `event.suspectScore` and `event.reasons` instead of rejecting. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Python 3.9 or later.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, leave out `reject` and log `event["suspectScore"]` and `event["reasons"]` instead. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, leave out `reject` and log `event["suspectScore"]` and `event["reasons"]` instead. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, leave out `reject` and log `event["suspectScore"]` and `event["reasons"]` instead. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). PHP 8.1 or later.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Send it in the `x-trace-event-id` header or as `eventId` in the request body.Start in shadow mode
For the first week, leave out `reject_score` and log `$event['suspectScore']` and `$event['reasons']` instead. Look at who would have been blocked, then pick thresholds you trust.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Java 11 or later.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Go 1.21 or later.Tested in CI
Passes its tests on Ruby 3.3, against the same test vectors as the other SDKs. It has not yet been used in a production Rails app, so start the guard in shadow mode.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). Ruby 3.0 or later.Tested in CI
Builds and passes its tests on .NET 8, against the same test vectors as the other SDKs. It has not yet been used in a production app, so start the guard in shadow mode.Before you start
You need a **secret key** (`sk_...`) from the dashboard's Keys page and a frontend that sends an `eventId` (see the [Web quickstarts](javascript.md)). .NET 8 or later.Important
Configure your framework's trusted proxy setting. Trace reads the client IP from it for VPN, datacenter and cross-browser signals; behind a load balancer without it, every visitor shares the balancer's address.Before you start
Finish one Web quickstart (for example [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The code below is Node.js; every server SDK returns the same event.Roll it out safely
Ship steps 1 to 4 with logging only. After a week, check how many real users would have hit `verify-phone`, then switch the response on. Families and shared office computers are the usual false positives.Mind the false positives
Accessibility tools, some privacy extensions and corporate VPNs can trip weaker signals. Block only on strong ones (`bot`, `tlsMismatch`) and challenge on the rest.Shared computers
Libraries, internet cafes and families share machines. Treat a device match as strong evidence, not proof: send it to review, or require extra verification, before a permanent ban.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Families share
A household with phones, tablets and a laptop can pass five devices. Measure your own distribution before enforcing.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.Before you start
Finish one Web quickstart (for example [JavaScript](javascript.md) or [React](react.md)) and one Server quickstart (for example [Node.js](node.md)). The decision code below is TypeScript; every server SDK returns the same event.