gleap-sdk-setup

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):

1. pubspec.yaml exists?

   • Contains flutterflow references or user mentions FlutterFlow -> FlutterFlow (platform-flutterflow.md)
   • Otherwise -> Flutter (platform-flutter.md)

2. 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

3. *.xcodeproj, *.xcworkspace, or Podfile exists? -> iOS (platform-ios.md)

4. build.gradle, build.gradle.kts, or app/build.gradle exists? -> Android (platform-android.md)

5. index.html exists (no package.json)? -> JavaScript CDN approach (platform-javascript.md)

6. 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.

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

If 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:

1. User provided it in the conversation (e.g., "add Gleap with token abc123") — use it directly
2. .env file in the project root — look for GLEAP_API_KEY=...
3. Environment variable — check if GLEAP_API_KEY is set via echo $GLEAP_API_KEY
4. 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 to .gitignore if not already there) so it's available for future use.

Workflow

Follow these steps in order:

1. 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.
2. Detect platform using the priority rules above.
3. Resolve API key using the API Key Resolution steps above.
4. Confirm with user: State the detected platform and ask for confirmation. If the user already specified a platform, skip this step.
5. Read platform guide: Read the matching platform-{name}.md file from this skill's directory.
6. 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.
7. Initialize SDK: Add initialization code using the resolved API key.
8. Configure platform: Apply required permissions, manifest entries, or additional config from the platform guide.
9. 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