integration-swift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for Swift (iOS/macOS)

适用于Swift（iOS/macOS）的PostHog集成

This skill helps you add PostHog analytics to Swift (iOS/macOS) applications.

本技能可帮助你为Swift（iOS/macOS）应用添加PostHog分析功能。

Workflow

工作流程

Follow these steps in order to complete the integration:

```
basic-integration-1.0-begin.md
```
- PostHog Setup - Begin ← Start here
```
basic-integration-1.1-edit.md
```
- PostHog Setup - Edit
```
basic-integration-1.2-revise.md
```
- PostHog Setup - Revise
```
basic-integration-1.3-conclude.md
```
- PostHog Setup - Conclusion

按照以下步骤完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog 设置 - 开始 ← 从此处开始
```
basic-integration-1.1-edit.md
```
- PostHog 设置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog 设置 - 修改
```
basic-integration-1.3-conclude.md
```
- PostHog 设置 - 总结

Reference files

参考文件

```
references/EXAMPLE.md
```
- Swift (iOS/macOS) example project code
```
references/ios.md
```
- Ios - docs
```
references/identify-users.md
```
- Identify users - docs

references/basic-integration-1.0-begin.md

- PostHog setup - begin

references/basic-integration-1.1-edit.md

- PostHog setup - edit

references/basic-integration-1.2-revise.md

- PostHog setup - revise

references/basic-integration-1.3-conclude.md

- PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

```
references/EXAMPLE.md
```
- Swift（iOS/macOS）示例项目代码
```
references/ios.md
```
- iOS - 文档
```
references/identify-users.md
```
- 用户识别 - 文档

references/basic-integration-1.0-begin.md

- PostHog 设置 - 开始

references/basic-integration-1.1-edit.md

- PostHog 设置 - 编辑

references/basic-integration-1.2-revise.md

- PostHog 设置 - 修改

references/basic-integration-1.3-conclude.md

- PostHog 设置 - 总结

示例项目展示了目标实现模式。如需了解API详情，请查阅相关文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

环境变量：始终使用环境变量存储PostHog密钥，切勿硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。

Framework guidelines

框架指南

Read configuration from environment variables via a
```
PostHogEnv
```
enum with a
```
value
```
computed property that calls
```
ProcessInfo.processInfo.environment[rawValue]
```
and
```
fatalError
```
s if missing — cases should be
```
projectToken = "POSTHOG_PROJECT_TOKEN"
```
and
```
host = "POSTHOG_HOST"
```
, set in the Xcode scheme's Run environment variables
When adding SPM dependencies to project.pbxproj, create three distinct objects with unique UUIDs — a
```
PBXBuildFile
```
(with
```
productRef
```
), an
```
XCSwiftPackageProductDependency
```
(with
```
package
```
and
```
productName
```
), and an
```
XCRemoteSwiftPackageReference
```
(with
```
repositoryURL
```
and
```
requirement
```
). The build file goes in the Frameworks phase
```
files
```
, the product dependency goes in the target's
```
packageProductDependencies
```
, and the package reference goes in the project's
```
packageReferences
```
.
Check the latest release version of posthog-ios at
```
https://github.com/PostHog/posthog-ios/releases
```
before setting the
```
minimumVersion
```
in the SPM package reference — do not hardcode a stale version
If the project uses App Sandbox (macOS), add
```
ENABLE_OUTGOING_NETWORK_CONNECTIONS = YES
```
to the target's build settings so PostHog can reach its servers — do NOT disable the sandbox entirely

通过
```
PostHogEnv
```
枚举从环境变量中读取配置，该枚举包含一个
```
value
```
计算属性，调用
```
ProcessInfo.processInfo.environment[rawValue]
```
，若缺失则触发
```
fatalError
```
——枚举值应为
```
projectToken = "POSTHOG_PROJECT_TOKEN"
```
和
```
host = "POSTHOG_HOST"
```
，需在Xcode scheme的Run环境变量中设置
向project.pbxproj添加SPM依赖时，创建三个具有唯一UUID的独立对象：
```
PBXBuildFile
```
（包含
```
productRef
```
）、
```
XCSwiftPackageProductDependency
```
（包含
```
package
```
和
```
productName
```
）以及
```
XCRemoteSwiftPackageReference
```
（包含
```
repositoryURL
```
和
```
requirement
```
）。构建文件需放入Frameworks阶段的
```
files
```
中，产品依赖需添加到目标的
```
packageProductDependencies
```
中，包引用需添加到项目的
```
packageReferences
```
中
在SPM包引用中设置
```
minimumVersion
```
之前，请查看
```
https://github.com/PostHog/posthog-ios/releases
```
上posthog-ios的最新版本——切勿硬编码过时版本
如果项目使用App Sandbox（macOS），需在目标的构建设置中添加
```
ENABLE_OUTGOING_NETWORK_CONNECTIONS = YES
```
，以便PostHog能够连接到其服务器——请勿完全禁用沙箱

Identifying users

用户识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using

X-POSTHOG-DISTINCT-ID

and

X-POSTHOG-SESSION-ID

headers to maintain correlation.

在登录和注册事件中识别用户。请参考示例代码和文档，了解适用于此框架的正确识别模式。如果同时存在前端和后端代码，请使用

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

标头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

在相关文件中添加PostHog错误追踪，尤其是关键用户流程和API边界附近。