### Install @umami/node Package

Source: https://github.com/umami-software/node/blob/master/README.md

Installs the Umami Node.js client package using npm. This is the first step to enable server-side tracking.

```shell
npm install @umami/node
```

--------------------------------

### Initialize and Use Umami Node Client

Source: https://github.com/umami-software/node/blob/master/README.md

Demonstrates how to initialize the Umami client with your website ID and Umami host URL. It shows how to optionally identify a session with custom attributes, track a page view with URL and title, and track a custom event with a name and associated data.

```javascript
import umami from '@umami/node';

//~ init
let umamiClient = new umami.Umami({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec', // Your website id
  hostUrl: 'https://umami.mywebsite.com' // URL to your Umami instance
  // ,userAgent // (optional) agent specifications ( OS / Browser / Device )
});

//~ (optional) identify : update with you own session attributes
const sessionId = Date.now();
const identifyOptions = {
    "attribute": "11.23",
    "sessionId": sessionId
}
await umamiClient.identify(identifyOptions);

//~ track a page
const url = `/home`;
const title = "title of /home";
let event = {url, title}
await umamiClient.track(event);
console.log(`✮ Page ${JSON.stringify(event)}`);

//~ track an event - an event has a *name*
const data = {"color": "red"};
event = {url, title, "name": "button-click", data};
await umamiClient.track(event);
console.log(`✮ Event ${JSON.stringify(event)}`);
```

--------------------------------

### Initialize Umami Client

Source: https://context7.com/umami-software/node/llms.txt

Create a new Umami client instance by providing the website ID and host URL. This configuration is required to establish communication with your Umami instance.

```typescript
import { Umami } from '@umami/node';

const client = new Umami({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec',
  hostUrl: 'https://umami.mywebsite.com',
  sessionId: 'user-session-12345',
  userAgent: 'MyApp/1.0.0 (Node.js)'
});
```

--------------------------------

### Configure Umami Client with init()

Source: https://context7.com/umami-software/node/llms.txt

Update or initialize the Umami client configuration dynamically. This method merges new settings with existing ones.

```typescript
import umami from '@umami/node';

umami.init({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec',
  hostUrl: 'https://analytics.example.com'
});

umami.init({
  sessionId: 'new-session-id'
});
```

--------------------------------

### Integrate Umami with Express.js

Source: https://context7.com/umami-software/node/llms.txt

Demonstrates how to implement Umami tracking in an Express application using middleware for automatic page views and route-specific event tracking.

```typescript
import express from 'express';
import { Umami } from '@umami/node';

const app = express();
app.use(express.json());

const analytics = new Umami({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec',
  hostUrl: 'https://cloud.umami.is'
});

app.use(async (req, res, next) => {
  try {
    await analytics.track({
      url: req.path,
      referrer: req.get('referer') || '',
      language: req.get('accept-language')?.split(',')[0] || 'en-US',
      hostname: req.hostname
    });
  } catch (error) {
    console.error('Analytics error:', error);
  }
  next();
});

app.post('/api/signup', async (req, res) => {
  const { email, plan } = req.body;
  await analytics.track('user-signup', {
    plan: plan,
    source: req.query.utm_source || 'direct'
  });
  await analytics.identify({
    email: email,
    plan: plan,
    signupDate: new Date()
  });
  res.json({ success: true });
});

app.listen(3000);
```

--------------------------------

### Method: send()

Source: https://context7.com/umami-software/node/llms.txt

Low-level method to send analytics data directly to the Umami API endpoint.

```APIDOC
## send(payload, type)

### Description
Low-level method that sends analytics data directly to the Umami API endpoint. This method is used internally by track() and identify() but can be called directly for custom integrations.

### Method
POST

### Parameters
- **payload** (Object) - Required - The data object containing website, url, title, name, or session details.
- **type** (String) - Required - The type of payload, typically 'event' or 'identify'.

### Request Example
await client.send({ website: '...', data: { key: 'value' } }, 'event');
```

--------------------------------

### Track Page Views

Source: https://context7.com/umami-software/node/llms.txt

Record page views by providing metadata such as URL, title, and other optional request details. This is essential for monitoring traffic patterns.

