Gleap SDK Setup

Guides users through integrating the Gleap SDK into their project. Supports JavaScript, iOS, Android, React Native, Flutter, Ionic/Capacitor, Cordova, and 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.

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.

API Key Resolution

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.

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.

Post-Setup API Guidance

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.

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

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

gleap-sdk-setup

NPX Install

Tags

SKILL.md Content