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:


Integration Workflow Overview

1

MANDATORY STEPS

Step 1: Collect Required Information

  • 1A: Get App Token (MCP or Manual)

  • 1B: Determine Integration Method

  • 1C: Apply Default Config (Inform + Opt-in Customize)

2

Step 2: Add SDK Dependency (Platform-Specific)

  • Fetch latest version from GitHub API

3

Step 3: Initialize the SDK (Platform-Specific)

  • Default: shake + floatingButton

4

Step 3B: Configure Network Interception [ANDROID ONLY]

  • Enable unified network interception in Gradle

5

DEFAULT CONFIG (Auto-Applied)

Applied automatically (customizable via opt-in):

  • Network Logging: enabled + common field masking

  • Screenshot Masking: iOS=maskNothing, Android=all

  • Symbolication Upload: automatic

  • User Identification: skip

6

VERIFICATION

Wrap up & validate: Build → Test → Verify Dashboard


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

  1. Gradle (Recommended)

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

Setting
Default

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:

  1. Using email

  2. Using user ID

  3. Using both email and ID

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

  1. Build and run the app on emulator/device:

  2. Trigger Luciq using configured invocation:

    • Shake: Shake device/emulator

    • Screenshot: Power + Volume Down

    • Floating Button: Tap overlay

  3. Verify Luciq UI appears

  4. Fill out and submit a test bug report

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

  1. SDK Not Initializing

  • Verify token is correct

  • Check initialization code placement (usually in app entry point)

  • Ensure import statement is correct

  1. Network Logging Not Working

  • Verify masking code placed AFTER SDK initialization

  • Check that network interceptor is properly configured

  • Ensure app has network permissions

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

  1. 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 with if

  • Extension functions → Static utility methods

Refer to official docs for Java examples if needed:

Last updated