gleap-sdk-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gleap SDK Setup

Gleap SDK 配置指南

Guides users through integrating the Gleap SDK into their project. Supports JavaScript, iOS, Android, React Native, Flutter, Ionic/Capacitor, Cordova, and FlutterFlow.

引导用户将Gleap SDK集成到自己的项目中。支持JavaScript、iOS、Android、React Native、Flutter、Ionic/Capacitor、Cordova以及FlutterFlow平台。

Platform Detection

平台检测

Detect the user's platform before proceeding. If the user explicitly states their platform, skip detection.

在开始操作前先检测用户的平台。如果用户已明确说明平台，则跳过检测步骤。

Auto-Detection Priority

自动检测优先级

Check in this order (first match wins):

pubspec.yaml
exists?
- Contains
```
flutterflow
```
  references or user mentions FlutterFlow -> FlutterFlow (
```
platform-flutterflow.md
```
  )
- Otherwise -> Flutter (
```
platform-flutter.md
```
  )
package.json
exists? Read it and check
```
dependencies
```
+
```
devDependencies
```
:
- ```
react-native
```
  present -> React Native (
```
platform-react-native.md
```
  )
- ```
@capacitor/core
```
  or
```
capacitor-core
```
  present -> Ionic/Capacitor (
```
platform-ionic-capacitor.md
```
  )
- ```
cordova
```
  present, or
```
config.xml
```
  exists with
```
<widget>
```
  -> Cordova (
```
platform-cordova.md
```
  )
- ```
@angular/core
```
  present -> JavaScript (Angular)
- ```
react
```
  present (without
```
react-native
```
  ) -> JavaScript (React)
- ```
vue
```
  present -> JavaScript (Vue)
- ```
next
```
  present -> JavaScript (Next.js)
- ```
nuxt
```
  present -> JavaScript (Nuxt)
- Other or no framework -> JavaScript (generic npm)
- Use
```
platform-javascript.md
```
  for all JavaScript variants

*.xcodeproj
,
*.xcworkspace
, or
Podfile
exists? -> iOS (

platform-ios.md

)

build.gradle
,
build.gradle.kts
, or
app/build.gradle
exists? -> Android (

platform-android.md

)

index.html
exists (no
package.json
)? -> JavaScript CDN approach (

platform-javascript.md

)

Server-side web framework detected? These all use the JavaScript SDK on the client side (
```
platform-javascript.md
```
):
- ```
composer.json
```
  exists (PHP / Laravel) — use CDN or npm depending on whether a JS build pipeline exists
- ```
Gemfile
```
  with
```
rails
```
  (Ruby on Rails) — use CDN in layouts, or npm if Webpacker/esbuild/importmap is present
- ```
requirements.txt
```
  /
```
pyproject.toml
```
  with
```
django
```
  or
```
flask
```
  (Python) — use CDN in base templates
- ```
*.cshtml
```
  /
```
*.csproj
```
  files (.NET / ASP.NET) — use CDN in layout views
- ```
pom.xml
```
  /
```
build.gradle
```
  with Spring Boot (Java) — use CDN in Thymeleaf templates
- Any other web framework (Go, Elixir/Phoenix, etc.) — use CDN approach
- Note: If the project also has a
```
package.json
```
  with a frontend framework, step 2 already covers this.
Nothing detected -> Ask the user which platform they are targeting.

按以下顺序进行检测（匹配到第一个符合条件的即停止）：

是否存在
pubspec.yaml
？
- 包含
```
flutterflow
```
  相关引用或用户提及FlutterFlow → FlutterFlow（对应
```
platform-flutterflow.md
```
  ）
- 否则 → Flutter（对应
```
platform-flutter.md
```
  ）
是否存在
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
```

是否存在
*.xcodeproj
、
*.xcworkspace
或
Podfile
？ → iOS（对应

platform-ios.md

）

是否存在
build.gradle
、
build.gradle.kts
或
app/build.gradle
？ → Android（对应

platform-android.md

）

是否存在
index.html
（无
package.json
）？ → JavaScript（CDN方式，对应
```
platform-javascript.md
```
）
检测到服务端Web框架？ 这些框架均在客户端使用JavaScript SDK（对应
```
platform-javascript.md
```
）：
- 存在
```
composer.json
```
  （PHP / Laravel）—— 根据是否有JS构建流水线选择CDN或npm方式
- 存在包含
```
rails
```
  的
```
Gemfile
```
  （Ruby on Rails）—— 在布局中使用CDN，若存在Webpacker/esbuild/importmap则使用npm方式
- 存在包含
```
django
```
  或
```
flask
```
  的
```
requirements.txt
```
  /
```
pyproject.toml
```
  （Python）—— 在基础模板中使用CDN
- 存在
```
*.cshtml
```
  /
```
*.csproj
```
  文件（.NET / ASP.NET）—— 在布局视图中使用CDN
- 存在包含Spring Boot的
```
pom.xml
```
  /
```
build.gradle
```
  （Java）—— 在Thymeleaf模板中使用CDN
- 其他Web框架（Go、Elixir/Phoenix等）—— 使用CDN方式
- 注意：若项目同时包含带有前端框架的
```
package.json
```
  ，则步骤2已覆盖此情况
未检测到任何平台 → 询问用户目标平台

Detection Commands

检测命令

Use

Glob

to scan for key files:

```
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

is found, use

Read

to inspect its

