portaly-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Portaly Analytics Integration

Portaly 分析集成

Use this skill to help a Portaly creator install Google Analytics 4 on their website and connect it to Portaly. Keep answers operational: prefer step lists, code snippets, and copy-ready examples over long architecture explanations.

使用本技能帮助Portaly创作者在其网站上安装Google Analytics 4并将其与Portaly连接。回复需注重实操性：优先使用步骤列表、代码片段和可直接复制的示例，而非冗长的架构说明。

Quick Start

快速开始

First, ask the human user what they want to accomplish:
- Install GA4 on my website → Part A (steps 1–5)
- Connect GA to Portaly dashboard → Part B (step 6)
- Both → Part A + Part B (steps 1–6)

Confirm what the human user is trying to build. Ask about their tech stack (Next.js / React / vanilla HTML) and whether they have an existing GA4 Property.
Guide through GA4 setup and event tracking installation.
If the user wants to see analytics in Portaly, guide through the Portaly authorization flow.
Start with
```
references/ga4-setup-guide.md
```
for installation instructions.
Return implementation-ready output. Prefer numbered steps, code samples, and copy-ready configuration.

首先询问用户想要完成的操作：
- 在我的网站上安装GA4 → 部分A（步骤1–5）
- 将GA连接到Portaly面板 → 部分B（步骤6）
- 两者都要 → 部分A + 部分B（步骤1–6）

确认用户想要搭建的内容。询问他们的技术栈（Next.js / React / 原生HTML）以及是否已有GA4 Property。
指导完成GA4设置和事件追踪安装。
如果用户希望在Portaly中查看分析数据，指导完成Portaly授权流程。
参考
```
references/ga4-setup-guide.md
```
获取安装说明。
返回可直接实施的输出内容。优先使用编号步骤、代码片段和可直接复制的配置示例。

Output Style

输出风格

Write for an AI agent that is helping a human user complete integration work.
Lead with the next concrete steps the human should take.
Use lists for:
- setup steps
- environment variables
- event definitions
- configuration options
Prefer concise code samples in JavaScript or TypeScript when the user does not ask for another stack.
Always include
```
.env
```
configuration and
```
.gitignore
```
verification steps.

为帮助人类用户完成集成工作的AI Agent撰写内容。
以用户下一步需执行的具体步骤开头。
使用列表呈现：
- 设置步骤
- 环境变量
- 事件定义
- 配置选项
当用户未指定其他技术栈时，优先使用JavaScript或TypeScript的简洁代码示例。
始终包含
```
.env
```
配置和
```
.gitignore
```
验证步骤。

Part A — GA4 Installation & Event Tracking

部分A — GA4安装与事件追踪

1. Create GA4 Property

1. 创建GA4 Property

If the user does not have a GA4 Property, guide them to create one:
1. Go to Google Analytics
2. Click "Admin" → "Create Property"
3. Enter property name, select timezone and currency
4. Set up a Web data stream with the site URL
5. Copy the Measurement ID (
```
G-XXXXXXX
```
  )
Ask the user to provide their Measurement ID.
Save it to
```
.env
```
:

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXX

Verify that
.gitignore
includes
.env
before proceeding.

如果用户没有GA4 Property，指导他们创建：
1. 访问Google Analytics
2. 点击“Admin”（管理员）→ “Create Property”（创建媒体资源）
3. 输入媒体资源名称，选择时区和货币
4. 使用网站URL设置Web数据流
5. 复制Measurement ID（格式为
```
G-XXXXXXX
```
  ）
请求用户提供他们的Measurement ID。
将其保存到
```
.env
```
文件中：

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXX

继续操作前，请确认
.gitignore
已包含
.env

2. Install gtag.js

2. 安装gtag.js

Refer to
```
references/ga4-setup-guide.md
```
for framework-specific installation instructions.
Choose the correct approach based on the user's tech stack:
- Next.js App Router →
```
layout.tsx
```
  with
```
next/script
```
- Next.js Pages Router →
```
_app.js
```
  with
```
next/script
```
- React SPA →
```
index.html
```
  script tags
- Vanilla HTML →
```
<head>
```
  script tags
Reference implementation:
```
scripts/gtag-nextjs-example.mjs
```

参考
```
references/ga4-setup-guide.md
```
获取针对不同框架的安装说明。
根据用户的技术栈选择正确的方法：
- Next.js App Router → 在
```
layout.tsx
```
  中使用
```
next/script
```
- Next.js Pages Router → 在
```
_app.js
```
  中使用
