Tài liệu API

Xác thực

Tất cả các yêu cầu phải bao gồm token API trong header Authorization.

Authorization: Bearer YOUR_API_TOKEN

Bạn có thể tạo token API từ cài đặt dự án. Đến trang token

Nếu bạn là một tác nhân AI thay vì con người, bạn có thể lấy token mà không cần ai sao chép và dán cho bạn. Xem phần ủy quyền thiết bị

Giới hạn tốc độ & hạn ngạch

Giới hạn phụ thuộc vào gói của bạn. Giới hạn tốc độ áp dụng cho mỗi tổ chức và được dùng chung cho mọi token API; việc tạo thêm token không làm tăng giới hạn này.

Giới hạn tốc độ toàn tổ chức áp dụng cho mọi endpoint được xác thực bằng token API, bao gồm POST /v1/events, PUT /v1/users, POST /v1/ping, PUT /v1/metrics, /v1/org/charts, /v1/org/widgets, và các thao tác xóa. Mỗi lệnh gọi tiêu tốn một yêu cầu từ cùng giới hạn chia sẻ này.

/v1/device/authorize (chưa có token tại thời điểm đó) được giới hạn ở mức 10 yêu cầu mỗi giờ cho mỗi địa chỉ IP, và /v1/device/token ở mức 60 yêu cầu mỗi 5 phút cho mỗi địa chỉ IP.

Khi vượt quá giới hạn tốc độ, API trả về 429 với Too many requests. Số lượng sự kiện và số lượng hình ảnh mỗi loại có hạn ngạch hằng tháng riêng; khi đạt một trong hai, API trả về 429 với Monthly event or hosted image quota exceeded. Upgrade your plan to continue.

Header hạn ngạch

Mỗi phản hồi thành công từ POST /v1/events bao gồm các header sau:

X-Quota-Remaining: 2497
X-Image-Quota-Remaining: 18320
X-Plan: starter

• X-Quota-Remaining – số sự kiện còn lại trong tháng dương lịch hiện tại. -1 nghĩa là không giới hạn (Enterprise).
• X-Image-Quota-Remaining – hình ảnh còn lại trong tháng dương lịch hiện tại. -1 nghĩa là không giới hạn (Enterprise).
• X-Plan – gói hiện tại của tổ chức (free, starter, plus, enterprise).

Xem tất cả gói và giá

Định dạng siêu dữ liệu

Trường metadata trên sự kiện và người dùng tuân theo các quy tắc giống nhau:

• Khóa: chỉ chữ thường, chữ số, dấu gạch ngang và dấu gạch dưới (^[a-z0-9_-]+$)
• Giá trị: string, number, hoặc boolean
• Tối đa 20 khóa mỗi đối tượng
• Khóa: tối đa 100 ký tự
• Giá trị dạng chuỗi: tối đa 255 ký tự

{
  "plan": "pro",
  "amount": 49,
  "score": 4.8,
  "is-trial": false
}

Prompt bắt đầu

Dán vào Claude Code, Cursor, Codex hoặc bất kỳ tác nhân AI nào để bắt đầu ngay.

You are integrating LogsNinja into this project.

LogsNinja is a real-time event tracking and push notification platform. Use its REST API to log application events, track users, update dashboard metrics, and trigger instant push notifications to mobile and desktop devices.

LogsNinja provides no SDK – all integration is done via plain HTTP calls using the libraries and conventions already present in this project.

## Fetch the full API documentation

Before writing any integration code, fetch the complete reference in Markdown:

  curl https://logsninja.com/vi/docs -H "Accept: text/markdown"

Read it carefully – it covers all endpoints, request fields, response codes, rate limits, and examples.

## Core concepts

