216 lines
No EOL
10 KiB
Markdown
216 lines
No EOL
10 KiB
Markdown
# UmamiClient
|
|
> Note: For self-hosted instances only. For Umami Cloud, consider using the official [Umami API Client](https://github.com/umami-software/api-client/).
|
|
|
|
> Documentation generated with the assistance of ChatGPT. Please report any inaccuracies.
|
|
|
|
The `UmamiClient` is a JavaScript ~class~ library designed to simplify interaction with the [Umami Analytics API](https://umami.is/docs/api). It provides methods for user authentication, website management, session analysis, event tracking, and data retrieval. This ~client~ library streamlines the process of fetching statistics, sessions, and events from a self-hosted Umami instance for use in applications or reporting dashboards. ~The class definition resides in the `umami.js` file.~
|
|
|
|
## [FULL DOCUMENTATION](./DOCS.md)
|
|
|
|
~This is not a published library; it's a standalone class intended for direct integration into projects.~ This is now a published library. It was developed to address specific needs and provide clearer documentation compared to the existing `@umami/api-client`.
|
|
|
|
## Table of Contents
|
|
- [Key Features](#key-features-of-umamiclient)
|
|
- [Getting Started](#getting-started)
|
|
- [Authentication](#authentication)
|
|
- [User Management](#user-management)
|
|
- [Team Management](#team-management)
|
|
- [Website Management](#website-management)
|
|
- [Session Analysis](#session-analysis)
|
|
- [Event Tracking and Data Retrieval](#event-tracking-and-data-retrieval)
|
|
- [Examples](#examples)
|
|
- [Type Definitions](#type-definitions)
|
|
|
|
## Key Features of UmamiClient
|
|
|
|
### 1. Automatic Authentication and Token Management
|
|
|
|
- `authenticate()` initiates the login process and retrieves an authentication token.
|
|
- `#ensureValidToken()` (private method) automatically checks token validity before each API request and refreshes it if expired, eliminating manual token management.
|
|
|
|
### 2. Private Helper Methods for Code Consistency
|
|
|
|
- Private methods like `#makeAuthenticatedRequest()` and `#formatQueryParams()` handle common tasks:
|
|
- Making authenticated requests.
|
|
- Injecting authorization tokens into headers.
|
|
- Formatting query parameters for clean URL construction.
|
|
- This abstraction ensures consistent request structure, headers, and error handling for improved robustness.
|
|
|
|
### 3. Modular API Endpoint Coverage
|
|
|
|
- `UmamiClient` provides methods for various Umami API endpoints, grouped by functionality:
|
|
- **Authentication:** `authenticate()`, `verifyToken()`
|
|
- **User Management:** `createUser()`, `getUsers()`, `getUser()`, `updateUser()`, `deleteUser()`, `getUserWebsites()`, `getUserTeams()`
|
|
- **Team Management:** `createTeam()`, `getTeams()`, `joinTeam()`, `getTeam()`, `updateTeam()`, `deleteTeam()`, `getTeamUsers()`, `addUserToTeam()`, `getTeamUser()`, `updateTeamUserRole()`, `removeUserFromTeam()`, `getTeamWebsites()`
|
|
- **Website Management:** `getWebsites()`, `createWebsite()`, `getWebsite()`, `updateWebsite()`, `deleteWebsite()`, `resetWebsite()`
|
|
- **Session Analysis:** `getSessions()`, `getSessionStats()`, `getSession()`, `getSessionActivity()`, `getSessionProperties()`, `getSessionDataProperties()`, `getSessionDataValues()`
|
|
- **Event Tracking:** `getEventsSeries()`, `getWebsiteEvents()`, `getWebsiteStats()`, `getEventDataEvents()`, `getEventDataFields()`, `getEventDataValues()`, `getEventDataStats()`, `getPageviews()`, `getMetrics()`, `sendEvent()` , `getActiveUsers()`
|
|
- This modularity simplifies using the client for specific tasks.
|
|
|
|
|
|
### 4. Flexible Query Parameter Handling
|
|
|
|
- `#formatQueryParams()` handles a wide range of query parameters, omitting undefined values for flexibility.
|
|
- This allows precise control over filtering, pagination, and sorting without manual query string formatting.
|
|
|
|
### 5. Robust Error Handling
|
|
|
|
- `#makeAuthenticatedRequest()` and `authenticate()` include error handling, throwing descriptive errors for authentication failures or network issues to aid debugging.
|
|
|
|
### 6. Frontend Compatibility
|
|
|
|
- `sendEvent()` automatically detects frontend context (e.g., `navigator.language`, `document.referrer`) for seamless event tracking in web applications.
|
|
|
|
### 7. Typed Responses with JSDoc
|
|
|
|
- Methods return specific data structures (e.g., `Session`, `SessionStats`, `PropertyCount`) or pagination information for predictable and easy-to-use responses. These types are documented using JSDoc typedefs.
|
|
|
|
|
|
## Getting Started
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install easy-umami-js
|
|
```
|
|
|
|
### Basic Setup
|
|
|
|
#### ES6 Import
|
|
```javascript
|
|
import UmamiClient from 'easy-umami-js';
|
|
|
|
const client = new UmamiClient({
|
|
baseUrl: 'https://your-umami-instance.com', // Your Umami instance URL (no trailing slash)
|
|
username: 'your-username', // superadmin username
|
|
password: 'your-password' // superadmin password
|
|
});
|
|
```
|
|
|
|
#### CJS
|
|
```javascript
|
|
const UmamiClient = require('easy-umami-js');
|
|
|
|
const client = new UmamiClient({
|
|
baseUrl: 'https://your-umami-instance.com', // Your Umami instance URL (no trailing slash)
|
|
username: 'your-username', // superadmin username
|
|
password: 'your-password' // superadmin password
|
|
});
|
|
```
|
|
|
|
## Authentication
|
|
|
|
- **`authenticate()`**: Authenticates with the Umami API and stores the token.
|
|
- **`verifyToken()`**: Verifies the current token and returns user information.
|
|
|
|
|
|
## User Management
|
|
|
|
- **`createUser(params)`**: Creates a new user. Requires admin privileges.
|
|
- **`getUsers()`**: Retrieves all users. Requires admin privileges.
|
|
- **`getUser(userId)`**: Retrieves a specific user by ID.
|
|
- **`updateUser(userId, params)`**: Updates a user's information.
|
|
- **`deleteUser(userId)`**: Deletes a user by ID. Requires admin privileges.
|
|
- **`getUserWebsites(userId, params)`**: Retrieves websites associated with a user.
|
|
- **`getUserTeams(userId, params)`**: Retrieves teams associated with a user.
|
|
|
|
|
|
## Team Management
|
|
|
|
- **`createTeam(params)`**: Creates a new team.
|
|
- **`getTeams(params)`**: Retrieves all teams.
|
|
- **`joinTeam(params)`**: Joins a team using an access code.
|
|
- **`getTeam(teamId)`**: Retrieves a specific team by ID.
|
|
- **`updateTeam(teamId, params)`**: Updates a team's information.
|
|
- **`deleteTeam(teamId)`**: Deletes a team by ID.
|
|
- **`getTeamUsers(teamId, params)`**: Retrieves users belonging to a team.
|
|
- **`addUserToTeam(teamId, params)`**: Adds a user to a team.
|
|
- **`getTeamUser(teamId, userId)`**: Retrieves details of a user within a team.
|
|
- **`updateTeamUserRole(teamId, userId, params)`**: Updates a user's role within a team.
|
|
- **`removeUserFromTeam(teamId, userId)`**: Removes a user from a team.
|
|
- **`getTeamWebsites(teamId, params)`**: Retrieves websites associated with a team.
|
|
|
|
## Website Management
|
|
|
|
- **`getWebsites(params)`**: Retrieves all websites.
|
|
- **`createWebsite(params)`**: Creates a new website.
|
|
- **`getWebsite(websiteId)`**: Retrieves a specific website by ID.
|
|
- **`updateWebsite(websiteId, params)`**: Updates website information.
|
|
- **`deleteWebsite(websiteId)`**: Deletes a website by ID.
|
|
- **`resetWebsite(websiteId)`**: Resets all data for a website.
|
|
|
|
|
|
## Session Analysis
|
|
|
|
- **`getSessions(websiteId, params)`**: Retrieves sessions for a website within a time range.
|
|
- **`getSessionStats(websiteId, params)`**: Retrieves summarized session statistics for a website.
|
|
- **`getSession(websiteId, sessionId)`**: Retrieves a specific session by ID.
|
|
- **`getSessionActivity(websiteId, sessionId, params)`**: Retrieves activity details for a session.
|
|
- **`getSessionProperties(websiteId, sessionId)`**: Retrieves properties associated with a session.
|
|
- **`getSessionDataProperties(websiteId, params)`**: Retrieves session data counts by property name.
|
|
- **`getSessionDataValues(websiteId, params)`**: Retrieves session data counts for a given property.
|
|
|
|
|
|
## Event Tracking and Data Retrieval
|
|
|
|
- **`getActiveUsers(websiteId)`**: Gets the number of active users on a website.
|
|
- **`getEventsSeries(websiteId, params)`**: Retrieves event series data for a website.
|
|
- **`getWebsiteEvents(websiteId, params)`**: Retrieves detailed event data for a website.
|
|
- **`getWebsiteStats(websiteId, params)`**: Retrieves summarized website statistics.
|
|
- **`getEventDataEvents(websiteId, params)`**: Retrieves event data summaries (names, properties, counts).
|
|
- **`getEventDataFields(websiteId, params)`**: Retrieves event data property and value counts.
|
|
- **`getEventDataValues(websiteId, params)`**: Retrieves event data counts for a specific event and property.
|
|
- **`getEventDataStats(websiteId, params)`**: Retrieves summarized event data (events, fields, records).
|
|
- **`getPageviews(websiteId, params)`**: Retrieves pageview data for a website.
|
|
- **`getMetrics(websiteId, params)`**: Retrieves various website metrics (e.g., URLs, referrers, browsers).
|
|
- **`sendEvent(payload)`**: Sends a custom event to Umami.
|
|
|
|
|
|
## Examples
|
|
|
|
### Authentication and Session Retrieval
|
|
|
|
```javascript
|
|
async function getSessions() {
|
|
try {
|
|
const authResponse = await client.authenticate();
|
|
console.log("Authentication successful:", authResponse);
|
|
|
|
const sessions = await client.getSessions('your-website-id', {
|
|
startAt: Date.now() - 7 * 24 * 60 * 60 * 1000, // Last 7 days
|
|
endAt: Date.now()
|
|
});
|
|
console.log("Sessions:", sessions);
|
|
} catch (error) {
|
|
console.error("Error:", error);
|
|
}
|
|
}
|
|
|
|
getSessions();
|
|
```
|
|
|
|
### Sending a Custom Event
|
|
|
|
```javascript
|
|
client.sendEvent({
|
|
website: 'your-website-id',
|
|
name: 'product_view',
|
|
data: { product_id: '12345' }
|
|
});
|
|
```
|
|
|
|
|
|
## Type Definitions
|
|
|
|
Refer to the JSDoc typedefs within the `umami.js` file for detailed information on the structure of objects like `User`, `GetTokenResponse`, `EventPayload`, `Session`, `SessionStats`, `SessionActivity`, `SessionProperty`, `PropertyCount`, and `PropertyValue`. These definitions provide clear documentation of the expected data structures for requests and responses. There's an documentation generated with jsdoc2md [here](./DOCS.md)
|
|
|
|
|
|
---
|
|
|
|
For complete API details and query parameter options, refer to the official [Umami Analytics API Documentation](https://umami.is/docs/api).
|
|
|
|
## TODO to v1:
|
|
- [ ] Test all the endpoints
|
|
- [ ] Add [`async-retry`](https://www.npmjs.com/package/async-retry) and add a `retries` parameter to class config and individual methods.
|
|
- [ ] Add a `timeout` parameter to class config and individual methods.
|
|
- [ ] Allow passing the `opts` type directly to class config and individual methods. |