contentsquare-ios-sdk

Name: contentsquare-ios-sdk
Author: contentsquare

github.com/contentsquare开发238 次安装6 天前更新

代码仓库

关于 contentsquare-ios-sdk

帮助 AI Agent 在 iOS 应用中集成或升级 Contentsquare SDK 的技能。它涵盖项目健康检查、初始化、隐私同意、屏幕与交易追踪、会话回放遮罩及 WebView 注册等步骤。

主要功能

01按数据源 ID 或 Bundle ID 检查项目配置
02指导 SPM 与 CocoaPods 安装
03配置 SDK 启动与用户同意
04追踪屏幕、交易、事件和身份
05设置会话回放隐私遮罩
06注册 WebView 并配置应用内功能

适用场景

01在 iOS 应用中接入 Contentsquare SDK
02升级或排查 SDK 配置
03实现屏幕与购买事件追踪
04设置会话回放的敏感内容遮罩

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/contentsquare/agents --skill contentsquare-ios-sdk

安装后在 Claude Code 中输入/contentsquare-ios-sdk确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

api-reference.md

ios-in-app-features.md

session-replay.md

xcode-project-setup.md

scripts/xcode_spm_setup/

.gitignore

Package.swift

scripts/xcode_spm_setup/Sources/

main.swift

详细介绍

Contentsquare iOS SDK 集成

此技能可帮助 AI Agent 在客户端应用中集成或升级 Contentsquare iOS SDK。

强制第一步——Contentsquare 项目健康检查

在一次对话中进行任何 Contentsquare 相关工作之前——包括集成、调试、配置问题和代码更改——都必须运行此健康检查，且每次对话只运行一次。不要跳过，也不要推迟到任务后续阶段。

先告知用户。 告诉用户你将要做什么，例如：

“开始之前，我会快速检查你的 Contentsquare 项目：我会询问你的数据源 ID（如果没有，则读取应用的 bundle ID），调用 Contentsquare 健康检查端点，并向你展示当前项目配置。之后我们再继续。”
先向用户询问 Contentsquare 数据源 ID。 例如：“你有 Contentsquare 数据源 ID 吗？可能有一个，也可能有多个。” 只使用用户提供的 ID，绝不要自行编造。
- 用户提供一个或多个数据源 ID → 仅通过数据源 ID 检查（v3）。跳过第 3 步。
- 用户只有环境 ID → 仅通过 bundle ID 检查（v2）：环境 ID 不是数据源 ID，不能用于 v3 路径。
- 用户没有、不知道或跳过此问题 → 仅通过 bundle ID 检查（v2）。
解析 bundle ID（仅在没有数据源 ID 时）。 从 Xcode 项目（*.xcodeproj/project.pbxproj）中读取 PRODUCT_BUNDLE_IDENTIFIER，或从 Info.plist 中读取 CFBundleIdentifier。使用前，将所有 $(...) 构建设置变量解析为其字面值。
调用端点——只能使用一个版本，绝不能同时使用两个版本。 平台字段必须是 ios，不接受其他值。

使用数据源 ID（v3）时，每个 ID 调用一次：
```
curl -s "https://mobile-production.content-square.net/healthcheck/ios/config/v3/<dataSourceId>.json"
```
如果某个 ID 未返回 200，请告知用户——该 ID 可能是环境 ID，也可能存在拼写错误——并询问是否可以自行在代码中查找数据源 ID：该 ID 是传递给 CSQ.start(dataSourceID:) 的值（如果它来自常量或配置文件，则继续追溯到其字面值）。如果用户同意且你找到了另一个 ID，则使用该 ID 运行一次 v3 检查。如果用户拒绝，或者代码中没有该 ID，则继续后续操作。

没有数据源 ID 时（v2）：
```
curl -s "https://mobile-production.content-square.net/healthcheck/ios/config/v2/<bundleId>.json"
```

简要汇总每次返回 200 的调用所对应的以下值：

报告项	JSON 路径
项目 ID	`cs_project_id`
跟踪是否启用	`project_configurations.project_config.enabled`
Session Replay	`project_configurations.project_config.session_replay`——`recording_rate`、`record_via_cellular_network`、`recording_quality_wifi`、`srm_enabled`、`user_identifier`
已启用的功能标记	`project_configurations.project_config.feature_flags`——仅列出 `enabled == true` 的条目，并提供 `name` 和 `min_version`

对于 v3 调用，还要报告环境 ID（environment_id）。如果响应内容不同，请明确指出。

然后继续处理用户的实际请求。