**Events** – send a POST to /v1/events. All fields are covered in the documentation.
**Streams** – lightweight channels grouping events. Auto-created on first use (e.g. "payments", "errors").
**Users** – PUT /v1/users to create or update a user profile. The same id is used in the user field when sending events. Optional country_code is caller-supplied (LogsNinja does not geolocate IPs itself) – see the full docs for how to obtain it.
**Metrics** – PUT /v1/metrics to create or update a numeric, text, currency, or percent dashboard tile. Supports atomic diff increments.
**Presence** – POST /v1/ping to signal a user is online without creating an event.
**Event chains** – link events sequentially with before/after fields to trace multi-step workflows.
**Charts** – POST/GET/PATCH/DELETE /v1/org/charts to manage dashboard charts. Same fields and validation rules as the dashboard's own chart editor.
**Widgets** – POST/GET/PATCH/DELETE /v1/org/widgets (plus POST /v1/org/widgets/reorder) to manage what's on the dashboard. The dashboard is a masonry layout, not a rigid grid: "small" widgets (metric, online_users) are meant for width 1 or 2 and render at exactly half the visual height of "large" widgets (chart, world_map, events_7d, top_countries), meant for width 2 or 3 (full row) – keep that in mind when arranging one via the API.

## Authentication

All requests require:

  Authorization: Bearer YOUR_API_TOKEN

Creating an account and generating a token both require a human to sign in
to the LogsNinja dashboard - you cannot do either yourself. If you don't
already have a token (e.g. in an environment variable), stop and ask the
person you're working with to create one at https://logsninja.com/vi/my/tokens
and give it to you (for example as a LOGSNINJA_API_TOKEN environment
variable) before you continue.

## API base URL

  https://api.logsninja.com/v1

## MCP server

If you are an AI agent with MCP support rather than a code-generation assistant, LogsNinja is also usable directly as an MCP server at https://logsninja.com/mcp (same Bearer token as above) – it exposes tools to manage charts and dashboard widgets, explore project data, and create/delete test events, users, and metrics, without writing HTTP calls yourself. See the full docs for the tool list.

## Integration guidelines

- Use the HTTP client and patterns already established in this project – do not introduce new dependencies.
- All LogsNinja calls must be fire-and-forget from the application's perspective: they must never block the main flow or surface errors to the end user.
- Apply a 3-second timeout to every HTTP call, if possible.
- If this project already has a job queue, background worker, or retry mechanism, use it for LogsNinja calls.
- If no such mechanism exists, wrap calls in a silent try/catch (or equivalent) so that a LogsNinja failure has zero impact on the application.

## What to instrument

Scan the codebase and identify meaningful moments to send events: key user actions, business transactions, errors, background jobs, and any other signal that would be useful to monitor. For each, choose a descriptive title and a fitting emoji. Once done, provide a summary of every integration point added.

## Presence

Use presence sparingly. Sending an event with a user field already updates that user's online status for 15 minutes, so a separate ping is redundant in those cases. Only call POST /v1/ping when you know the user is active but no event will be sent soon – for example on login, or during an idle session. Do not ping on every page view or API call.

Gửi sự kiện

Tiêu đề

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Nội dung yêu cầu

{
  "project": "YOUR_PROJECT_ID",
  "stream": "payments",
  "title": "New subscription",
  "content": "[email protected] subscribed to Pro",
  "emoji": "💳",
  "metadata": { "plan": "pro", "amount": 49 },
  "notify": true
}

Ví dụ

curl -X POST https://api.logsninja.com/v1/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "YOUR_PROJECT_ID",
    "stream": "payments",
    "title": "New subscription",
    "content": "[email protected] subscribed to Pro",
    "notify": true
  }'

await fetch('https://api.logsninja.com/v1/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project: 'YOUR_PROJECT_ID',
    stream: 'payments',
    title: 'New subscription',
    content: '[email protected] subscribed to Pro',
    notify: true,
  }),
});

import requests

requests.post(
    'https://api.logsninja.com/v1/events',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        'project': 'YOUR_PROJECT_ID',
        'stream': 'payments',
        'title': 'New subscription',
        'content': '[email protected] subscribed to Pro',
        'notify': True,
    },
)

