posthog-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog Analytics Skill

PostHog 分析技能

Automate PostHog dashboard creation, sync, update, and export via API.

通过API自动化PostHog仪表盘的创建、同步、更新与导出。

Prerequisites

前置条件

Required Tools

所需工具

```
curl
```
- HTTP client (pre-installed on macOS/Linux)
```
jq
```
- JSON processor:
```
brew install jq
```
or
```
apt install jq
```
```
bash
```
- Shell (the script is bash)

```
curl
```
- HTTP客户端（macOS/Linux系统预装）
```
jq
```
- JSON处理器：
```
brew install jq
```
或
```
apt install jq
```
```
bash
```
- Shell（脚本基于bash编写）

PostHog API Key

PostHog API密钥

Go to PostHog Settings → Personal API Keys
Create a new key with read/write access
Export it:

bash

export POSTHOG_PERSONAL_API_KEY=phx_xxx

Note: The API key determines your organization and project. The script uses

@current

project context (your default project).

前往PostHog 设置 → 个人API密钥
创建一个具备读写权限的新密钥
导出密钥：

bash

export POSTHOG_PERSONAL_API_KEY=phx_xxx

注意：API密钥决定了您的组织和项目。脚本使用

@current

项目上下文（即您的默认项目）。

Verify Setup

验证配置

bash

undefined

bash

undefined

Test your API key - should return your project info

curl -s -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY"
"https://us.i.posthog.com/api/projects/@current/" | jq '{id, name}'


Expected output:
```json
{
  "id": 209268,
  "name": "Default project"
}

If you get an error, check your API key is correct and has proper permissions.

curl -s -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY"
"https://us.i.posthog.com/api/projects/@current/" | jq '{id, name}'


预期输出：
```json
{
  "id": 209268,
  "name": "Default project"
}

如果出现错误，请检查您的API密钥是否正确，以及是否拥有合适的权限。

Quick Start: Blog Analytics Example

快速开始：博客分析示例

Step 1: Write Your Config

步骤1：编写配置文件

Create

blog_dashboard.json

json

{
  "name": "Blog Analytics",
  "description": "Track blog performance and reader engagement",
  "filter": {"key": "source", "value": "blog"},
  "dashboard_id": null,
  "insights": [
    {"name": "Blog Pageviews (Total)", "type": "pageviews_total"},
    {"name": "Unique Blog Readers", "type": "unique_users"},
    {"name": "Blog Traffic Trend", "type": "traffic_trend"},
    {"name": "Top Blog Posts", "type": "top_pages"}
  ]
}

Note: Set

dashboard_id: null

for new dashboards.

创建

blog_dashboard.json

：

json

{
  "name": "Blog Analytics",
  "description": "Track blog performance and reader engagement",
  "filter": {"key": "source", "value": "blog"},
  "dashboard_id": null,
  "insights": [
    {"name": "Blog Pageviews (Total)", "type": "pageviews_total"},
    {"name": "Unique Blog Readers", "type": "unique_users"},
    {"name": "Blog Traffic Trend", "type": "traffic_trend"},
    {"name": "Top Blog Posts", "type": "top_pages"}
  ]
}

注意：对于新仪表盘，设置

dashboard_id: null

。

Step 2: Create Dashboard

步骤2：创建仪表盘

bash

./scripts/posthog_sync.sh create blog_dashboard.json

Output:

Creating dashboard: Blog Analytics
Dashboard created: ID 1166599
Creating insight: Blog Pageviews (Total)
{id: 6520531, name: "Blog Pageviews (Total)"}
...
Dashboard URL: https://us.posthog.com/project/209268/dashboard/1166599

The script:

Creates a new dashboard in your PostHog project
Returns dashboard_id (e.g.,
```
1166599
```
) and project_id (e.g.,
```
209268
```
) in the URL
Automatically updates your config file with the
```
dashboard_id
```

bash

./scripts/posthog_sync.sh create blog_dashboard.json

输出：

Creating dashboard: Blog Analytics
Dashboard created: ID 1166599
Creating insight: Blog Pageviews (Total)
{id: 6520531, name: "Blog Pageviews (Total)"}
...
Dashboard URL: https://us.posthog.com/project/209268/dashboard/1166599

脚本会：

在您的PostHog项目中创建一个新仪表盘
在URL中返回dashboard_id（例如：
```
1166599
```
）和project_id（例如：
```
209268
```
）
自动更新您的配置文件，填入
```
dashboard_id
```

Step 3: Add New Insights (Sync)

步骤3：添加新洞察（同步）

Edit config to add new insights, then:

bash

./scripts/posthog_sync.sh sync blog_dashboard.json

Only creates NEW insights. Existing ones (matched by name) are skipped.

编辑配置文件添加新洞察，然后执行：

bash

./scripts/posthog_sync.sh sync blog_dashboard.json