dependencies

and

devDependencies

keys.

使用

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 Key Resolution

API密钥获取

Before asking the user for their API key, check these locations in order:

User provided it in the conversation (e.g., "add Gleap with token abc123") — use it directly
.env
file in the project root — look for
```
GLEAP_API_KEY=...
```
Environment variable — check if
```
GLEAP_API_KEY
```
is set via
```
echo $GLEAP_API_KEY
```
Not found — ask the user to provide their API key (available at https://app.gleap.io under Project Settings > Security > API Key)

When a key is found or provided, offer to save it to the project's

.env

file (creating it if needed, and adding

.env

.gitignore

if not already there) so it's available for future use.

在向用户索要API密钥前，按以下顺序检查位置：

对话中用户已提供（例如：“使用令牌abc123添加Gleap”）—— 直接使用该密钥
项目根目录的
.env
文件—— 查找
```
GLEAP_API_KEY=...
```
环境变量—— 通过
```
echo $GLEAP_API_KEY
```
检查是否设置了
```
GLEAP_API_KEY
```
未找到—— 请求用户提供API密钥（可在https://app.gleap.io的项目设置>安全>API密钥中获取）

找到或获取密钥后，建议将其保存到项目的

.env

文件中（若文件不存在则创建，并在

.gitignore

中添加

.env

（若尚未添加）），以便后续使用。

Workflow

工作流程

Follow these steps in order:

Fetch latest SDK versions: Run
```
scripts/get-latest-versions.sh
```
from this skill's directory. Use the returned versions in all install commands instead of hardcoded version numbers.
Detect platform using the priority rules above.
Resolve API key using the API Key Resolution steps above.
Confirm with user: State the detected platform and ask for confirmation. If the user already specified a platform, skip this step.
Read platform guide: Read the matching
```
platform-{name}.md
```
file from this skill's directory.
Install SDK: Walk the user through installing the dependency using the latest version from step 1. Run install commands when the user approves. Verify installation succeeded.
Initialize SDK: Add initialization code using the resolved API key.
Configure platform: Apply required permissions, manifest entries, or additional config from the platform guide.
Verify: Suggest building/running the project to confirm integration works.

按以下顺序执行步骤：

获取最新SDK版本：运行此skill目录下的
```
scripts/get-latest-versions.sh
```
脚本。在所有安装命令中使用返回的版本号，而非硬编码版本。
检测平台：使用上述优先级规则检测平台
获取API密钥：按照上述API密钥获取步骤执行
与用户确认：告知检测到的平台并请求确认。若用户已指定平台，则跳过此步骤
读取平台指南：从skill目录中读取匹配的
```
platform-{name}.md
```
文件
安装SDK：引导用户使用步骤1获取的最新版本安装依赖。获得用户批准后运行安装命令，并验证安装是否成功
初始化SDK：添加使用已获取API密钥的初始化代码
配置平台：根据平台指南应用所需权限、清单条目或其他配置
验证：建议构建/运行项目以确认集成成功

Post-Setup API Guidance

集成后API使用指南

After setup, if the user asks about using the Gleap API, refer to the "Common API Usage" section in the relevant platform file. The most common tasks are:

Identify users: Associate sessions with user data (name, email, plan, custom data)
Track events: Log custom events at key points in the app
Custom data: Attach contextual data to feedback tickets
Widget control: Programmatically open/close the Gleap widget

Re-read the platform file's API section for the correct method signatures, as they differ between platforms.

配置完成后，若用户询问Gleap API的使用方法，请参考对应平台文件中的“常见API使用”章节。最常见的操作包括：

用户标识：将会话与用户数据（姓名、邮箱、套餐、自定义数据）关联
事件追踪：在应用关键节点记录自定义事件
自定义数据：向反馈工单附加上下文数据
控件控制：以编程方式打开/关闭Gleap控件

请重新阅读平台文件的API章节以获取正确的方法签名，不同平台的方法会有所差异。

Important Notes

重要说明

```
initialize()
```
must be called exactly once in the application lifecycle
For cross-platform frameworks (React Native, Flutter, Ionic/Capacitor), both iOS and Android platform-specific configuration (permissions) is needed
The JavaScript CDN approach works for any web context and does not require npm
For identity verification, the user hash must be generated server-side using the project's secret key
Custom data supports only primitive values (strings, numbers, booleans) with a max of 35 keys

```
initialize()
```
必须在应用生命周期中恰好调用一次
对于跨平台框架（React Native、Flutter、Ionic/Capacitor），需同时配置iOS和Android的平台特定权限
JavaScript CDN方式适用于任何Web环境，无需npm
身份验证需使用项目密钥在服务端生成用户哈希
自定义数据仅支持原始值（字符串、数字、布尔值），最多包含35个键

Common Troubleshooting

常见问题排查

pod install
fails: Run
```
pod repo update
```
first, then retry
Gradle sync fails: Ensure
```
minSdkVersion
```
is at least 21
Flutter version conflict: Add
```
tools:overrideLibrary="io.gleap.gleap_sdk"
```
to AndroidManifest.xml
Widget not showing on web: Check Content Security Policy headers allow
```
sdk.gleap.io
```
Soft-reload clears widget (Rails/Turbo): Call
```
Gleap.getInstance().softReInitialize()
```
after reload
Android hardware acceleration: Do not set
```
android:hardwareAccelerated="false"
```
at application level

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"
```