Trường sự kiện

Tải ảnh lên

Có hai cách để đính kèm ảnh vào một sự kiện, cả hai đều dành cho gói trả phí và được xử lý theo cùng một cách, bất đồng bộ: truyền một mảng các URL HTTPS công khai trong trường JSON images để LogsNinja tải và lưu trữ, hoặc gửi chính các file trong cùng một yêu cầu POST /v1/events dưới dạng multipart/form-data.

Tải lên nhị phân (multipart/form-data)

Yêu cầu có một phần event và một hoặc nhiều phần file có tên image:

curl -X POST https://api.logsninja.com/v1/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'event={"project":"YOUR_PROJECT_ID","stream":"payments","title":"New subscription","metadata":{"plan":"pro"},"notify":true};type=application/json' \
  -F 'image=@./screenshot.png;type=image/png'

const form = new FormData();
form.append('event', JSON.stringify({
  project: 'YOUR_PROJECT_ID',
  stream: 'payments',
  title: 'New subscription',
  metadata: { plan: 'pro' },
  notify: true,
}));
form.append('image', fileOrBlob, 'screenshot.png'); // Content-Type image/png

await fetch('https://api.logsninja.com/v1/events', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }, // no Content-Type
  body: form,
});

Lỗi đồng bộ

Chúng được trả về ngay trong phản hồi POST, trước khi sự kiện được tạo:

Xem Giới hạn tần suất và hạn mức để biết số lượng ảnh theo gói, kích thước mỗi ảnh và kích thước thân yêu cầu tối đa.

Tải từ một URL

Khi bạn truyền URL thay vì file, mỗi URL phải đáp ứng tất cả các điều sau, nếu không ảnh sẽ bị đánh dấu failed:

• Chỉ HTTPS, trên cổng 443. Không có host là địa chỉ IP, không localhost, .local hoặc .internal. URL tối đa 2048 ký tự.
• Phản hồi phải mang Content-Type: image/jpeg, image/png hoặc image/webp. Một 200 trả về text/html (trang lỗi, tường đăng nhập) là lỗi vĩnh viễn – không bao giờ thử lại.
• Việc tải hết thời gian chờ sau 15 giây và theo tối đa 3 lần chuyển hướng.
• Với 403, 404, 408, 425, 429, 500, 502, 503 hoặc 504, việc tải được thử lại trong khoảng một phút trước khi ảnh bị đánh dấu failed. Mọi trạng thái khác đều thất bại vĩnh viễn ngay lần đầu.

Định dạng và xử lý

• Định dạng được chấp nhận: JPEG, PNG và WebP, được phát hiện từ các byte nhận dạng của file – không phải phần mở rộng hay kiểu khai báo.
• Mỗi ảnh được đổi cỡ để vừa với kích thước tối đa của gói và được lưu ở cả JPEG và WebP. Ảnh được giữ trong 30 ngày.
• Một sự kiện lùi ngày (timestamp) có ngày đã nằm ngoài cửa sổ 30 ngày sẽ bỏ qua hoàn toàn việc xử lý ảnh; images_status của nó là expired.

Đọc kết quả

Phản hồi POST bao gồm images_status, nhưng tại thời điểm đó nó luôn là pending (hoặc none / expired) vì việc xử lý chưa chạy. Không có webhook: hãy đọc lại sự kiện sau – bằng công cụ get_event của MCP hoặc trong nguồn cấp sự kiện của Studio – để xem kết quả.

Mỗi ảnh cũng mang một chuỗi error và một error_code (too_large, bad_format hoặc unreachable) khi bị lỗi.

Khuyến nghị: đối với một sự kiện bạn phát ngay sau khi tạo ảnh (một bản render, ảnh chụp màn hình, bản xuất), hãy tải file lên thay vì một URL. Một URL chưa thể truy cập – hoặc đã bị xóa – khi LogsNinja tải nó sẽ làm ảnh bị lỗi, và không có gì báo cho bạn khi điều đó xảy ra.

