gleap-sdk-setup

Gleap SDK 设置

指导用户将 Gleap SDK 集成到项目中。支持 JavaScript、iOS、Android、React Native、Flutter、Ionic/Capacitor、Cordova 和 FlutterFlow。

平台检测

继续操作前，检测用户的平台。如果用户明确说明了平台，则跳过检测。

自动检测优先级

按以下顺序检查（以第一个匹配项为准）：

1. 是否存在 pubspec.yaml？

   • 包含 flutterflow 引用，或用户提到 FlutterFlow -> FlutterFlow（platform-flutterflow.md）
   • 否则 -> Flutter（platform-flutter.md）

2. 是否存在 package.json？ 读取该文件并检查 dependencies 和 devDependencies：

   • 存在 react-native -> React Native（platform-react-native.md）
   • 存在 @capacitor/core 或 capacitor-core -> Ionic/Capacitor（platform-ionic-capacitor.md）
   • 存在 cordova，或存在包含 <widget> 的 config.xml -> Cordova（platform-cordova.md）
   • 存在 @angular/core -> JavaScript（Angular）
   • 存在 react（但不存在 react-native）-> JavaScript（React）
   • 存在 vue -> JavaScript（Vue）
   • 存在 next -> JavaScript（Next.js）
   • 存在 nuxt -> JavaScript（Nuxt）
   • 其他情况或未使用框架 -> JavaScript（通用 npm）
   • 所有 JavaScript 变体均使用 platform-javascript.md

3. 是否存在 *.xcodeproj、*.xcworkspace 或 Podfile？ -> iOS（platform-ios.md）

4. 是否存在 build.gradle、build.gradle.kts 或 app/build.gradle？ -> Android（platform-android.md）

5. 是否存在 index.html（且不存在 package.json）？ -> JavaScript CDN 方式（platform-javascript.md）

6. 是否检测到服务端 Web 框架？ 这些框架的客户端均使用 JavaScript SDK（platform-javascript.md）：

   • 存在 composer.json（PHP / Laravel）— 根据是否存在 JS 构建流水线，使用 CDN 或 npm
   • 存在包含 rails 的 Gemfile（Ruby on Rails）— 在布局文件中使用 CDN；如果存在 Webpacker/esbuild/importmap，则使用 npm
   • requirements.txt / pyproject.toml 中包含 django 或 flask（Python）— 在基础模板中使用 CDN
   • 存在 *.cshtml / *.csproj 文件（.NET / ASP.NET）— 在布局视图中使用 CDN
   • pom.xml / build.gradle 中包含 Spring Boot（Java）— 在 Thymeleaf 模板中使用 CDN
   • 任何其他 Web 框架（Go、Elixir/Phoenix 等）— 使用 CDN 方式
   • 注意：如果项目还包含使用前端框架的 package.json，步骤 2 已涵盖这种情况。

7. 未检测到任何内容 -> 询问用户计划使用哪个平台。

检测命令

使用 Glob 扫描关键文件：

• pubspec.yaml
• package.json
• **/*.xcodeproj
• **/*.xcworkspace
• Podfile
• build.gradle
• build.gradle.kts
• app/build.gradle
• config.xml
• index.html
• composer.json
• Gemfile
• requirements.txt
• pyproject.toml

如果找到 package.json，使用 Read 检查其 dependencies 和 devDependencies 键。

API 密钥解析

询问用户 API 密钥前，按以下顺序检查这些位置：

1. 用户已在对话中提供（例如，“添加 Gleap，令牌为 abc123”）— 直接使用
2. 项目根目录中的 .env 文件 — 查找 GLEAP_API_KEY=...
3. 环境变量 — 通过 echo $GLEAP_API_KEY 检查是否已设置 GLEAP_API_KEY
4. 未找到 — 请用户提供 API 密钥（可在 https://app.gleap.io 的 Project Settings > Security > API Key 中获取）

找到或收到密钥后，提出将其保存到项目的 .env 文件中（如有需要则创建该文件；如果 .gitignore 尚未包含 .env，则将其添加进去），以便今后使用。

工作流

按顺序执行以下步骤：

1. 获取最新 SDK 版本：在此技能目录中运行 scripts/get-latest-versions.sh。在所有安装命令中使用返回的版本，不要使用硬编码的版本号。
2. 检测平台：使用上文的优先级规则。
3. 解析 API 密钥：使用上文的 API 密钥解析步骤。
4. 向用户确认：说明检测到的平台并请求确认。如果用户已指定平台，则跳过此步骤。
5. 阅读平台指南：从此技能目录中读取匹配的 platform-{name}.md 文件。
6. 安装 SDK：引导用户使用步骤 1 中的最新版本安装依赖。获得用户批准后运行安装命令。验证安装是否成功。
7. 初始化 SDK：使用解析出的 API 密钥添加初始化代码。
8. 配置平台：根据平台指南应用所需的权限、清单条目或其他配置。
9. 验证：建议构建或运行项目，以确认集成正常。

设置后的 API 指南

设置完成后，如果用户询问如何使用 Gleap API，请参阅相关平台文件中的“常见 API 用法”部分。最常见的任务包括：

• 识别用户：将会话与用户数据（姓名、电子邮件、套餐、自定义数据）关联
• 跟踪事件：在应用的关键节点记录自定义事件
• 自定义数据：为反馈工单附加上下文数据
• 控制小组件：以编程方式打开或关闭 Gleap 小组件

请重新阅读平台文件中的 API 部分，确认正确的方法签名，因为不同平台的方法签名有所不同。

重要说明

• 在应用生命周期中，必须且只能调用一次 initialize()
• 对于跨平台框架（React Native、Flutter、Ionic/Capacitor），需要同时配置 iOS 和 Android 平台专属设置（权限）
• JavaScript CDN 方式适用于任何 Web 环境，且不需要 npm
• 若要进行身份验证，用户哈希必须使用项目的密钥在服务器端生成
• 自定义数据仅支持基本类型（字符串、数字、布尔值），最多支持 35 个键

常见故障排除

• pod install 失败：先运行 pod repo update，然后重试
• Gradle 同步失败：确保 minSdkVersion 至少为 21
• Flutter 版本冲突：在 AndroidManifest.xml 中添加 tools:overrideLibrary="io.gleap.gleap_sdk"
• Web 上未显示小组件：检查内容安全策略标头是否允许 sdk.gleap.io
• 软重载会清除小组件（Rails/Turbo）：重载后调用 Gleap.getInstance().softReInitialize()
• Android 硬件加速：不要在应用级别设置 android:hardwareAccelerated="false"