🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Add Node.js SDK docs back
Edward Cuie3506c40fd22
diff --git a/docs/src/content/sdks/node.mdx b/docs/src/content/sdks/node.mdxnew file mode 100644index 000000000..68826dd8d--- /dev/null+++ b/docs/src/content/sdks/node.mdx@@ -0,0 +1,164 @@+import { Callout } from "nextra/components"++# JavaScript (Node.js)++## Installation++```bash filename="npm"+npm install @rybbit/node+```++```bash filename="yarn"+yarn add @rybbit/node+```++## Initialization++### Syntax++```typescript+import { Rybbit } from "@rybbit/node";++const rybbit = new Rybbit(config: RybbitConfig);+```++### Example++```javascript+import { Rybbit } from "@rybbit/node";++const rybbit = new Rybbit({+ analyticsHost: "https://api.rybbit.io/api",+ siteId: "1",+ origin: "https://rybbit.io",+});+```++<Callout type="warning">+The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `origin`) are missing or invalid.+</Callout>++### Configuration Options++| Option | Type | Default | Description |+| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |+| `analyticsHost` | `string` | - | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |+| `siteId` | `string \| number` | - | **Required.** The Site ID for your website obtained from your Rybbit instance. |+| `origin` | `string` | - | **Required.** The domain of your website. |+| `userAgent` | `string` | `""` | A custom User-Agent string to send with tracking requests. |+| `debug` | `boolean` | `false` | If `true`, enables detailed logging to the console. |++## Tracking Pageviews++While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.++### Syntax++```typescript+await rybbit.pageview(payload?: Payload);+```++### Parameters++- **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.+ - `hostname` (`string`): The hostname associated with this pageview.+ - `pathname` (`string`): The path of the page/resource being viewed.+ - `querystring` (`string`): Any query parameters associated with the path.+ - `screenWidth` (`number`): Screen width in pixels.+ - `screenHeight` (`number`): Screen height in pixels.+ - `language` (`string`): Language code.+ - `page_title` (`string`): The title of the page or resource.+ - `referrer` (`string`): The referrer URL.++<Callout type="info">+The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.+</Callout>++### Example++```javascript+// Track a server-rendered page view+async function handleProductPageRequest(req, res) {+ // ... server logic to render product page ...++ await rybbit.pageview({+ hostname: req.hostname,+ pathname: `/products/${req.params.productId}`,+ page_title: `Product - ${product.name}`+ });++ // ... send response ...+}++// Track an API resource view+async function serveApiResource(req) {+ await rybbit.pageview({+ hostname: "api.myservice.com",+ pathname: `/v1/items/${req.params.itemId}`+ });+ // ... return API data ...+}+```++## Tracking Custom Events++Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.++### Syntax++```typescript+await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);+```++### Parameters++- **`eventName`** (`string`, Required): The name of the event you want to track.+- **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.+ - `hostname` (`string`): The hostname associated with this event.+ - `pathname` (`string`): The path or resource context for this event.+ - `querystring` (`string`): Any query parameters relevant to the event's context.+ - `screenWidth` (`number`): Screen width in pixels.+ - `screenHeight` (`number`): Screen height in pixels.+ - `language` (`string`): Language code.+ - `page_title` (`string`): The title of the page or resource context.+ - `referrer` (`string`): The referrer URL.+- **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values should ideally be strings, numbers, or booleans. Keep the structure flat.++<Callout type="info">+The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).+</Callout>++### Example++```javascript+// Track a new user registration+async function registerUser(userData) {+ // ... process user registration ...++ await rybbit.event("user_registered",+ { hostname: "auth.myservice.com", pathname: "/register" },+ { userId: newUserId, registrationMethod: "email" }+ );+}++// Track a background job completion+async function processDailyReport(reportId) {+ // ... generate report ...++ await rybbit.event("report_generated",+ {},+ { reportId: reportId, status: "success", processingTimeMs: 12345 }+ );+}++// Track an API endpoint usage with specific data+async function handleApiRequest(req) {+ // ... handle request ...+ await rybbit.event(+ "api_v1_item_lookup",+ { hostname: req.hostname, pathname: req.path },+ { itemId: req.params.itemId, clientVersion: req.headers["x-client-version"] }+ );+ // ... return response ...+}+```