Chuỗi sự kiện

Các trường before và after liên kết các sự kiện thành một chuỗi. Bảng chi tiết sự kiện hiển thị các sự kiện liền kề và cho phép xem toàn bộ chuỗi.

Chỉ các tham chiếu đến sự kiện trong cùng một dự án mới được xử lý và chỉ khi dấu thời gian của chúng hợp lý. Mục tiêu after (tiền nhiệm) phải có dấu thời gian sớm hơn, và mục tiêu before (kế nhiệm) phải có dấu thời gian muộn hơn.

Xóa sự kiện

Xóa vĩnh viễn một sự kiện.

Tạo hoặc cập nhật người dùng

Tạo hoặc cập nhật người dùng app. Gọi với cùng id sẽ thay thế bản ghi.

{
  "project": "YOUR_PROJECT_ID",
  "id": "user_123",
  "country_code": "FR",
  "display_as": "[email protected]",
  "metadata": { "plan": "pro", "mrr": 49 }
}

Ví dụ

curl -X PUT https://api.logsninja.com/v1/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "YOUR_PROJECT_ID",
    "id": "user_123",
    "country_code": "FR",
    "metadata": { "plan": "pro" }
  }'

await fetch('https://api.logsninja.com/v1/users', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project: 'YOUR_PROJECT_ID',
    id: 'user_123',
    country_code: 'FR',
    metadata: { plan: 'pro' },
  }),
});

import requests

requests.put(
    'https://api.logsninja.com/v1/users',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        'project': 'YOUR_PROJECT_ID',
        'id': 'user_123',
        'country_code': 'FR',
        'metadata': {'plan': 'pro'},
    },
)

Định vị địa lý

LogsNinja không bao giờ tự xác định quốc gia của người dùng từ địa chỉ IP – country_code hoàn toàn do bên gọi cung cấp.

• Nếu backend của bạn đi qua Cloudflare (Workers/Pages, hoặc bản ghi DNS bật đám mây cam), hãy đọc trực tiếp header CF-IPCountry – nó đã có sẵn trên mọi request đến.
• Nguyên tắc tương tự cũng áp dụng với hầu hết các CDN/mạng biên khác (vd. Akamai, Bunny, Fastly, Amazon CloudFront) – chúng thường tự thêm một header địa lý tương đương. Hãy kiểm tra tài liệu của nhà cung cấp đó để biết tên và định dạng header chính xác.
• Nếu không, hãy dùng một thư viện hoặc dịch vụ GeoIP trên địa chỉ IP của request (vd. MaxMind GeoLite2, ipinfo.io, ip-api.com).

Truyền mã thu được vào country_code – nó cung cấp dữ liệu cho biểu đồ phân bổ theo quốc gia và widget bản đồ thế giới.

Xóa người dùng

Xóa người dùng app. Sự kiện của họ vẫn còn nhưng không còn liên kết với người dùng.

Báo hiệu sự hiện diện của người dùng

Ghi nhận người dùng đang trực tuyến, không tạo sự kiện. Người dùng được coi là trực tuyến nếu họ đã gửi ping hoặc có sự kiện liên kết trong 15 phút qua. Nếu người dùng chưa tồn tại, ping sẽ bị bỏ qua – hãy tạo người dùng trước qua PUT /v1/users.

{
  "project": "YOUR_PROJECT_ID",
  "id": "user_123"
}

Tạo hoặc cập nhật chỉ số

Tạo hoặc cập nhật một ô chỉ số. Gọi với cùng id sẽ thay thế giá trị. Với kiểu số, bạn cũng có thể áp dụng delta thay vì đặt giá trị tuyệt đối.