仅创建新的洞察。已存在的洞察（按名称匹配）会被跳过。

Step 4: Update Existing Insights

步骤4：更新现有洞察

Changed your filter? Edit config, then:

bash

./scripts/posthog_sync.sh update blog_dashboard.json

Updates ALL insights with current config settings. Use when changing filters.

修改了过滤器？编辑配置文件后执行：

bash

./scripts/posthog_sync.sh update blog_dashboard.json

会使用当前配置设置更新所有洞察。当修改过滤器时使用此命令。

Step 5: Export Existing Dashboard

步骤5：导出现有仪表盘

bash

./scripts/posthog_sync.sh export 1166599 > exported_dashboard.json

bash

./scripts/posthog_sync.sh export 1166599 > exported_dashboard.json

Config Reference

配置参考

Field	Required	Description
`name`	Yes	Dashboard name
`description`	No	Dashboard description
`filter`	No*	Event property filter: `{"key": "source", "value": "blog"}`
`domain_filter`	No*	URL filter fallback: `"blog.sylph.ai"`
`dashboard_id`	No	Set to `null` for create, or existing ID for sync/update
`insights`	Yes	Array of insight objects

*At least one filter recommended.

filter

takes precedence over

domain_filter

字段	是否必填	描述
`name`	是	仪表盘名称
`description`	否	仪表盘描述
`filter`	否*	事件属性过滤器： `{"key": "source", "value": "blog"}`
`domain_filter`	否*	URL过滤器备选： `"blog.sylph.ai"`
`dashboard_id`	否	创建新仪表盘时设为 `null` ，同步/更新时填入现有ID
`insights`	是	洞察对象数组

*建议至少设置一个过滤器。

filter

优先级高于

domain_filter

。

Insight Types

洞察类型

Type	Display	Description
`pageviews_total`	BoldNumber	Total pageview count
`unique_users`	BoldNumber	Unique visitors (DAU)
`traffic_trend`	LineGraph	Traffic over time
`top_pages`	Table	Top pages breakdown

类型	展示方式	描述
`pageviews_total`	BoldNumber	总页面浏览量
`unique_users`	BoldNumber	独立访客数（日活用户）
`traffic_trend`	LineGraph	流量趋势（随时间变化）
`top_pages`	Table	热门页面细分

Optional Insight Fields

可选洞察字段

Field	Default	Options
`math`	`total`	`total` , `dau` , `weekly_active` , `monthly_active`
`display`	Auto	`BoldNumber` , `ActionsLineGraph` , `ActionsTable`
`date_range`	`-30d`	`-7d` , `-30d` , `-90d` , etc.

字段	默认值	可选值
`math`	`total`	`total` , `dau` , `weekly_active` , `monthly_active`
`display`	自动	`BoldNumber` , `ActionsLineGraph` , `ActionsTable`
`date_range`	`-30d`	`-7d` , `-30d` , `-90d` 等

Environment Variables

环境变量

Variable	Required	Default	Description
`POSTHOG_PERSONAL_API_KEY`	Yes	-	Your API key (determines org/project)
`POSTHOG_HOST`	No	us.i.posthog.com	API host (EU: eu.i.posthog.com)
`POSTHOG_UI_HOST`	No	us.posthog.com	UI host for dashboard URLs

变量	是否必填	默认值	描述
`POSTHOG_PERSONAL_API_KEY`	是	-	您的API密钥（决定组织/项目）
`POSTHOG_HOST`	否	us.i.posthog.com	API主机（欧盟区域：eu.i.posthog.com）
`POSTHOG_UI_HOST`	否	us.posthog.com	仪表盘URL对应的UI主机

Files

文件说明

```
scripts/posthog_sync.sh
```
- CLI script (create/sync/update/export)
```
examples/blog_dashboard.json
```
- Example config

```
scripts/posthog_sync.sh
```
- CLI脚本（支持创建/同步/更新/导出操作）
```
examples/blog_dashboard.json
```
- 示例配置文件

posthog-analytics

Original

Translation

PostHog Analytics Skill

PostHog 分析技能

Prerequisites

前置条件

Required Tools

所需工具

PostHog API Key

PostHog API密钥

Verify Setup

验证配置

Test your API key - should return your project info

Test your API key - should return your project info

Quick Start: Blog Analytics Example

快速开始：博客分析示例

Step 1: Write Your Config

步骤1：编写配置文件

Step 2: Create Dashboard

步骤2：创建仪表盘

Step 3: Add New Insights (Sync)

步骤3：添加新洞察（同步）

Step 4: Update Existing Insights

步骤4：更新现有洞察

Step 5: Export Existing Dashboard

步骤5：导出现有仪表盘

Config Reference

配置参考

Insight Types

洞察类型

Optional Insight Fields

可选洞察字段

Environment Variables

环境变量

Files

文件说明

References

参考资料