```
next/script
```
- React SPA → 在
```
index.html
```
  中添加脚本标签
- 原生HTML → 在
```
<head>
```
  中添加脚本标签
参考实现示例：
```
scripts/gtag-nextjs-example.mjs
```

3. Set up Portaly event tracking

3. 设置Portaly事件追踪

Refer to
```
references/event-tracking-contract.md
```
for standard Portaly event definitions.
Install standard Portaly events based on what the user's app does:
- ```
portaly_checkout_start
```
  — when a checkout session is created
- ```
portaly_checkout_complete
```
  — when a payment callback confirms completion
- ```
portaly_subscription_cancel
```
  — when a subscription is cancelled
- ```
portaly_page_view
```
  — when a Portaly-embedded page is viewed
- ```
portaly_product_view
```
  — when a product page is viewed
Map to GA4 recommended ecommerce events where applicable (
```
begin_checkout
```
,
```
purchase
```
).
Reference implementation:
```
scripts/track-portaly-events.mjs
```

参考
```
references/event-tracking-contract.md
```
获取标准Portaly事件定义。
根据用户应用的功能安装标准Portaly事件：
- ```
portaly_checkout_start
```
  — 当结账会话创建时触发
- ```
portaly_checkout_complete
```
  — 当支付回调确认完成时触发
- ```
portaly_subscription_cancel
```
  — 当订阅取消时触发
- ```
portaly_page_view
```
  — 当嵌入Portaly的页面被查看时触发
- ```
portaly_product_view
```
  — 当产品页面被查看时触发
适当时映射到GA4推荐的电商事件（如
```
begin_checkout
```
、
```
purchase
```
）。
参考实现示例：
```
scripts/track-portaly-events.mjs
```

4. Verify installation

4. 验证安装

Guide the user to verify in GA4 Realtime report:
1. Open the website in a browser
2. Go to Google Analytics → Reports → Realtime
3. Confirm page views and events appear
If events don't appear, check:
- Measurement ID is correct
- gtag.js script is loaded (check browser Network tab)
- No ad blockers interfering
- Consent mode is not blocking (if applicable)

指导用户在GA4实时报告中验证：
1. 在浏览器中打开网站
2. 进入Google Analytics → 报告 → 实时
3. 确认页面浏览量和事件已显示
如果事件未显示，请检查：
- Measurement ID是否正确
- gtag.js脚本是否已加载（查看浏览器网络标签）
- 是否有广告拦截器干扰
- 是否有同意模式阻止追踪（如适用）

5. Optional: Enhanced ecommerce tracking

5. 可选：增强型电商追踪

For users with Portaly payment integration, set up enhanced ecommerce events:
- ```
view_item
```
  → when a plan or product page is viewed
- ```
begin_checkout
```
  → mapped from
```
portaly_checkout_start
```
- ```
purchase
```
  → mapped from
```
portaly_checkout_complete
```
These enable GA4's built-in ecommerce reports.

对于集成了Portaly支付功能的用户，设置增强型电商事件：
- ```
view_item
```
  → 当查看套餐或产品页面时触发
- ```
begin_checkout
```
  → 映射自
```
portaly_checkout_start
```
- ```
purchase
```
  → 映射自
```
portaly_checkout_complete
```
这些事件可启用GA4内置的电商报告。

Part B — Connect Google Analytics to Portaly

部分B — 将Google Analytics连接到Portaly

6. Authorize Portaly to access GA data

6. 授权Portaly访问GA数据

Once GA4 is installed and collecting data, guide the user to connect it to Portaly:

Go to Portaly admin:
```
https://portaly.cc/admin
```
Navigate to 分析工具 (Analytics) settings
Click 連結 Google Analytics
Sign in with the Google account that owns the GA4 Property
Grant Portaly read-only access to Google Analytics data
Select the GA4 Property to connect
Done — analytics dashboard will appear in Portaly admin

Key points to communicate to the user:

Portaly only requests read-only access (
```
analytics.readonly
```
scope). Portaly cannot modify your GA4 settings or data.
You can revoke access at any time from your Google Account permissions.
The dashboard in Portaly will show data from your connected GA4 Property, including sessions, page views, traffic sources, and Portaly-specific events.
GA4 data has a 24–48 hour processing delay. Newly installed tracking may take 1–2 days to show historical data in Portaly.

GA4安装完成并开始收集数据后，指导用户将其与Portaly连接：