{
  "project": "YOUR_PROJECT_ID",
  "id": "mrr",
  "title": "MRR",
  "emoji": "💰",
  "value": 4900,
  "value_type": "currency",
  "currency": "EUR"
}

{
  "project": "YOUR_PROJECT_ID",
  "id": "active-users",
  "title": "Active users",
  "value": { "diff": 1 },
  "value_type": "number"
}

Ví dụ

curl -X PUT https://api.logsninja.com/v1/metrics \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "YOUR_PROJECT_ID",
    "id": "mrr",
    "title": "MRR",
    "value": 4900,
    "value_type": "currency",
    "currency": "EUR"
  }'

await fetch('https://api.logsninja.com/v1/metrics', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    project: 'YOUR_PROJECT_ID',
    id: 'mrr',
    title: 'MRR',
    value: 4900,
    value_type: 'currency',
    currency: 'EUR',
  }),
});

import requests

requests.put(
    'https://api.logsninja.com/v1/metrics',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
    },
    json={
        'project': 'YOUR_PROJECT_ID',
        'id': 'mrr',
        'title': 'MRR',
        'value': 4900,
        'value_type': 'currency',
        'currency': 'EUR',
    },
)

Xóa chỉ số

Xóa ô chỉ số khỏi bảng điều khiển.

Dự án

Danh sách dự án

Trả về các dự án trong tổ chức theo từng trang. Token giới hạn theo dự án chỉ nhận được dự án đã liên kết. Chấp nhận tham số page (mặc định 1) và limit (mặc định 50, tối đa 200). Phản hồi gồm page, limit, total và has_more.

Tạo dự án

Việc tạo dự án yêu cầu token có phạm vi toàn tổ chức. Token giới hạn theo dự án không thể tạo dự án.

Tokens

Danh sách token

Trả về các token API trong tổ chức theo từng trang. Token giới hạn theo dự án chỉ nhận được các token liên kết với cùng dự án. Chấp nhận tham số page (mặc định 1) và limit (mặc định 50, tối đa 200). Phản hồi gồm page, limit, total, has_more và quyền can_manage_tokens của từng token. Giá trị token không bao giờ được trả lại sau khi tạo.

Tạo token

Thông tin xác thực gọi API phải có can_manage_tokens=true. Giá trị token chỉ được trả về một lần và không thể lấy lại. Bên gọi bị giới hạn theo dự án chỉ có thể tạo token khác cho chính dự án đó; bỏ qua project_id không cấp quyền truy cập toàn tổ chức.

Ủy quyền thiết bị

Cho phép công cụ CLI hoặc tác nhân AI lấy token API mà không cần con người sao chép và dán thủ công. Công cụ yêu cầu một mã ngắn và hiển thị cho con người; một người dùng đã có tài khoản LogsNinja mở một liên kết và phê duyệt yêu cầu từ phiên trình duyệt của chính họ; sau đó công cụ tự động nhận được token. Việc này không bao giờ tạo tài khoản hay bỏ qua đăng ký – chỉ người dùng đã đăng nhập mới có thể phê duyệt yêu cầu.

Bắt đầu quy trình

Không cần xác thực. Trả về device_code, một user_code ngắn để hiển thị cho con người, và một verification_uri để mở trong trình duyệt.

{
  "device_code": "a1b2c3...",
  "user_code": "WXYZ-1234",
  "verification_uri": "https://logsninja.com/en/my/tokens#devices",
  "verification_uri_complete": "https://logsninja.com/en/my/tokens?user_code=WXYZ-1234#devices",
  "expires_in": 600,
  "interval": 5
}

Hiển thị user_code (hoặc liên kết verification_uri_complete) cho con người và yêu cầu họ mở và phê duyệt yêu cầu.

Thăm dò để lấy token

Không cần xác thực. Thăm dò bằng device_code theo khoảng thời gian đã cho ở trên cho đến khi trạng thái không còn là pending.