失败处理。 403 Invalid health-check path 表示 URL 格式错误——请重新检查 ios 字段、v2/v3 字段和 ID，不要更改路径结构。上游代理返回的非 200 响应表示该数据源 ID 或 bundle ID 没有 Contentsquare 配置：请如实告知用户，然后继续操作——不要改用另一个版本重试（唯一允许的重试方式是第 4 步中的代码查找）。此健康检查仅供参考，绝不能阻碍用户任务。

安装

Swift Package Manager（推荐）

请参阅 xcode-project-setup，添加 https://github.com/ContentSquare/apple-sdk

CocoaPods

pod 'ContentsquareSDK'

然后运行 pod install。

快速入门

import ContentsquareSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        CSQ.start(dataSourceID: "your-data-source-id") // or start(environmentID:) if no data source ID
        CSQ.optIn() // TODO: Only call after user consent. The SDK stays inactive until optIn() is called. Implement a consent prompt and call optIn()/optOut() based on user choice.
        return true
    }
}

SwiftUI：

import ContentsquareSDK

@main
struct MyApp: App {
    init() {
        CSQ.start(dataSourceID: "your-data-source-id") // or start(environmentID:) if no data source ID
        CSQ.optIn() // TODO: Only call after user consent. The SDK stays inactive until optIn() is called. Implement a consent prompt and call optIn()/optOut() based on user choice.
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

如需仅使用 DXA（不包含 Product Analytics），请使用不带参数的 CSQ.start()。

屏幕追踪非常重要，否则 Session Replay 将无法正常工作。你可以在 viewWillAppear(_:)（UIKit）或 .onAppear（SwiftUI）中使用 trackScreenview() 手动追踪屏幕：

CSQ.trackScreenview("HomeScreen")

在完成集成之前，请确保处理应用中存在的 WebView。WebView 不会自动追踪，必须逐一注册。详情请查看下方的 WebView 追踪部分。

集成工作流

将 Contentsquare 集成到 iOS 应用时，请按以下顺序操作：

添加依赖项 -- SPM：https://github.com/ContentSquare/apple-sdk.git，或 CocoaPods：pod 'ContentsquareSDK'。
启动 SDK -- 在 application(_:didFinishLaunchingWithOptions:) 或 App.init() 中调用 CSQ.start(dataSourceID:)（首选）或 CSQ.start(environmentID:)。如需仅使用 DXA，请使用 CSQ.start()。
实现同意流程 -- 添加 CSQ.optIn()，并附上 TODO 注释，提示客户自行管理同意流程。在调用 optIn() 之前，SDK 将保持非活动状态。
设置屏幕追踪 -- 在每次屏幕出现时调用 CSQ.trackScreenview(_:)（例如在 viewWillAppear、.onAppear 中）。
追踪交易 -- 购买时使用 CSQ.trackTransaction(Transaction(id:, value:, currency:))。
配置 Session Replay 遮罩 -- 使用 CSQ.setDefaultMasking(true) 进行全局设置，然后使用 CSQ.unmask(view) / CSQ.mask(view)，或对敏感内容使用 SwiftUI .csqMaskContents(true)。
设置错误追踪 -- 使用 CSQ.onCrashReporterStart { } 与第三方崩溃报告工具协调。
注册 WebView -- 为每个 WKWebView 实例调用 CSQ.registerWebView(webView)。
添加身份信息 -- 对于 Product Analytics，使用 identify()；对于 Experience Analytics，使用 sendUserIdentifier()。
配置应用内功能 -- 添加自定义 URL scheme 并处理 deeplink。此步骤为必需项，才能使用截图采集、SDK 日志、Log Visualizer 和 Zoning Analysis。请参阅 references/ios-in-app-features.md。

API 一览

始终使用 import ContentsquareSDK 中的 CSQ。Contentsquare 类属于旧版 SDK，不应使用。

生命周期

方法	用途
`start()`	启动 SDK。必须在调用任何其他 API 之前调用。
`stop()`	完全关闭 SDK。
`pauseTracking()`	暂停数据采集（用于敏感屏幕）。
`resumeTracking()`	在调用 `pauseTracking()` 后恢复采集。

除非有明确要求，否则请避免使用 pauseTracking 和 resumeTracking。

启动配置

方法	使用场景	接入优先级
`start(dataSourceID:, options:)`	使用数据源 ID，同时启用 DXA 和 Product Analytics	新客户的首选 -- 优先询问此项
`start(environmentID:, options:)`	使用环境 ID 启用 Product Analytics	若没有数据源 ID，则作为第二选择
`start(options:)`	仅使用 Digital Experience Analytics	仅作备用 -- 在两种 ID 均不可用或明确要求仅使用 DXA 时使用

建议的接入流程：

询问用户：“你有 Contentsquare 数据源 ID 吗？”（如果用户在健康检查期间已回答，则跳过此问题）。如果有，请使用 CSQ.start(dataSourceID: "your-data-source-id")。
如果没有，询问：“你有环境 ID 吗？” 如果有，请使用 CSQ.start(environmentID: "your-env-id")。
只有在两种 ID 均不可用（或用户明确希望仅使用 DXA）时，才使用 CSQ.start() 作为备用方案。

不要编造 ID。不要在未询问的情况下默默默认使用 DXA。

选项包括：.uploadInterval、.baseURL、.disablePageviewAutocapture、.enableNativeAutocapture、.enablePushNotificationAutocapture、.sessionReplayAutoStart。

隐私

方法	用途
`optIn()`	选择加入设备跟踪。生成用户 ID，并立即开始。
`optOut()`	永久选择退出。停止跟踪，直到调用 `optIn()` 或重新安装应用。

身份

方法	上下文	用途
`identify("userId")`	产品分析	设置用户身份。不同的 ID 会触发新会话。最多 255 个字符。
`resetIdentity()`	产品分析	清除身份。
`sendUserIdentifier("userId")`	数字体验分析	发送经过哈希处理的用户 ID。最多 100 个字符。

屏幕跟踪

方法	用途
`trackScreenview(_:, cvars:)`	跟踪屏幕浏览，可选自定义变量。

CustomVar(index:, name:, value:) -- index（UInt32）、name（String，最多 512 个字符）、value（String，最多 255 个字符）。

交易

let transaction = Transaction(id: "order_123", value: 29.99, currency: .usd)
CSQ.trackTransaction(transaction)

Currency 是 ISO 4217 枚举（例如，.usd、.eur、.gbp）。

自定义事件和属性

方法	用途
`trackEvent(_:, properties:)`	跟踪具名事件，可选属性。
`addDynamicVar(DynamicVar)`	添加会话级动态变量（EA）。
`addUserProperties([String: PropertyValue])`	设置用户级属性（PA）。
`addEventProperties([String: PropertyValue])`	为所有后续事件设置属性（PA）。
`removeEventProperty("key")`	移除一个事件属性。
`clearEventProperties()`	移除所有事件属性。

Swift 中的 PropertyValue：String、Substring、Bool、Double、Float、Int、Int64、Int32、Int16、Int8。

DynamicVar(key:, value:) -- value 为 String（key 最多 512 个字符，value 最多 255 个字符）或 UInt32（key 最多 50 个字符）。

会话回放屏蔽

方法	用途
`setDefaultMasking(Bool)`	设置全局屏蔽状态。注意：即使设为 `false`，文本输入内容仍会被屏蔽。
`mask(UIView)`	屏蔽指定视图及其子视图。
`unmask(UIView)`	取消屏蔽指定视图。
`mask(viewsOfType: UIView.Type)`	屏蔽指定类型的所有视图（DXA）。
`unmask(viewsOfType: UIView.Type)`	取消屏蔽指定类型的所有视图（DXA）。
`ignoreInteractions(UIView)`	忽略指定视图上的交互（PA）。
`maskTexts(Bool)`	屏蔽所有文本内容（`UILabel`、SwiftUI `Text`）。
`maskImages(Bool)`	屏蔽所有图像组件（`UIImageView`、SwiftUI `Image`）。
`maskTextInputs(Bool)`	屏蔽所有文本输入字段（`UITextField`、`UITextView`、SwiftUI `TextField`、`SecureField`、`TextEditor`）。

UIKit IBInspectable 属性：view.csqMaskContents = true、view.csqIgnoreInteractions = true、view.csqIgnoreInnerHierarchy = true。

SwiftUI 修饰符：.csqMaskContents(true)、.csqIgnoreInteractions(true)。

WebView 跟踪

方法	用途
`registerWebView(WKWebView)`	注册 WKWebView 以进行跟踪。
`unregisterWebView(WKWebView)`	取消注册 WKWebView。

WebView 不会自动跟踪。必须注册每个 WKWebView 实例。

调查问卷

方法	用途
`triggerSurvey("triggerName")`	根据预定义的触发器名称触发调查问卷（DXA VoC）。

错误跟踪

方法	用途
`onCrashReporterStart { enabled in }`	崩溃报告程序初始化时的回调（DXA）。
`setURLMaskingPatterns(["pattern"])`	屏蔽敏感 URL 路径（DXA）。
`trackNetworkMetric(NetworkMetric)`	跟踪 HTTP 网络错误（DXA）。

CSInApp

必须在应用中配置应用内功能，这些 API 才能正常工作。 如果未设置 URL scheme 和 deeplink 处理器，handle(url:) 将永远不会被触发，应用内功能（截图捕获、SDK 日志、日志可视化工具）也将无法使用。完整设置说明请参阅 references/ios-in-app-features.md。

方法	用途
`handle(url:)`	处理 CSInApp URL scheme 激活（DXA）。在 `application(_:open:options:)` 中调用。
`csInApp`	手动启用或停用应用内调试功能（DXA）的可读写属性。

调试和元数据

API	用途
`logLevel = .debug`	设置日志级别（`.none`、`.error`、`.warn`、`.info`、`.debug`、`.trace`）
`logChannel = customChannel`	将日志路由到自定义日志记录器，替代默认的控制台输出。
`addLogChannel(_:)` / `removeLogChannel(_:)`	在现有日志通道的基础上添加或移除日志通道。
`metadata`	访问会话元数据。
`metadata.onChange { metadata in }`	监听元数据变更。

元数据属性：userID、sessionID、projectID、environmentID、sessionReplayURL、identity。

常见模式

1. 使用产品分析进行完整初始化

import ContentsquareSDK

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    CSQ.start(dataSourceID: "your-data-source-id", options: [.enableNativeAutocapture: true]) // or start(environmentID:) if no data source ID
    CSQ.optIn() // TODO: Only call after user consent
    return true
}

2. 跟踪购买事件

let transaction = Transaction(id: "txn_abc", value: 49.99, currency: .eur)
CSQ.trackTransaction(transaction)

3. 携带属性的自定义事件

CSQ.trackEvent(
    "add_to_cart",
    properties: ["product_id": "sku_123", "quantity": 2, "is_promo": true]
)

4. 崩溃报告器协同工作

CSQ.onCrashReporterStart { enabled in
    if enabled {
        // Start Firebase Crashlytics or other crash reporter here
    }
}

5. SwiftUI 屏幕跟踪

struct ProductDetailView: View {
    var body: some View {
        VStack { /* content */ }
            .onAppear {
                CSQ.trackScreenview("ProductDetail")
            }
    }
}

6. WebView 注册

let webView = WKWebView()
CSQ.registerWebView(webView)
// When done or on deinit:
CSQ.unregisterWebView(webView)

平台指南

UIKit

在 application(_:didFinishLaunchingWithOptions:) 中调用 CSQ.start()。
在 viewWillAppear(_:) 中使用 CSQ.trackScreenview(_:) 跟踪屏幕。
使用 CSQ.mask(view) / view.csqMaskContents = true 遮罩视图。

SwiftUI

在 App.init() 中调用 CSQ.start()。
使用 .onAppear { CSQ.trackScreenview("ScreenName") } 跟踪屏幕。
使用 .csqMaskContents(true) 修饰符遮罩视图。
使用 .csqIgnoreInteractions(true) 忽略交互。

从较早版本的 SDK 迁移

当前 SDK 版本：1.11.x

本节介绍如何从 SDK 1.0–1.6 迁移到 1.11.x。如果要从更早的版本迁移，请应用以下所有更改。这些步骤是累积的——使用 1.0 的项目必须完成每一步。

步骤 1 — 将 SDK 升级到 1.11.x

检查 SDK 是否为最新版本。如果不是，请将 Contentsquare SPM 软件包升级到 1.11.x。
请参阅 xcode-project-setup，了解如何升级 Swift Package。

步骤 2 — 替换已弃用的初始化模式

已移除两步式的 CSQ.configureProductAnalytics(environmentID:, additionalOptions:) + CSQ.start() 模式。请改用统一的 CSQ.start(environmentID:, options:) 或 CSQ.start(dataSourceID:, options:)。

// Old (removed — will not compile in 1.11.x)
CSQ.configureProductAnalytics(environmentID: "your-env-id", additionalOptions: [.enableUIKitAutocapture: true])

// New
CSQ.start(environmentID: "your-env-id", options: [.enableNativeAutocapture: true])

如果项目有数据源 ID（新客户端首选），请改用 start(dataSourceID:)。

步骤 3 — 重命名选项

旧名称	新名称
`.enableUIKitAutocapture`	`.enableNativeAutocapture`
`ProductAnalyticsOption`（类型）	`AnalyticsOption`（`ProductAnalyticsOption` 是已弃用的类型别名——新代码请优先使用 `AnalyticsOption`）

步骤 4 — 删除已移除的选项

以下选项已从 AnalyticsOption 中彻底移除。请从所有 start(...) 或 configureProductAnalytics(...) 调用处删除每一处相关内容——只要还有任何一处保留，项目就无法编译：

.captureVendorID
.captureAdvertiserID
.clearEventPropertiesOnNewUser
.messageBatchByteLimit
.messageBatchMessageLimit
.resumePreviousSession
.pruningLookBackWindow
.disableScreenviewForwardToDXA
.disableScreenviewForwardToPA
.interactionHierarchyCaptureLimit
.disableInteractionTextCapture
.disableInteractionAccessibilityLabelCapture

步骤 5 — 检查 Session Replay 自动启动行为

新增了选项 .sessionReplayAutoStart（默认为 true）。如果你希望使用默认行为，无需执行任何操作。只有在需要手动控制 Session Replay 时，才将其设为 false：

CSQ.start(environmentID: "your-env-id", options: [.sessionReplayAutoStart: false])
// Then start/stop manually:
CSQ.startSessionReplay()
CSQ.stopSessionReplay() // terminal — cannot be restarted in the same SDK lifetime

迁移清单（1.0–1.6 → 1.11.x）

SPM 软件包已更新至 1.11.x
已将 configureProductAnalytics + start() 替换为统一的 CSQ.start(environmentID:options:) 或 CSQ.start(dataSourceID:options:)
已将 .enableUIKitAutocapture 重命名为 .enableNativeAutocapture
已将 ProductAnalyticsOption 类型引用重命名为 AnalyticsOption
已从每个调用位置删除所有已移除的选项
构建成功，且没有与上述内容相关的已弃用 API 警告

应用内功能（必须设置）

应用内功能（截图采集、SDK 日志、日志可视化工具、区域分析）对于 Contentsquare 用户验证和调试集成至关重要。这些功能并非可选——如果没有此设置，Contentsquare 用户将无法使用这些工具。

需要完成两个步骤：

将 cs-$(PRODUCT_BUNDLE_IDENTIFIER) URL scheme 添加到 Info.plist。
在相应的深层链接处理程序（AppDelegate、SceneDelegate 或 SwiftUI 中的 .onOpenURL）中调用 CSQ.handle(url: url)。

集成 SDK 时，请务必包含此设置。完整的实现指南请参阅 references/ios-in-app-features.md。

重要限制

按以下顺序询问 ID：集成前，询问用户 (1) 是否有 Contentsquare 数据源 ID（复用健康检查的回答）——新客户端优先使用此 ID。(2) 如果没有，询问是否有环境 ID。(3) 只有在两者都没有（或用户明确只需要 DXA）时，才改用 CSQ.start()。不要虚构 ID，也不要在未询问的情况下默认使用 DXA。
扫描 WebView：集成期间，搜索代码库中是否使用了 WKWebView。WebView 不会自动被跟踪——每个实例都必须通过 CSQ.registerWebView(_:) 注册。不要跳过此步骤。
应用内功能必须设置：务必配置 URL scheme（cs-$(PRODUCT_BUNDLE_IDENTIFIER)）和 CSQ.handle(url:) 深层链接处理程序。否则，Contentsquare 用户将无法使用截图采集、SDK 日志、日志可视化工具或区域分析。请参阅 references/ios-in-app-features.md。
平台支持：仅支持 iOS。请查看兼容性文档。
属性类型：仅接受 String、Bool 和数值类型作为 PropertyValue。
DynamicVar 限制：String 变体：键最多 512 个字符，值最多 255 个字符。Int 变体：键最多 50 个字符，值为 UInt32。
userIdentifier：identify() 最多 255 个字符，sendUserIdentifier() 最多 100 个字符。
隐私：切勿自动选择加入。务必实现同意流程。
PII：切勿在屏幕名称、事件名称或属性中传入电子邮件地址、密码或真实姓名。
环境 ID：切勿硬编码——请使用配置或环境变量。

集成检查清单

在确认集成完成前，请核实：

参考资料

完整的方法签名和参数详情：references/api-reference.md
Session Replay 深入说明（遮罩、已知限制）：references/session-replay.md
应用内功能设置（必需）：references/ios-in-app-features.md
官方 iOS 应用内功能文档
官方 iOS 文档
iOS 兼容性

支持 Markdown

登录后评论

基本信息

作者: contentsquare
仓库: contentsquare/agents
分类: 开发
安装次数: 38
GitHub Stars: 2

报告问题