Guide for AI Coding Agents to Integrate Luciq on Android
⚠️ UNIVERSAL EXECUTION RULES ⚠️
Critical Rules - Apply to ALL Platforms:
NEVER skip WAIT instructions — always get user confirmation before proceeding
NEVER auto-execute optional steps — user must explicitly select them
ALWAYS fetch latest SDK version before integration (DO NOT use placeholders like 1.0.0)
ALL API parameters must be included (can be nil/null) — never omit parameters
Execution Guidelines:
Be specific and concise — save tokens by being to the point
Don't create documentation files — only code files required for integration
Implement mandatory steps sequentially — complete each before moving to the next
Prompt user with current step — describe what's happening, then proceed when done
Only ask for optional steps after mandatory ones — show numbered list for selection
Use numbered lists for all options — makes selection easier (e.g., "Select 1", "Select 2")
Add wrap up step — execute validation only when user selects "Wrap up & validate"
Check documentation first — confirm API availability before getting creative beyond examples
Official Documentation:
Main docs: https://docs.luciq.ai/
Always check official docs when unsure about API signatures or platform specifics
Integration Workflow Overview
Step 2: Add SDK Dependency (Platform-Specific)
Fetch latest version from GitHub API
Step 3: Initialize the SDK (Platform-Specific)
Default: shake + floatingButton
Step 3B: Configure Network Interception [ANDROID ONLY]
Enable unified network interception in Gradle
Step 1 — Collect Required Information [MANDATORY]
1A: Get App Token
Check MCP Server First:
Validation:
Token should be non-empty
Typically 32-40 character hexadecimal string
If invalid format, warn user but proceed
1B: Determine Integration Method
Auto-Detection Logic:
Detect package managers in project:
iOS: Podfile, Cartfile, SPM packages in .xcodeproj, or none → Manual
Android: build.gradle with repositories, pom.xml, or none → Manual
For Android, detection checks:
build.gradle / build.gradle.kts → Gradle
pom.xml → Maven
Integration Method Menu (if multiple/none detected):
Gradle (Recommended)
Maven
1C: Apply Default Configuration (Inform + Opt-in)
Default configuration is applied automatically. Inform the user:
Store default configuration:
If user wants to customize (yes), follow the CUSTOMIZATION LOOP:
If user does not want to customize (no): Proceed to Step 2
1D: APM (Application Performance Monitoring) — Android Only
Step 2 — Add SDK Dependency [MANDATORY - ANDROID]
MUST FETCH LATEST VERSION FIRST:
Fetch latest version from GitHub API: https://api.github.com/repos/luciqai/luciq-android-sdk/releases/latest
Extract version number from the "tag_name" field (e.g., "19.1.0")
Store version for dependency configuration
DO NOT use placeholder versions like "1.0.0" or "latest"
Android Implementation Notes:
If integration_method == gradle, apply Luciq Gradle plugins and dependencies.
Part A: Gradle Plugins (Kotlin DSL / Groovy examples)
Kotlin (project-level build.gradle.kts)
Groovy (project-level build.gradle)
App-level (Kotlin DSL)
Note: If project uses Firebase Performance Monitoring, ensure Luciq plugins are declared BEFORE Firebase:
Part B: Add Dependencies
Kotlin (app-level build.gradle.kts)
Groovy (app-level build.gradle)
Maven (if using Maven)
Automatic Permissions: SDK adds these to AndroidManifest.xml automatically:
Important: Use exact version in Gradle (do not use + or ranges).
Step 3 — Initialize the SDK [MANDATORY - ANDROID]
IMPORTANT: The SDK initialization MUST be the FIRST code executed in onCreate() (immediately after super.onCreate()). This ensures Luciq captures all app activity from the very start.
Part A: Detect or Create Application Class
Search for classes extending Application and check AndroidManifest.xml for android:name in .
If none found, create MyApplication class and register it in AndroidManifest.xml.
Part B: Initialize Luciq SDK
If NO existing Application class — Create new (Kotlin example):
Register in AndroidManifest.xml:
If existing Application class — Update onCreate():
Part C: APM Configuration (If apm_enabled)
In app-level build.gradle(-kts) configure luciq.apm settings. Example (Kotlin DSL):
Note: APM's network capture is for performance monitoring only. You MUST still add the network interception configuration (Step 3B) for network logs to appear in bug reports.
Invocation Events Syntax
Default invocation events: SHAKE, FLOATING_BUTTON
Kotlin examples:
Available Events:
LuciqInvocationEvent.SHAKE
LuciqInvocationEvent.SCREENSHOT
LuciqInvocationEvent.FLOATING_BUTTON
LuciqInvocationEvent.NONE
Step 3B — Configure Network Interception [MANDATORY]
The Luciq Gradle Plugin automatically instruments OkHttp and UrlConnection networking libraries. Minimum SDK version for unified interception: 19.0.0+
Configuration Settings (defaults shown)
networkInterception.enabled
false
okHttp.enabled
true
urlConnection.enabled
true
okHttp.legacyApmInterceptionEnabled
true
urlConnection.legacyInterceptionEnabled
true
Enable Network Interception (Gradle plugin examples)
Kotlin DSL (build.gradle.kts):
Groovy (build.gradle):
Note: Disabling legacy interceptors now ensures smoother future upgrades.
Selective Library Instrumentation (Optional)
Part C: Mask Sensitive Data (Application class, after Luciq.Builder().build())
Use Luciq.setNetworkLogListener to mask headers and recursively mask JSON body fields.
Kotlin example (place in Application class after initialization):
Key Points:
Mask headers with "*****" (preserves header presence)
Body fields: Recursive masking at any depth using Set for O(1) lookup
Return null to exclude a log entirely
Optional Step 1 — Mask Repro Step Screenshots (Android)
Minimum SDK Version: 11.13.0
If config_mode == default:
Custom mode examples:
Additional privacy controls:
Available Masking Types:
MaskingType.TEXT_INPUTS
MaskingType.LABELS
MaskingType.MEDIA
MaskingType.MASK_NOTHING
Notes:
Private Views API takes precedence over Auto Masking
Works with Bug Reporting, Crash Reporting, and Session Replay
Screenshots are disabled by default for Crash Reporting
Optional Step 2 — Configure Repro Steps Mode (Android)
Use ReproConfigurations.Builder to set IssueType modes:
Examples:
IssueType options:
IssueType.Bug
IssueType.Crash
IssueType.SessionReplay
IssueType.All
Key Points:
Selected products → ReproMode.EnableWithScreenshots
Non-selected → ReproMode.EnableWithNoScreenshots
Optional Step 3 — Add User Identification (Android)
Purpose: Link bug reports to specific user accounts.
Display options:
Using email
Using user ID
Using both email and ID
Skip (no user identification)
If user selects identification, search for login flows and add identify call AFTER successful auth and BEFORE navigation.
API Signature:
⚠️ CRITICAL: At least email OR id must be non-null. All null throws error.
Examples:
Email only: Luciq.identifyUser(user.name, user.email, null)
ID only: Luciq.identifyUser(user.name, null, user.id)
Both: Luciq.identifyUser(user.name, user.email, user.id)
Additional user data:
Logout flow:
Placement rules:
Identify AFTER authentication succeeds
Add logout BEFORE clearing session data
Optional Step 4 — Upload Mapping Files (Android)
This is configured automatically in default mode. Purpose: Upload ProGuard/R8 mapping files for crash symbolication.
Part A: Create upload_mapping.sh (project root)
Part B: Add Gradle Task (examples)
Kotlin DSL (build.gradle.kts)
Groovy (build.gradle)
Part C: Run After Release Build
Alternative: Manual dashboard upload via Luciq dashboard Settings.
Step 4 — Verification & Testing (Wrap up & validate) [USER-INITIATED ONLY]
⚠️ CRITICAL: This step is ONLY executed when the user explicitly selects "Wrap up & validate" from the optional steps menu. Do NOT run automatically after mandatory steps complete.
After mandatory steps complete, display the summary and menu:
WAIT for user selection. Do NOT proceed to build verification unless user selects option 2.
1. Build Verification (ONLY WHEN USER REQUESTS)
Execute platform-specific build command:
Android: ./gradlew assembleDebug
Expected Result: BUILD SUCCEEDED with no errors
Common Build Errors & Solutions:
"compileSdkVersion < 29" → set compileSdkVersion to 29+
"Unresolved reference: Luciq" → missing dependency, sync gradle and verify version
"Duplicate class" → dependency conflict; run ./gradlew dependencies to inspect
2. Runtime Testing (MANUAL)
Steps to test:
Build and run the app on emulator/device:
Trigger Luciq using configured invocation:
Shake: Shake device/emulator
Screenshot: Power + Volume Down
Floating Button: Tap overlay
Verify Luciq UI appears
Fill out and submit a test bug report
Check Luciq dashboard at https://dashboard.luciq.ai — verify report, user identification, and network logs
3. Final Summary (Display after build success)
Error Handling & Troubleshooting
Common Issues Across Platforms
SDK Not Initializing
Verify token is correct
Check initialization code placement (usually in app entry point)
Ensure import statement is correct
Network Logging Not Working
Verify masking code placed AFTER SDK initialization
Check that network interceptor is properly configured
Ensure app has network permissions
User Identification Not Showing
Verify identifyUser called after successful login
Check that logout is called on all logout paths
Ensure parameters are not all null
Reports Not Appearing in Dashboard
Verify device/simulator has internet connection
Check app token is correct
Wait a few minutes for sync
Check dashboard filters
Android-Specific Troubleshooting
Issue: "compileSdkVersion must be >= 29"
Issue: Network logs not appearing
Fix: Enable unified network interception in luciq { networkInterception { enabled = true } }
Issue: Application class not registered
Fix: Add android:name=".MyApplication" to tag in manifest
Issue: User identification error
Fix: Ensure at least email OR id is non-null (not both null)
Issue: Screenshots not masking
Fix: Use setAutoMaskScreenshotsTypes(MaskingType.TEXT_INPUTS, MaskingType.LABELS)
Quick Reference (Kotlin)
Java Equivalents
All Kotlin examples have straightforward Java equivalents:
val → final
Lambda
{ }→ Anonymous inner class?.let→ null check withifExtension functions → Static utility methods
Refer to official docs for Java examples if needed:
Last updated