Phản hồi là {"status": "pending"}, {"status": "denied"}, {"status": "expired"}, hoặc, khi đã được phê duyệt, {"status": "approved", "token": "..."}. Token chỉ được trả về đúng một lần – hãy lưu lại ngay lập tức.

Máy chủ MCP

Cho phép một tác nhân AI (Claude, v.v.) sử dụng LogsNinja trực tiếp từ một cuộc trò chuyện thay vì viết các lệnh gọi HTTP.

Trỏ client MCP của bạn đến URL này, xác thực bằng cùng token API như phần còn lại của API này: Authorization: Bearer YOUR_API_TOKEN.

Claude Code

claude mcp add --transport http logsninja https://logsninja.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Claude Desktop

File cấu hình của Claude Desktop không còn chấp nhận trực tiếp url và headers của một server từ xa – chỉ hỗ trợ server stdio (command/args). Hãy kết nối đến endpoint HTTP này bằng mcp-remote:

{
  "mcpServers": {
    "logsninja": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://logsninja.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_TOKEN"
      ]
    }
  }
}

Cursor

Cursor hỗ trợ trực tiếp url và headers của một server từ xa, không cần cầu nối:

{
  "mcpServers": {
    "logsninja": {
      "url": "https://logsninja.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

File cấu hình: ~/.cursor/mcp.json (toàn cục) hoặc .cursor/mcp.json (dự án)

Codex CLI và ứng dụng ChatGPT

Cả hai đều dùng chung ~/.codex/config.toml – form Settings → Plugins → MCPs → Add Server của ứng dụng ChatGPT cũng ghi vào file này. Hãy chỉnh sửa trực tiếp để dùng bearer_token_env_var, đọc token từ một biến môi trường thay vì lưu dạng văn bản thuần:

[mcp_servers.logsninja]
url = "https://logsninja.com/mcp"
bearer_token_env_var = "LOGSNINJA_API_TOKEN"

Đặt biến môi trường trong shell profile trước khi khởi chạy Codex hoặc ứng dụng ChatGPT, ví dụ export LOGSNINJA_API_TOKEN=YOUR_API_TOKEN.

File cấu hình: ~/.codex/config.toml

Công cụ

Hầu hết các tool nhận tham số project_id, bắt buộc trừ khi token bị giới hạn cho một dự án duy nhất – cùng quy tắc như các endpoint REST bên dưới.

Biểu đồ

Tạo và quản lý các biểu đồ giống như bạn tự xây dựng trên bảng điều khiển – mọi tùy chọn bên dưới và mọi quy tắc xác thực đều giống hệt nhau, dù bạn dùng trình chỉnh sửa biểu đồ trên bảng điều khiển hay API. Đây chỉ là cấu hình biểu đồ: nó định nghĩa những gì biểu đồ hiển thị, không phải giá trị đã tính toán – không có endpoint nào để lấy các điểm dữ liệu của biểu đồ qua API này.

Loại biểu đồ

Biểu đồ đường (line) vẽ một giá trị cho mỗi kỳ dưới dạng đường liền – phù hợp để theo dõi xu hướng theo thời gian. Biểu đồ tròn (pie) hiển thị một ảnh chụp nhanh duy nhất chia thành các lát – phù hợp để xem tỷ lệ trong nháy mắt. Biểu đồ cột (bar) hiển thị một cột mỗi kỳ; ngay khi bạn thêm một phân tách (xem « Group by » bên dưới), nó tự động được vẽ với các phân đoạn xếp chồng thay vì một cột duy nhất – không có loại « cột xếp chồng » riêng để chọn. Biểu đồ phễu (funnel) đặt ra một loại câu hỏi hoàn toàn khác: thay vì một chỉ số theo thời gian, nó cho biết có bao nhiêu người dùng giống nhau đã đi qua một chuỗi bước có thứ tự.

Khoảng thời gian và khoảng chia

Chọn khoảng thời gian biểu đồ nhìn lại: 7 ngày qua (7d), 30 ngày qua (30d), hoặc 90 ngày qua (90d). Bạn cũng có thể tự định kích thước cửa sổ trượt theo giờ, ngày hoặc tháng (duration, kèm periodDurationValue và periodDurationUnit, ví dụ « 45 ngày qua »), hoặc đặt ngày bắt đầu cố định luôn chạy đến hôm nay (custom, kèm periodDateFrom) – không có trường nào để đặt ngày kết thúc cố định, nó luôn chạy đến hôm nay.

Khoảng chia thời gian (granularity) quyết định cách khoảng thời gian đó được chia thành các đoạn: theo giờ, ngày, tuần hoặc tháng (hour, day, week, month). Nó không áp dụng cho biểu đồ phễu: chúng vẫn dùng khoảng thời gian ở trên để lọc sự kiện, nhưng hiển thị một cột cho mỗi bước thay vì một chuỗi đoạn theo thời gian.

Một số tổ hợp chỉ có 90 ngày lịch sử khả dụng, bất kể khoảng thời gian bạn chọn: một phễu, một biểu đồ tròn có phân tách, một phân tách theo quốc gia/người dùng/metadata, nhiều hơn một phân tách cùng lúc, bất kỳ phép tính nào khác ngoài đếm đơn giản, hoặc lọc theo metadata. Một phép đếm đơn giản không có phân tách, hoặc phân tách chỉ theo stream hoặc tiêu đề sự kiện, có thể lùi xa hơn.

Lọc sự kiện nào được tính

Theo mặc định, một biểu đồ bao gồm mọi sự kiện (all). Bạn có thể thu hẹp xuống một stream duy nhất (stream, ví dụ chỉ "payments"), một tiêu đề sự kiện duy nhất (title, ví dụ chỉ "Order placed"), hoặc các sự kiện khớp với một giá trị metadata cụ thể (metadata, ví dụ chỉ sự kiện có "plan" bằng "pro").

Tổng hợp

Điều này quyết định cách các sự kiện khớp trong mỗi khoảng thời gian trở thành con số duy nhất được vẽ: đếm sự kiện đơn giản (count), đếm người dùng riêng biệt (count_distinct), hoặc một phép tính trên giá trị metadata dạng số của sự kiện – tổng (sum), trung bình (avg), nhỏ nhất (min), lớn nhất (max), hoặc trung vị (median). Với bất kỳ phép tính nào khác ngoài đếm đơn giản, bạn cũng chọn khóa metadata nào chứa con số đó qua aggregation_field; các sự kiện thiếu khóa đó, hoặc giá trị không phải số, sẽ bị bỏ qua.

Nhóm theo

Theo mặc định, một biểu đồ hiển thị một giá trị tổng hợp duy nhất cho mỗi kỳ. Việc nhóm (group_by) sẽ tách nó thành nhiều chuỗi hoặc phân đoạn thay vào đó – mỗi giá trị riêng biệt của thứ bạn dùng để nhóm – được vẽ dưới dạng các đường riêng biệt, phân đoạn xếp chồng, hoặc lát hình tròn tùy theo loại biểu đồ.

Bạn có thể nhóm theo stream (stream), tiêu đề sự kiện (title), quốc gia (country), hoặc người dùng (user) mà không cần cấu hình gì thêm, hoặc theo một khóa metadata tùy chọn (metadata, với aggregation_field chứa khóa dùng để tách).

Một ràng buộc cần biết: khóa metadata bạn dùng để nhóm và khóa metadata bạn tổng hợp là cùng một cài đặt (aggregation_field), vì một biểu đồ chỉ có một khóa đó. Vì vậy "tổng số tiền đơn hàng mỗi ngày, chia theo gói" không thể thực hiện trong một biểu đồ duy nhất – bạn cần hoặc tính tổng số tiền không phân tách, hoặc đếm đơn hàng phân tách theo gói, không thể cả hai trên cùng một biểu đồ.

Biểu đồ phễu

Biểu đồ phễu (funnel) đặt ra một loại câu hỏi hoàn toàn khác: không phải « bao nhiêu sự kiện » mà là « bao nhiêu người dùng giống nhau đã đi từ bước 1, sang bước 2, sang bước 3 ». Bạn cung cấp một danh sách có thứ tự gồm ít nhất hai tiêu đề sự kiện qua funnel_steps; biểu đồ hiển thị một cột cho mỗi bước, mỗi cột chỉ đếm những người dùng đã hoàn thành mọi bước trước đó theo đúng thứ tự. Khoảng thời gian ở trên vẫn áp dụng, nhưng khoảng chia, phép tổng hợp và việc phân nhóm thì không.

Tùy chọn hiển thị

Bạn có thể hiện hoặc ẩn chú giải (show_legend), và chọn màu riêng (colors, một mảng mã hex áp dụng theo thứ tự) cho mỗi chuỗi hoặc phân đoạn thay vì bảng màu mặc định. Bạn cũng có thể chuyển sang tổng lũy kế (cumulative) thay vì giá trị theo từng kỳ – chỉ có ý nghĩa với biểu đồ đường hoặc cột cộng dồn một phép đếm hoặc tổng, vì tổng lũy kế của một giá trị trung bình, một số lượng người dùng riêng biệt, hoặc một biểu đồ tròn/phễu thì không có ý nghĩa gì.

Liệt kê biểu đồ

Chấp nhận tham số truy vấn project_id, bắt buộc trừ khi token đã được giới hạn cho một dự án duy nhất.

Tạo biểu đồ

Cập nhật biểu đồ

Chỉ những trường bạn gửi mới được thay đổi.

Xóa biểu đồ

Dữ liệu lịch sử vượt quá thời gian lưu trữ không khả dụng đối với các tổ hợp quét sự kiện thô (funnel, pie có group-by, group-by theo country/user/metadata, hoặc bất kỳ phép tổng hợp nào khác ngoài count).

Widget

Quản lý những ô nào xuất hiện trên bảng điều khiển và cách chúng được sắp xếp – đây chỉ là cấu hình bố cục, không phải dữ liệu hiển thị bên trong một ô.

Bảng điều khiển là bố cục kiểu masonry, không phải lưới cứng nhắc. Các widget « nhỏ » (metric, online_users) được thiết kế để chiếm một phần ba hoặc một nửa hàng (width 1 hoặc 2) và hiển thị với chính xác một nửa chiều cao trực quan của các widget « lớn » (chart, world_map, events_7d, top_countries), được thiết kế để chiếm một nửa hàng hoặc toàn bộ hàng (width 2 hoặc 3). Hãy nhớ điều này khi sắp xếp bảng điều khiển qua API.

Liệt kê widget

Chấp nhận tham số truy vấn project_id, bắt buộc trừ khi token đã được giới hạn cho một dự án duy nhất.

Thêm widget

Thay đổi kích thước hoặc di chuyển widget

Gửi width và/hoặc position (chỉ số bắt đầu từ 0 trong số các widget của dự án). Đặt một vị trí sẽ di chuyển widget đến đó và đẩy mọi widget phía sau xuống một bậc – nó không hoán đổi hai widget. Chỉ những trường bạn gửi mới được thay đổi.

Sắp xếp lại toàn bộ bảng điều khiển

Gửi order dưới dạng danh sách đầy đủ, có thứ tự của mọi id widget trong dự án (danh sách không đầy đủ sẽ bị từ chối), và tùy chọn widths dưới dạng bản đồ id sang width.

Xóa widget

Mã phản hồi

Mã lỗi: 400 lỗi xác thực, 401 token thiếu hoặc không hợp lệ, 403 token bị giới hạn cho dự án khác, 404 không tìm thấy dự án.