API

发送统计数据

POST /api/send#

要注册一个 event，需要向 /api/send 发送 POST 请求，数据格式如下：

对于 Umami Cloud，请发送 POST 请求到 https://cloud.umami.is/api/send。

参数说明

Parameter	Type	Description
`payload.hostname`	string	主机名。
`payload.screen`	string	屏幕分辨率（例如 "1920x1080"）。
`payload.language`	string	访客语言（例如 "en-US"）。
`payload.url`	string	页面 URL。
`payload.referrer`	string	引荐来源 URL。
`payload.title`	string	页面标题。
`payload.tag`	string	额外标签描述。
`payload.id`	string	会话标识符。
`payload.website`	string	网站 ID。
`payload.name`	string	事件名称。
`payload.data`	object	（可选）事件的附加数据。
`type`	string	`event`、`identify` 或 `performance` 之一。

示例负载

{
  "payload": {
    "hostname": "your-hostname",
    "language": "en-US",
    "referrer": "",
    "screen": "1920x1080",
    "title": "dashboard",
    "url": "/",
    "website": "your-website-id",
    "name": "event-name",
    "data": {
      "foo": "bar"
    }
  },
  "type": "event"
}

注意，向 /api/send 发送请求时不需要提供认证令牌。

同时，需要发送正确的 User-Agent HTTP 头，否则请求将不会被注册。

示例响应

{
  "cache": "xxxxxxxxxxxxxxx",
  "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "visitId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

程序生成示例

你可以使用浏览器的 JavaScript API 程序生成大部分参数。例如：

const data = {
  payload: {
    hostname: window.location.hostname,
    language: navigator.language,
    referrer: document.referrer,
    screen: `${window.screen.width}x${window.screen.height}`,
    title: document.title,
    url: window.location.pathname,
    website: 'your-website-id',
    name: 'event-name',
  },
  type: 'event',
};

POST /api/batch#

要在单个请求中发送多个事件，请向 /api/batch POST 一个 JSON 数组。数组中的每个元素都与 /api/send 请求体具有相同的结构。与 /api/send 一样，此端点不需要认证令牌，但需要有效的 User-Agent 头。

示例载荷

[
  {
    "payload": {
      "hostname": "your-hostname",
      "url": "/page-1",
      "website": "your-website-id",
      "name": "event-name"
    },
    "type": "event"
  },
  {
    "payload": {
      "hostname": "your-hostname",
      "url": "/page-2",
      "website": "your-website-id",
      "name": "event-name"
    },
    "type": "event"
  }
]

每个条目都会转发到 /api/send，因此那里支持的所有 type 值和 payload 字段在这里也都支持。

示例响应

{
  "size": 2,
  "processed": 2,
  "errors": 0,
  "details": [],
  "cache": "xxxxxxxxxxxxxxx"
}

如果有任何条目失败，errors 表示失败数量，details 会列出每个失败项以及其在提交数组中的 index。

Previous认证 Next常用端点