```typescript
await client.track({
  url: '/products/widget-123',
  title: 'Widget 123 - Product Details',
  hostname: 'www.example.com',
  language: 'en-US',
  referrer: 'https://google.com/search?q=widgets',
  screen: '1920x1080'
});
```

--------------------------------

### POST /api/send (Track)

Source: https://github.com/umami-software/node/blob/master/README.md

Sends page view or event data to the Umami analytics instance.

```APIDOC
## POST /api/send

### Description
Tracks a page view or a custom event to the configured Umami instance.

### Method
POST

### Endpoint
/api/send

### Request Body
- **url** (string) - Required - The URL of the page being tracked.
- **title** (string) - Optional - The title of the page.
- **name** (string) - Optional - The name of the custom event.
- **data** (object) - Optional - Custom properties associated with the event.
- **hostname** (string) - Optional - The hostname of the server.
- **language** (string) - Optional - The client language.
- **referrer** (string) - Optional - The page referrer.
- **screen** (string) - Optional - Screen dimensions (e.g., 1920x1080).

### Request Example
{
  "url": "/home",
  "title": "Home Page",
  "name": "button-click",
  "data": { "color": "red" }
}

### Response
#### Success Response (200)
- **status** (string) - Returns success status.
```

--------------------------------

### Method: reset()

Source: https://context7.com/umami-software/node/llms.txt

Clears all accumulated session properties from the client instance, useful for logout scenarios.

```APIDOC
## reset()

### Description
Clears all accumulated session properties from the client. Use this when a user logs out or when you need to start a fresh session without the previously identified properties.

### Method
void

### Parameters
None

### Request Example
client.reset();
```

--------------------------------

### Identify User Sessions

Source: https://context7.com/umami-software/node/llms.txt

Associate specific user properties with the current session. Properties are merged over time, allowing for detailed user segmentation.

```typescript
await client.identify({
  userId: 'user-456',
  email: 'user@example.com',
  plan: 'enterprise'
});
```

--------------------------------

### Send Custom Analytics Payloads

Source: https://context7.com/umami-software/node/llms.txt

Utilizes the low-level send method to transmit event or identify payloads directly to the Umami API. This is useful for custom integrations requiring fine-grained control over the data structure.

```typescript
import { Umami, UmamiPayload } from '@umami/node';

const client = new Umami({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec',
  hostUrl: 'https://umami.mywebsite.com'
});

const payload: UmamiPayload = {
  website: '50429a93-8479-4073-be80-d5d29c09c2ec',
  url: '/api/webhook',
  title: 'Webhook Received',
  name: 'webhook-processed',
  data: {
    source: 'stripe',
    eventType: 'payment.succeeded'
  }
};

await client.send(payload, 'event');

await client.send({
  website: '50429a93-8479-4073-be80-d5d29c09c2ec',
  session: 'session-xyz',
  data: { tier: 'premium' }
}, 'identify');
```

--------------------------------

### Track Custom Events

Source: https://context7.com/umami-software/node/llms.txt

Log custom user interactions or application events. You can pass a simple event name or a detailed payload object to capture specific data points.

```typescript
await client.track('button-click', {
  color: 'red',
  position: 'header',
  timestamp: Date.now()
});
```

--------------------------------

### POST /api/send (Identify)

Source: https://github.com/umami-software/node/blob/master/README.md

Updates session attributes for a specific user session.

```APIDOC
## POST /api/send (Identify)

### Description
Associates custom attributes with a specific session ID.

### Method
POST

### Endpoint
/api/send

### Request Body
- **sessionId** (string) - Required - The unique identifier for the session.
- **attribute** (string) - Required - The attribute value to associate with the session.

### Request Example
{
  "sessionId": "1715678901234",
  "attribute": "11.23"
}

### Response
#### Success Response (200)
- **status** (string) - Returns success status.
```

--------------------------------

### Reset Session Properties in Umami Node

Source: https://context7.com/umami-software/node/llms.txt

Clears all accumulated session properties from the Umami client. This is essential for handling user logouts or initiating a fresh session state.

```typescript
import { Umami } from '@umami/node';

const client = new Umami({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec',
  hostUrl: 'https://umami.mywebsite.com'
});

await client.identify({
  userId: 'user-123',
  role: 'admin'
});

client.reset();

await client.identify({
  userId: 'user-456',
  role: 'viewer'
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.