分析

产品分析：track、identify、漏斗与同期群。

概览

基础路径: https://api.infrai.cc/v1/analytics

鉴权头: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/analytics capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/analytics/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

方法

analytics.track

POST /v1/analytics/track

追踪一个或多个分析事件。

参数

名称	类型	必填	说明
`event`	`string`	必填	事件名称。
`distinct_id`	`string`	必填	操作用户的稳定 id。
`properties`	`Record<string, unknown>`	可选	任意事件属性。

{ ok, accepted }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/track \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "checkout_completed", "distinct_id": "user_42", "properties": {"amount": 19.99}}'

analytics.identify

POST /v1/analytics/identify

将特征属性关联到某个 distinct id。

参数

名称	类型	必填	说明
`distinct_id`	`string`	必填	操作用户的稳定 id。
`user_id`	`string`	可选	连接用户的 id。
`traits`	`Record<string, unknown>`	可选	要设置的用户特征。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/identify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "..."}'

analytics.alias

POST /v1/analytics/alias

合并身份别名

参数

名称	类型	必填	说明
`old_id`	`string`	必填	要合并的来源 distinct_id（例如匿名 id）。
`new_id`	`string`	必填	合并目标的规范 distinct_id。
`idempotency_key`	`string`	可选	可选幂等键，确保重复请求只生效一次。

AliasResult { merged: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/alias \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"old_id": "...", "new_id": "..."}'

analytics.batch

POST /v1/analytics/batch

批量上报事件

参数

名称	类型	必填	说明
`events`	`TrackEvent[]`	必填	至多 1000 条 TrackEvent 事件，每条事件自带幂等键。

{ ok: boolean, accepted: number }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": []}'

analytics.group

POST /v1/analytics/group

关联群组

参数

名称	类型	必填	说明
`distinct_id`	`string`	必填	要关联到群组的用户 distinct_id。
`group_type`	`string`	必填	群组维度，例如 company / team。
`group_key`	`string`	必填	在 group_type 下的群组标识符。
`traits`	`Record<string, unknown>`	可选	可选的群组档案属性。
`idempotency_key`	`string`	可选	可选幂等键，确保重复请求只生效一次。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/group \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "...", "group_type": "...", "group_key": "..."}'

analytics.dashboard.create

POST /v1/analytics/dashboard/create

创建仪表盘

参数

名称	类型	必填	说明
`name`	`string`	必填	仪表盘名称。
`queries`	`object[]`	必填	组成仪表盘的已保存查询列表。
`idempotency_key`	`string`	可选	可选幂等键，确保重复请求只生效一次。

Dashboard

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/dashboard/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "queries": []}'

analytics.dashboard.get

GET /v1/analytics/dashboard/get/{dashboard_id}

获取仪表盘

参数

名称	类型	必填	说明
`dashboard_id`	`string`	必填	仪表盘 id。

Dashboard

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/analytics/dashboard/get/DASHBOARD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.dashboard.list

GET /v1/analytics/dashboard/list

列出仪表盘

参数

名称	类型	必填	说明
`cursor`	`string`	可选	来自上一页 next_cursor 的不透明游标。
`limit`	`number`	可选	本页返回的最大条数。

{ items: Dashboard[], next_cursor?: string }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/analytics/dashboard/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.dashboard.delete

DELETE /v1/analytics/dashboard/delete/{dashboard_id}

删除仪表盘

参数

名称	类型	必填	说明
`dashboard_id`	`string`	必填	要删除的仪表盘 id。
`idempotency_key`	`string`	可选	可选幂等键，确保重复请求只生效一次。

{ ok: boolean }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/analytics/dashboard/delete/DASHBOARD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.query.events

POST /v1/analytics/query/events

查询原始事件

参数

名称	类型	必填	说明
`since`	`string`	必填	时间窗口起点（含）。
`until`	`string`	必填	时间窗口终点（不含）。
`filter`	`Record<string, unknown>`	可选	可选属性过滤（键/值匹配）。
`limit`	`number`	可选	本页返回的最大条数（1-1000，默认 1000）。
`cursor`	`string`	可选	来自上一页 next_cursor 的不透明游标。