访问Portaly管理后台：
```
https://portaly.cc/admin
```
导航至分析工具（Analytics）设置页面
点击連結 Google Analytics（连接Google Analytics）
使用拥有GA4 Property的Google账号登录
授予Portaly对Google Analytics数据的只读访问权限
选择要连接的GA4 Property
完成设置 — 分析面板将在Portaly管理后台中显示

需要向用户传达的关键点：

Portaly仅请求只读访问权限（
```
analytics.readonly
```
权限范围）。Portaly无法修改您的GA4设置或数据。
您可随时从Google账号权限页面撤销访问权限。
Portaly中的面板将显示来自已连接GA4 Property的数据，包括会话、页面浏览量、流量来源以及Portaly专属事件。
GA4数据存在24–48小时的处理延迟。新安装的追踪可能需要1–2天才能在Portaly中显示历史数据。

Guardrails

约束规则

Measurement ID format: Always
```
G-XXXXXXX
```
. If the user provides a different format (e.g.,
```
UA-XXXXX
```
), that is a Universal Analytics ID — guide them to create a GA4 Property instead.
Credentials security: The Measurement ID (
```
G-XXXXXXX
```
) is not a secret — it's visible in page source. However, always store it in
```
.env
```
for easy configuration management and verify
```
.gitignore
```
includes
```
.env
```
.
Cross-domain tracking: If the user's app redirects to
```
portaly.ai
```
for checkout and back, recommend setting up cross-domain tracking in GA4 to maintain session continuity:
1. Go to GA4 Admin → Data Streams → Web → Configure tag settings → Configure your domains
2. Add both domains
Ad blockers: Some visitors use ad blockers that block gtag.js. GA4 numbers will always undercount. Do not promise 100% tracking accuracy.
Consent mode: If the user's site needs cookie consent (GDPR, etc.), guide them to implement GA4 consent mode.
Data freshness: GA4 data has a 24–48 hour processing delay. Realtime data is available in GA4's own Realtime report but Portaly dashboards rely on the processed data.
Portaly authorization: The Portaly OAuth connection is handled entirely by Portaly's hosted flow. The user does not need to create any Google Cloud projects, OAuth clients, or manage API keys. They simply click "Connect" and authorize.

Measurement ID格式：必须为
```
G-XXXXXXX
```
。如果用户提供了其他格式（如
```
UA-XXXXX
```
），这是Universal Analytics的ID — 指导用户创建GA4 Property。
凭证安全：Measurement ID（
```
G-XXXXXXX
```
）并非机密信息 — 它会在页面源码中显示。但始终建议将其存储在
```
.env
```
中以便于配置管理，并确认
```
.gitignore
```
已包含
```
.env
```
。
跨域追踪：如果用户的应用在结账时重定向到
```
portaly.ai
```
后再返回，建议在GA4中设置跨域追踪以保持会话连续性：
1. 进入GA4管理员 → 数据流 → Web → 配置标签设置 → 配置您的域名
2. 添加两个域名
广告拦截器：部分访客使用广告拦截器会阻止gtag.js加载。GA4的数据统计会始终存在低估情况，请勿承诺100%的追踪准确性。
同意模式：如果用户的网站需要Cookie同意（如GDPR等法规要求），指导用户实施GA4同意模式。
数据新鲜度：GA4数据存在24–48小时的处理延迟。GA4自身的实时报告可查看实时数据，但Portaly面板依赖于处理后的历史数据。
Portaly授权：Portaly的OAuth连接完全由Portaly的托管流程处理。用户无需创建任何Google Cloud项目、OAuth客户端或管理API密钥。只需点击“连接”并授权即可。

Preferred Response Shape

Resources

资源

```
references/ga4-setup-guide.md
```
Use for framework-specific gtag.js installation instructions and pageview/event tracking setup.
```
references/event-tracking-contract.md
```
Use for standard Portaly event names, parameters, and GA4 ecommerce event mappings.
```
scripts/gtag-nextjs-example.mjs
```
Reference implementation for installing gtag.js in a Next.js application.
```
scripts/track-portaly-events.mjs
```
Reference implementation for tracking Portaly-specific events.

```
references/ga4-setup-guide.md
```
用于获取针对不同框架的gtag.js安装说明以及页面浏览/事件追踪设置。
```
references/event-tracking-contract.md
```
用于获取标准Portaly事件名称、参数以及与GA4电商事件的映射关系。
```
scripts/gtag-nextjs-example.mjs
```
用于在Next.js应用中安装gtag.js的参考实现。
```
scripts/track-portaly-events.mjs
```
用于追踪Portaly专属事件的参考实现。