# 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.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/sdks/

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**

```bash
npm install @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**pnpm**

```bash
pnpm add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**yarn**

```bash
yarn add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**bun**

```bash
bun add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**script tag**

```html
<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`](https://docs.sypnia.com/sdks/browser)                                       | **\[At launch]** |
| A Next.js app                                                                                   | [`@sypnia/next`](https://docs.sypnia.com/sdks/nextjs), which covers the browser and the server  | **\[At launch]** |
| A Node server: Express, Fastify, Koa, NestJS, Hono                                              | [`@sypnia/node`](https://docs.sypnia.com/sdks/node)                                             | **\[At launch]** |
| A backend in Python, Go, PHP, Rust, Java or anything else                                       | [OpenTelemetry](https://docs.sypnia.com/sdks/opentelemetry): point your OTLP exporter at Sypnia | **\[At launch]** |
| A mobile app built as a web view                                                                | [`@sypnia/browser`](https://docs.sypnia.com/sdks/browser)                                       | **\[At launch]** |
| A native iOS or Android app                                                                     | Native SDKs are planned. See [Planned](https://docs.sypnia.com/reference/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

The exact shape of everything the SDKs send is the [event schema](https://docs.sypnia.com/reference/event-schema).
