SDKs
How your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.
An SDK is the small piece of Sypnia that lives inside your app. It notices what happens (an error, a slow page, a click that does nothing) and sends it to Sypnia as events.
The SDKs are open source under the MIT licence and are the same for the open-source engine and for Sypnia Cloud. Two things differ, and every page shows both:
| Sypnia Cloud | Self-hosted engine | |
|---|---|---|
| Where the SDK sends | https://ingest.sypnia.com, the default. You set nothing. | Your engine’s base URL, in the option endpoint. |
| Where the key comes from | Your project’s page in app.sypnia.com. | sypnia project create, or the API. |
npm
npm install @sypnia/browserimport { init } from '@sypnia/browser';
init({ project: 'YOUR_PROJECT_KEY' });pnpm
pnpm add @sypnia/browserimport { init } from '@sypnia/browser';
init({ project: 'YOUR_PROJECT_KEY' });yarn
yarn add @sypnia/browserimport { init } from '@sypnia/browser';
init({ project: 'YOUR_PROJECT_KEY' });bun
bun add @sypnia/browserimport { init } from '@sypnia/browser';
init({ project: 'YOUR_PROJECT_KEY' });script tag
<script async
src="https://ingest.sypnia.com/v1/sdk.js"
data-project="YOUR_PROJECT_KEY"></script>No build step and no init call: paste it before </head>. The tag starts Sypnia with the key in data-project.
Which one you need
| Your app | Use | Status |
|---|---|---|
| Anything that runs in a browser: React, Vue, Svelte, plain HTML, an app made with an AI builder | @sypnia/browser | At launch |
| A Next.js app | @sypnia/next, which covers the browser and the server | At launch |
| A Node server: Express, Fastify, Koa, NestJS, Hono | @sypnia/node | At launch |
| A backend in Python, Go, PHP, Rust, Java or anything else | OpenTelemetry: point your OTLP exporter at Sypnia | At launch |
| A mobile app built as a web view | @sypnia/browser | At launch |
| A native iOS or Android app | Native SDKs are planned. See Planned. | Planned |
A web app with its own backend uses two: the browser SDK in the page and a server SDK (or OpenTelemetry) in the backend, both sending to the same project. That is what lets Sypnia follow one click from the page to the database.
The whole public API
Three packages, a handful of functions.
| Function | @sypnia/browser | @sypnia/node | What it does |
|---|---|---|---|
init(options) | yes | yes | Starts the SDK. Once. |
identify(who) | yes | yes | Says who the person is, and their account. |
reportError(error) | yes | yes | Reports an error your code caught. |
track(name, props) | yes | no | Sends a custom event. |
flush() | yes | yes | Sends what is waiting. |
getSessionId() | yes | no | The current session’s id. |
optOut(), optIn() | yes | no | Stops and resumes everything for one browser. |
span(name, fn) | no | yes | Records a step of your own inside a request. |
shutdown() | no | yes | Sends what is waiting and stops. |
wrapFetchHandler(handler) | no | yes | Traces a function from a Request to a Response. |
@sypnia/next gives you the browser functions from @sypnia/next/client, the server functions from @sypnia/next/server, and withSypnia for next.config.ts.
Pages in this section
- Install, every option, what is captured without code.
- Requests, outgoing calls and errors of a Node server.
- One setup for the client and the server, and source maps at build.
- Any other backend, through OTLP/HTTP.
- The defaults, and how to mask more.
- Persons, accounts and anonymous sessions.
- Which sessions are recorded, and what happens at a limit.
- Nothing arrives, ad blockers, source maps, duplicate sessions.
The exact shape of everything the SDKs send is the event schema.