EventQueryResult { events: object[], next_cursor?: string }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/events \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since": "...", "until": "..."}'

analytics.query.retention

POST /v1/analytics/query/retention

查询留存

参数

名称	类型	必填	说明
`born_event`	`string`	必填	定义群组归属（第 0 天）的事件。
`return_event`	`string`	必填	其再次发生用于衡量留存的事件。
`since`	`string`	必填	时间窗口起点。
`until`	`string`	必填	时间窗口终点。
`interval`	`string`	可选	分桶周期（默认 day）。

RetentionResult { matrix: number[][] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/retention \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"born_event": "...", "return_event": "...", "since": "...", "until": "..."}'

analytics.query.path

POST /v1/analytics/query/path

查询行为路径

参数

名称	类型	必填	说明
`start_event`	`string`	必填	路径树展开的根事件。
`since`	`string`	必填	时间窗口起点。
`until`	`string`	必填	时间窗口终点。
`max_depth`	`number`	可选	路径树最大深度（1-20，默认 5）。

PathResult { root: string, children: object[] }

示例

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/path \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_event": "...", "since": "...", "until": "..."}'

全部能力

本模块全部已路由能力——完整的对外 REST 契约。上方方法是带讲解的入门示例,此表是完整参考。

能力	端点	说明
`analytics.alias`	`POST /v1/analytics/alias`	Rename or merge an anonymous distinct_id (old_id) into a known identity (new_id).
`analytics.batch`	`POST /v1/analytics/batch`	Ingest up to 1000 TrackEvent events in a single call (idempotency is per-event).
`analytics.dashboard.create`	`POST /v1/analytics/dashboard/create`	Assemble a dashboard from saved queries and return the Dashboard.
`analytics.dashboard.delete`	`DELETE /v1/analytics/dashboard/delete/{dashboard_id}`	Delete a dashboard by dashboard_id (idempotent).
`analytics.dashboard.get`	`GET /v1/analytics/dashboard/get/{dashboard_id}`	Get a single dashboard by dashboard_id.
`analytics.dashboard.list`	`GET /v1/analytics/dashboard/list`	List all dashboards on the account with cursor pagination.
`analytics.group`	`POST /v1/analytics/group`	Associate a distinct_id with a group (organization/team/account) for B2B account-level aggregation.
`analytics.identify`	`POST /v1/analytics/identify`	Set profile traits on a distinct_id, optionally merging a prior id via alias_for.
`analytics.query.events`	`POST /v1/analytics/query/events`	Query raw events within a time window, with attribute filters and cursor pagination.
`analytics.query.path`	`POST /v1/analytics/query/path`	Build behavioral path/sequence trees rooted at a start event within a time window.
`analytics.query.retention`	`POST /v1/analytics/query/retention`	Compute a retention matrix bucketed by period from a born event to a return event.
`analytics.track`	`POST /v1/analytics/track`	Ingest a single product analytics event with properties for a distinct user; idempotent.

完整示例

本模块的生产级端到端范例:先一次性配置,再运行业务流程,尽量覆盖本模块的多数 API。

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) analytics.track
curl -X POST https://api.infrai.cc/v1/analytics/track \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "checkout_completed", "distinct_id": "user_42", "properties": {"amount": 19.99}}'

# 3) analytics.identify
curl -X POST https://api.infrai.cc/v1/analytics/identify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "..."}'

# 4) analytics.alias
curl -X POST https://api.infrai.cc/v1/analytics/alias \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"old_id": "...", "new_id": "..."}'

# 5) analytics.batch
curl -X POST https://api.infrai.cc/v1/analytics/batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": []}'

# 6) analytics.group
curl -X POST https://api.infrai.cc/v1/analytics/group \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "...", "group_type": "...", "group_key": "..."}'

# 7) analytics.dashboard.create
curl -X POST https://api.infrai.cc/v1/analytics/dashboard/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "queries": []}'