AI Agent Integration Guide

A step by step prompt for AI coding agents integrating the Luciq iOS SDK, with the execution rules to follow and the iOS specific details.

Guide for AI Coding Agents to Integrate Luciq on iOS

⚠️ 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

┌─────────────────────────────────────────────────────────────┐
│                    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) │
│                                                             │
│ 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 4: Configure Network Logging [MANDATORY]             │
│   └─ Enable network capture + mask sensitive fields       │
│                                                             │
│ Step 5: Mask Repro Step Screenshots [MANDATORY]           │
│   └─ iOS: maskNothing default | Android: all types        │
│                                                             │
│ Step 6: Upload Symbolication Files [MANDATORY]            │
│   └─ iOS: dSYM via Build Phase | Android: mapping files   │
│                                                             │
│ 🛑 MANDATORY STEPS COMPLETE                               │
├─────────────────────────────────────────────────────────────┤
│              OPTIONAL FEATURES                              │
├─────────────────────────────────────────────────────────────┤
│ Available after mandatory steps (user-selected):          │
│   • Repro Steps Mode: Configure per product               │
│   • User Identification: Link reports to users            │
├─────────────────────────────────────────────────────────────┤
│                    VERIFICATION                             │
├─────────────────────────────────────────────────────────────┤
│ Wrap up & validate: Build → Test → Verify Dashboard       │
└─────────────────────────────────────────────────────────────┘

Step 1 — Collect Required Information [MANDATORY]

1A: Get App Token

Check MCP Server First:

IF Luciq MCP server is installed:
  1. Fetch all tokens with app names using MCP tools
  2. Display tokens to user in numbered list with app names
  3. Ask: "Which app token would you like to use?"
  4. WAIT for selection
  5. Store selected token
ELSE:
  1. Display to user: "To integrate Luciq SDK, you'll need your App Token."
  2. Display to user:
     "📍 Find your token: Luciq Dashboard → Settings → SDK Integration"
  3. Display on new line with indentation:
     "   Dashboard URL: https://dashboard.luciq.ai"
  4. Ask: "Please provide your Luciq App Token:"
  5. WAIT for user to provide token
  6. Validate token format (non-empty, alphanumeric)
  7. Store token for later use
END IF

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:

Platform-specific detection should look for:

iOS: Podfile, Cartfile, SPM packages in .xcodeproj, or none → Manual
Android: build.gradle with repositories, pom.xml, or none → Manual

DETECT package managers in project:
  - Count how many are found

IF exactly ONE package manager detected:
  1. Inform user: "Detected [PackageManager], will use this for integration"
  2. Store integration_method
  3. Proceed to Step 2
ELSE IF multiple or zero detected:
  1. Display platform-specific menu (see platform guides)
  2. WAIT for user selection
  3. Store integration_method
  4. Proceed to Step 2
END IF

1C: Apply Default Configuration (Inform + Opt-in)

Default configuration is applied automatically. Inform the user:

Display: "Applying default configuration:
  • Invocation: shake + floatingButton
  • Network logging: enabled with common field masking
  • Screenshot masking:
      - iOS: maskNothing (customize per privacy settings)
      - Android: all types (text inputs, labels, media)
  • Symbolication: automatic upload enabled
  • APM (Android): enabled
  • User identification: skip (can add later)

Would you like to customize any of these settings? (yes/no)"

WAIT for response

Store default configuration:

  - invocation_events = [shake, floatingButton]
  - network_logging_enabled = true
  - network_masking_enabled = true
  - predefined_headers_to_mask = ["Authorization", "Cookie", "X-API-Key", "token"]
  - predefined_body_fields_to_mask = ["password", "token", "ssn"]
  - auto_masking_types:
      - iOS: maskNothing (with guidance comments)
      - Android: [textInputs, labels, media]
  - symbolication_upload = enabled
  - repro_steps_config = skip (use defaults)
  - user_identification = skip

FOR ANDROID ONLY:
  - apm_enabled = true
  - Continue to Step 1D (Compose detection)

FOR iOS:
  - Continue to Step 1D (Fastlane detection for dSYM)

If user wants to customize (yes):

CUSTOMIZATION LOOP:

1. Display: "Which setting would you like to customize?
     1. Invocation events
     2. Network logging
     3. Screenshot masking
     4. Symbolication upload
     5. User identification

   Enter number:"

2. WAIT for selection

3. Apply the customization (see platform-specific guides for options)

4. Redisplay updated configuration:
   "Updated configuration:
     • Invocation: <current setting>  ← CHANGED (if modified)
     • Network logging: <current setting>
     • Screenshot masking: <current setting>
     • Symbolication: <current setting>
     • User identification: <current setting>

   Would you like to customize anything else? (yes/no)"

5. WAIT for response

6. IF yes → Go to step 1
   IF no → Proceed to Step 2

LOOP until user confirms to move on

If user does not want to customize (no):

Proceed to Step 2

Step 2 — Add SDK Dependency [MANDATORY - Platform-Specific]

Pre-Dependency Critical Step:

⚠️ MUST FETCH LATEST VERSION FIRST:

1. Fetch latest version from GitHub API:
   - iOS: https://api.github.com/repos/luciqai/luciq-ios-sdk/releases/latest
   - Android: https://api.github.com/repos/luciqai/luciq-android-sdk/releases/latest

2. Extract version number from the "tag_name" field (e.g., "19.1.0")

3. Store version for dependency configuration

4. DO NOT use placeholder versions like "1.0.0" or "latest"

Then proceed to platform-specific dependency installation (see platform guides)

Step 3 — Initialize the SDK [MANDATORY - Platform-Specific]

Invocation Events Configuration

Default invocation events: [shake, floatingButton]

These are applied automatically unless the user chose to customize in Step 1C.

If user chose to customize invocation events:

"Which invocation events (1 or more) should trigger Luciq?"

Options (select all that apply):
  1. shake: Device shake gesture
  2. screenshot: Screenshot capture
  3. floatingButton: Persistent floating button overlay
  4. none: Manual invocation only (via code)

WAIT for selection

Invocation Event Mapping:

none → Empty array []
Single selection → [selected]
Multiple → [event1, event2, ...]

Apply configuration in platform-specific syntax (see platform guides)

Step 4 — Configure Network Logging [MANDATORY]

Concepts (Platform-Agnostic):

Purpose: Automatically capture network requests/responses and optionally mask sensitive data

Part A: Network Capture

Display options:
  1. Keep automatic network capture enabled (default)
  2. Disable automatic network capture

WAIT for selection

IF option 2:
  - Apply platform-specific disable code (see platform guide)
  - END
ELSE IF option 1:
  - Continue with default (enabled)
END IF

Part B: Mask Sensitive Data

Display: "Specify which fields to mask:
          Options:
            1. Enter comma-separated field names
            2. Skip (no masking)

          For option 1, specify:
            - Headers (e.g., Authorization, Cookie, X-API-Key)
            - Body fields (e.g., password, token, ssn)"

WAIT for input

IF option 1 selected and input provided:
  Parse input:
    - Split by comma
    - Trim whitespace
    - Create arrays: headersToMask[], bodyFieldsToMask[]

  Apply platform-specific masking code (see platform guide):
    - Use loops for headers
    - Use recursion for nested body fields
    - Handle arrays and nested objects
ELSE IF option 2:
  - Leave network logs unmasked
END IF

Implementation Requirements:

Masking code MUST be placed AFTER SDK initialization
Headers: Simple loop through header names
Body: Recursive function to handle nested JSON at any depth
Performance: Use Set/HashSet for O(1) field lookup

Step 5 — Mask Repro Step Screenshots [MANDATORY]

Concepts (Platform-Agnostic):

Purpose: Automatically blur/mask sensitive UI elements in screenshot repro steps

Default Configuration:

iOS: maskNothing (with guidance comments for customization)
Android: All types (textInputs, labels, media)

Apply default screenshot masking configuration:

IF platform == iOS:
  Apply: Luciq.setAutoMaskScreenshots(.maskNothing)
  Add guidance comment about available options
ELSE IF platform == Android:
  Apply: Luciq.setAutoMaskScreenshotsTypes(MaskingType.TEXT_INPUTS, MaskingType.LABELS, MaskingType.MEDIA)
END IF

If user chose to customize in Step 1C:

Display options - Which types of elements should be masked?
  1. Text inputs only
  2. Labels only
  3. Images/media only
  4. Text inputs + labels
  5. All (text inputs + labels + media)
  6. Custom selection
  7. None (no screenshot masking - iOS only)

WAIT for selection

Map selection to mask types:
  1 → [textInputs]
  2 → [labels]
  3 → [images]
  4 → [textInputs, labels]
  5 → [textInputs, labels, images]
  6 → Ask for custom combination, then apply
  7 → maskNothing (iOS only)

Apply platform-specific masking API (see platform guide)

Available Mask Types:

iOS:
- .textInputs: Text input fields, password fields
- .labels: Text labels, buttons with text
- .media: Comprehensive masking (includes all types)
- .maskNothing: No automatic masking (default)
Android:
- MaskingType.TEXT_INPUTS: Text input fields, password fields
- MaskingType.LABELS: Text labels, buttons with text
- MaskingType.MEDIA: Images, media content
- MaskingType.MASK_NOTHING: Disable auto masking

Step 6 — Upload Symbolication Files [MANDATORY]

Concepts (Platform-Agnostic):

Purpose: Upload debug symbols (dSYM for iOS, mapping files for Android) for crash symbolication. This is required for readable crash reports.

iOS (dSYM Upload):

Detection-based approach:

1. Check if project uses Fastlane for archiving:
   - Look for Fastfile in project root or fastlane/ directory
   - Check if it contains archive/gym lanes

IF Fastlane detected:
   Use Fastlane Plugin approach
ELSE:
   Use Build Post-actions Script approach

See ios-guide.md for implementation details.

Android (Mapping File Upload):

Default: Gradle task (automatic)

Add Gradle task to upload ProGuard/R8 mapping files automatically
after release builds.

See android-guide.md for implementation details.

Customization Options:

Display: "How would you like to upload symbolication files?"

Options:
  1. Automatic (recommended) - configured during build/archive
  2. Manual - upload through dashboard
  3. Skip - disable symbolication upload

WAIT for selection

🛑 MANDATORY STEPS COMPLETE - STOP HERE

After all mandatory steps are complete, display:

"✅ Luciq SDK mandatory integration complete!

Configuration Summary:
  • Invocation: <configured events>
  • Network Logging: enabled with masking
  • Network Masking:
      - Headers: Authorization, Cookie, X-API-Key, token
      - Body Fields: password, token, ssn
  • Screenshot Masking: <configured types>
  • Symbolication Upload: configured

Ready to build and test?
  1. Wrap up & validate (build and test)
  2. Configure optional features (repro steps mode, user identification)

Enter number:"

WAIT for selection

Optional Step 1 — Configure Repro Steps Mode

Concepts (Platform-Agnostic):

Purpose: Control which products include screenshots in their repro steps

Default Behavior:

Bug Reporting: Screenshots enabled
Crash Reporting: Screenshots disabled
Session Replay: Screenshots enabled

Display: "Select products to ENABLE screenshots for:"

Options (multiple selection):
  1. Bug Reporting
  2. Crash Reporting
  3. Session Replay
  4. All products
  5. None (disable screenshots for all)
  6. Keep defaults (Bug Reporting + Session Replay with screenshots, Crash without)

Enter selections (e.g., "1,3" or "4"):

WAIT for input

IF option 6:
  - Keep default configuration
  - END
ELSE IF option 5 or "none" selected:
  - Disable screenshots for all products
  - Apply platform-specific configuration (see platform guide)
  - END
ELSE:
  Parse selections:
    - Selected products → Enable with screenshots
    - Non-selected products → Enable WITHOUT screenshots

  Apply platform-specific configuration (see platform guide)
END IF

Issue Type Mapping:

Bug Reporting → .bug / IssueType.Bug
Crash Reporting → .allCrashes / IssueType.AllCrashes
Session Replay → .sessionReplay / IssueType.SessionReplay
All products → .all / IssueType.All

Optional Step 2 — Add User Identification

Concepts (Platform-Agnostic):

Purpose: Link bug reports to specific user accounts for better tracking

Display options - How would you like to identify users?
  1. Using email
  2. Using user ID
  3. Using both email and ID
  4. Skip (no user identification)

WAIT for selection

IF option 4:
  - Skip user identification
  - END
ELSE:
  Store user_id_method
  Proceed to Step 3A and 3B
END IF

Search Strategy:

Search for authentication/login methods in codebase
Look for successful login callbacks/handlers
Identify where user data becomes available

Placement Rules:

Add identification AFTER authentication succeeds
Add BEFORE any navigation/routing
Ensure user data (email/id/name) is available at this point

API Signature (All Platforms):

identifyUser(
  id: String/null,      // User ID - required param, can be null
  email: String/null,   // Email - required param, can be null
  name: String/null     // Name - required param, can be null
)

Examples by Selection:

Option 1 (email): identifyUser(null, user.email, user.name)
Option 2 (ID): identifyUser(user.id, null, user.name)
Option 3 (both): identifyUser(user.id, user.email, user.name)

Platform-Specific Syntax: See platform guides

Step 3B: Identify Logout Flows

Search Strategy:

Search for logout/signout methods in codebase
Look for session clearing logic
Identify where user data is removed

Placement Rules:

Add logout call BEFORE clearing user session/data
Ensure it's called on all logout paths

API Signature (All Platforms):

logOut() / logout()  // No parameters

Platform-Specific Syntax: See platform guides

Step 7 — 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 this summary and menu:

✅ Luciq SDK integration complete!

Platform: <iOS/Android>
SDK Version: <version>
Integration Method: <SPM/Gradle/etc>

Configuration:
  • App Token: <first 8 chars>...
  • Invocation Events: <configured events>
  • Network Logging: <enabled/disabled>
  • Network Masking:
      - Headers: <list or none>
      - Body Fields: <list or none>
  • Screenshot Masking: <types or none>
  • Symbolication Upload: <automatic/manual/skip>
  • User Identification: <configured or not configured>

Next Steps - Select an option:
1. Configure optional features
2. Wrap up & validate

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:

iOS: xcodebuild -project ... -scheme ... build
Android: ./gradlew assembleDebug

Expected Result: BUILD SUCCEEDED with no errors

Common Build Errors & Solutions:

Error

Likely Cause

Solution

"no such module" / "unresolved import"

Wrong import statement

Check platform guide for correct import

"version not found"

Invalid SDK version

Verify version fetched from releases

"package not resolved"

Dependency not added

Re-run package manager sync

2. Runtime Testing [MANUAL]

After successful build, instruct user to perform these steps:

1. Build and run the app on simulator/emulator or device

2. Trigger Luciq using configured invocation method:
   - IF shake enabled: Shake the device/simulator
   - IF screenshot enabled: Take a screenshot
   - IF floatingButton enabled: Tap the floating button

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 appears
   - Verify user identification (if configured)
   - Verify network logs (if configured)

3. Final Summary [DISPLAY AFTER BUILD SUCCESS]

Generate and display summary after successful validation:

✅ Luciq SDK successfully integrated and validated!

Platform: <iOS/Android>
SDK Version: <version>
Integration Method: <SPM/Gradle/etc>

Configuration:
  • App Token: <first 8 chars>...
  • Invocation Events: <configured events>
  • Network Logging: <enabled/disabled>
  • Network Masking:
      - Headers: <list or none>
      - Body Fields: <list or none>
  • Screenshot Masking: <types or none>
  • Symbolication Upload: <automatic/manual/skip>
  • User Identification: <configured or not configured>

Build Status: ✅ SUCCEEDED

Next Steps:
  • ✅ Build completed successfully
  • Run the app and test SDK invocation
  • Submit a test report
  • Verify report in Luciq dashboard

Integration Complete - Ready for Testing!

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

2. Network Logging Not Working:

Verify masking code placed AFTER SDK initialization
Check that network interceptor is properly configured
Ensure app has network permissions

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

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

Extension Points for Platform Guides

Platform-specific guides should include:

Required Sections:

Platform-Specific Critical Rules (import naming, package names, etc.)
Pre-Integration Checklist (platform-specific gotchas)
Step 2 Implementation (dependency management code)
Step 3 Implementation (SDK initialization code)
Step 4 Implementation (network logging code) [MANDATORY]
Step 5 Implementation (screenshot masking code) [MANDATORY]
Step 6 Implementation (symbolication upload code) [MANDATORY]
Optional Step 1 Implementation (repro steps mode)
Optional Step 2 Implementation (user identification code)
Step 7 Implementation (build commands, platform-specific testing)

Reference Format:

## Step X — [Title]

> 📋 See [common-workflow.md#step-x](common-workflow.md#step-x) for detailed workflow

### Platform-Specific Implementation

[Platform-specific code and instructions]

Luciq SDK Integration - iOS Guide

Purpose: iOS-specific implementation details for Luciq SDK integration. This guide provides iOS-specific code, configuration, and platform requirements.

⚠️ iOS-SPECIFIC CRITICAL RULES ⚠️

Package vs Import Naming (MUST FOLLOW):

SPM Package Product Name: Use "Luciq" (in project.pbxproj, Podfile, etc.)
Swift Import Statement: ALWAYS use import LuciqSDK (NOT import Luciq)
Why Different?: The binary XCFramework is named "LuciqSDK.framework" internally
If Build Fails with "no such module 'Luciq'": You forgot to use import LuciqSDK

iOS-Specific Execution Rules:

Network logging code goes AFTER Luciq.start()
ALL API parameters must be included (can be nil) - never omit parameters
Use exact for SPM version requirement (not upToNextMajorVersion)
Place SDK initialization in AppDelegate or main App struct's init()

Official iOS Documentation:

iOS Integration: https://docs.luciq.ai/docs/ios-integration
iOS User Identification: https://docs.luciq.ai/docs/ios-identify-user
iOS Screenshot Masking: https://docs.luciq.ai/docs/product-guides-reprosteps-and-automasking

IOS-SPECIFIC IMPLEMENTATION DETAILS

Pre-Integration Checklist

Before starting, verify you understand these iOS-specific points:

Package product is "Luciq" but import is import LuciqSDK
SPM requires updating BOTH Package.swift AND project.pbxproj - updating only one is insufficient
SDK initialization MUST be the FIRST line in init()/didFinishLaunchingWithOptions
Network logging is MANDATORY - configure masking AFTER Luciq.start()
Screenshot masking is MANDATORY - configure after SDK initialization
dSYM upload is MANDATORY - add Run Script Build Phase to project.pbxproj (if no Fastlane)
Use exact for SPM (not range)
Build errors about "no such module" mean wrong import
ALL parameters in API calls are required (can be nil)

Step 1 — Collect Required Information [MANDATORY]

📋 Workflow: See common-workflow.md - Step 1

iOS-Specific Implementation

Package Manager Detection:

Check for:

.xcodeproj with SPM packages → SPM
Cartfile → Carthage
Podfile → CocoaPods (deprecated)
None → Manual

Integration Method Menu (if multiple/none detected):

Swift Package Manager (SPM) [Recommended]
Carthage
Manual (XCFramework)
CocoaPods (deprecated)

1C: Apply Default Configuration (Inform + Opt-in)

📋 Workflow: See common-workflow.md - Step 1C

For iOS:

Default configuration is applied automatically (shake + floatingButton, network masking, etc.)
User is informed of defaults and can opt-in to customize
If user customizes: Use the customization loop (select → apply → redisplay → confirm)
After configuration: Continue to Step 1D (Fastlane detection for dSYM)

1D: Detect Fastlane for dSYM Upload

Auto-Detection:

Search for Fastlane configuration:
  - Look for Fastfile in project root or fastlane/ directory
  - Check if it contains archive/gym lanes

IF Fastlane detected:
  Store fastlane_detected = true
  Inform user: "Fastlane detected - will configure dSYM upload via Fastlane plugin"
ELSE:
  Store fastlane_detected = false
  Inform user: "Will configure dSYM upload via Xcode Archive Post-actions"
END IF

Proceed to Step 2

Step 2 — Add the Luciq SDK Dependency [MANDATORY]

📋 Workflow: See common-workflow.md - Step 2 Fetch latest version from GitHub API: https://api.github.com/repos/luciqai/luciq-ios-sdk/releases/latest

iOS Implementation

⚠️ CRITICAL FOR SPM INTEGRATION: When adding the SDK via SPM, you MUST update BOTH files:

Package.swift - Add the package dependency and product
project.pbxproj - Add all SPM-related entries (package reference, product dependency, framework link)

Updating only Package.swift is NOT sufficient - the Xcode project file must also be modified for the SDK to be recognized.

If integration_method == spm:

Option A: Via Xcode UI (Manual - for reference only)

File → Add Package Dependencies...
Enter URL: https://github.com/luciqai/luciq-ios-sdk
Select "Exact Version" and enter <FETCHED_VERSION>
Add "Luciq" product to your target

Option B: Programmatic - REQUIRED for agent integration

The agent MUST modify project.pbxproj directly. Add the following entries:

1. Add to PBXBuildFile section:

/* Begin PBXBuildFile section */
    <UNIQUE_ID_1> /* Luciq in Frameworks */ = {isa = PBXBuildFile; productRef = <UNIQUE_ID_2> /* Luciq */; };
    // ... existing build files ...
/* End PBXBuildFile section */

2. Add to PBXFrameworksBuildPhase > files array:

/* Begin PBXFrameworksBuildPhase section */
    <EXISTING_ID> /* Frameworks */ = {
        isa = PBXFrameworksBuildPhase;
        buildActionMask = 2147483647;
        files = (
            <UNIQUE_ID_1> /* Luciq in Frameworks */,
        );
        runOnlyForDeploymentPostprocessing = 0;
    };
/* End PBXFrameworksBuildPhase section */

3. Add to PBXNativeTarget > packageProductDependencies array:

/* Begin PBXNativeTarget section */
    <TARGET_ID> /* YourApp */ = {
        // ... other properties ...
        packageProductDependencies = (
            <UNIQUE_ID_2> /* Luciq */,
        );
        // ... other properties ...
    };
/* End PBXNativeTarget section */

4. Add to PBXProject > packageReferences array:

/* Begin PBXProject section */
    <PROJECT_ID> /* Project object */ = {
        // ... other properties ...
        packageReferences = (
            <UNIQUE_ID_3> /* XCRemoteSwiftPackageReference "luciq-ios-sdk" */,
        );
        // ... other properties ...
    };
/* End PBXProject section */

5. Add XCRemoteSwiftPackageReference section (before closing brace):

/* Begin XCRemoteSwiftPackageReference section */
    <UNIQUE_ID_3> /* XCRemoteSwiftPackageReference "luciq-ios-sdk" */ = {
        isa = XCRemoteSwiftPackageReference;
        repositoryURL = "https://github.com/luciqai/luciq-ios-sdk";
        requirement = {
            kind = exactVersion;
            version = <FETCHED_VERSION>;
        };
    };
/* End XCRemoteSwiftPackageReference section */

6. Add XCSwiftPackageProductDependency section (before closing brace):

/* Begin XCSwiftPackageProductDependency section */
    <UNIQUE_ID_2> /* Luciq */ = {
        isa = XCSwiftPackageProductDependency;
        package = <UNIQUE_ID_3> /* XCRemoteSwiftPackageReference "luciq-ios-sdk" */;
        productName = Luciq;
    };
/* End XCSwiftPackageProductDependency section */

ID Generation Notes:

Use unique 24-character hexadecimal IDs (e.g., A10017001A000000000000001)
IDs must be unique within the project file
Follow the existing ID format pattern in the project

Also update Package.swift (if present):

// In Package.swift dependencies array:
dependencies: [
    .package(url: "https://github.com/luciqai/luciq-ios-sdk", exact: "<FETCHED_VERSION>")
],

// In target dependencies:
.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "Luciq", package: "luciq-ios-sdk")
    ]
)

If integration_method == carthage:

# In Cartfile:
binary "https://raw.githubusercontent.com/luciqai/luciq-ios-sdk/main/Luciq.json"

# Then run:
carthage update --platform iOS

If integration_method == manual:

1. Download: https://github.com/luciqai/luciq-ios-sdk/releases/latest/download/Luciq-XCFramework.zip
2. Unzip to reveal Luciq.xcframework
3. Drag into Xcode project → Frameworks, Libraries, and Embedded Content
4. Select "Embed & Sign"

If integration_method == cocoapods:

Note for the agent: CocoaPods is deprecated. Before applying the Podfile change, you MUST inform the user that SPM is now the recommended integration method and offer to migrate them. Only proceed with the Podfile change below if the user explicitly declines migration.
If the user agrees to migrate, follow the steps in the Migrating from CocoaPods to SPM guide instead, then return to the SPM block above to complete the integration.

# In Podfile:
pod 'Luciq', '~> <MAJOR_VERSION>'  # e.g., '~> 19.0'

# Then run:
pod install

Step 3 — Initialize the SDK [MANDATORY]

📋 Workflow: See common-workflow.md - Step 3

iOS Implementation

⚠️ CRITICAL: ALWAYS use import LuciqSDK (not import Luciq)

Where to place:

SwiftUI: App struct's init() - AS THE FIRST LINE
UIKit: AppDelegate's application(_:didFinishLaunchingWithOptions:) - AS THE FIRST LINE

⚠️ IMPORTANT: The SDK initialization MUST be the FIRST code executed in the init method, before any other initialization code. This ensures Luciq captures all app activity from the very start.

Option 1: SwiftUI App

import SwiftUI
import LuciqSDK  // ← CRITICAL: Import is LuciqSDK, not Luciq

@main
struct YourApp: App {
    init() {
        // ⚠️ MUST be FIRST - Initialize Luciq before any other code
        Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: <EVENTS>)

        // Other initialization code goes AFTER Luciq.start()
        // ...
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Option 2: UIKit App (AppDelegate)

import UIKit
import LuciqSDK  // ← CRITICAL: Import is LuciqSDK, not Luciq

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // ⚠️ MUST be FIRST - Initialize Luciq before any other code
        Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: <EVENTS>)

        // Other initialization code goes AFTER Luciq.start()
        // ...

        return true
    }

    // ... rest of AppDelegate methods ...
}

Invocation Events Syntax:

Default invocation events: [.shake, .floatingButton]

// Default mode: shake + floatingButton (applied automatically)
Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [.shake, .floatingButton])

// If user customized - other options:

// Screenshot only
Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [.screenshot])

// All events
Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [.shake, .screenshot, .floatingButton])

// None (manual only)
Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [])

Note: The class name is Luciq but the import is LuciqSDK

Step 3B: Add Info.plist Permissions

Required permissions for Luciq features (voice notes, image attachments):

First, fetch the app name:

1. Read Info.plist for CFBundleDisplayName or CFBundleName
2. If not found, check project.pbxproj for PRODUCT_NAME
3. Store as <APP_NAME>

Add to Info.plist if not present:

<key>NSMicrophoneUsageDescription</key>
<string><APP_NAME> needs access to your microphone so you can attach voice notes.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string><APP_NAME> needs access to your photo library so you can attach images.</string>

Example (if app name is "MyApp"):

<key>NSMicrophoneUsageDescription</key>
<string>MyApp needs access to your microphone so you can attach voice notes.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>MyApp needs access to your photo library so you can attach images.</string>

Implementation:

1. Locate Info.plist file in project
2. Check if NSMicrophoneUsageDescription exists
   - If not, add it with the app name prefix
3. Check if NSPhotoLibraryUsageDescription exists
   - If not, add it with the app name prefix
4. Inform user of added permissions

Step 4 — Configure Network Logging [MANDATORY]

📋 Workflow: See common-workflow.md - Step 4

iOS Implementation

Check Configuration Mode:

IF config_mode == default:
  Network logging is enabled by default
  Apply predefined masking with:
    - Headers: ["Authorization", "Cookie", "X-API-Key", "token"]
    - Body fields: ["password", "token", "ssn"]
ELSE IF config_mode == custom:
  Ask user for network logging preferences
END IF

Disable Automatic Capture (call BEFORE Luciq.start()) - Custom Mode Only:

NetworkLogger.disableAutomaticCapturingOfNetworkLogs()

Mask Sensitive Data (call AFTER Luciq.start()):

Option 1: SwiftUI App

import SwiftUI
import LuciqSDK

@main
struct YourApp: App {
    init() {
        // Step 1: Initialize SDK first
        Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [.floatingButton])

        // Step 2: Configure network masking AFTER start
        configureNetworkMasking()
    }

    private func configureNetworkMasking() {
        // Define fields based on config_mode
        let headersToMask: [String] = IF config_mode == default:
            ["Authorization", "Cookie", "X-API-Key", "token"]  // Predefined for default mode
        ELSE:
            ["Authorization", "Cookie", "X-API-Key"]  // Custom user input

        let bodyFieldsToMask: Set<String> = IF config_mode == default:
            ["password", "token", "ssn"]  // Predefined for default mode
        ELSE:
            ["password", "token", "ssn", "uuid"]  // Custom user input

        NetworkLogger.setRequestObfuscationHandler { request in
            var mutableRequest = (request as NSURLRequest).mutableCopy() as! NSMutableURLRequest

            // Mask headers using loop
            for header in headersToMask {
                if mutableRequest.value(forHTTPHeaderField: header) != nil {
                    mutableRequest.setValue("*****", forHTTPHeaderField: header)
                }
            }

            // Mask body fields using recursive function
            if let body = mutableRequest.httpBody,
               let jsonObject = try? JSONSerialization.jsonObject(with: body) {
                let maskedObject = Self.maskFields(in: jsonObject, fieldsToMask: bodyFieldsToMask)
                if let newBody = try? JSONSerialization.data(withJSONObject: maskedObject) {
                    mutableRequest.httpBody = newBody
                }
            }

            return mutableRequest.copy() as! URLRequest
        }
    }

    // Recursive helper to mask fields at any depth
    private static func maskFields(in object: Any, fieldsToMask: Set<String>) -> Any {
        if var dictionary = object as? [String: Any] {
            for (key, value) in dictionary {
                if fieldsToMask.contains(key) {
                    dictionary[key] = "*****"
                } else if value is [String: Any] || value is [Any] {
                    dictionary[key] = maskFields(in: value, fieldsToMask: fieldsToMask)
                }
            }
            return dictionary
        } else if let array = object as? [Any] {
            return array.map { maskFields(in: $0, fieldsToMask: fieldsToMask) }
        }
        return object
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Option 2: UIKit App (AppDelegate)

import UIKit
import LuciqSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Step 1: Initialize SDK first
        Luciq.start(withToken: "<APP_TOKEN>", invocationEvents: [.floatingButton])

        // Step 2: Configure network masking AFTER start
        configureNetworkMasking()

        return true
    }

    private func configureNetworkMasking() {
        // Define fields based on config_mode
        let headersToMask: [String] = IF config_mode == default:
            ["Authorization", "Cookie", "X-API-Key", "token"]  // Predefined for default mode
        ELSE:
            ["Authorization", "Cookie", "X-API-Key"]  // Custom user input

        let bodyFieldsToMask: Set<String> = IF config_mode == default:
            ["password", "token", "ssn"]  // Predefined for default mode
        ELSE:
            ["password", "token", "ssn", "uuid"]  // Custom user input

        NetworkLogger.setRequestObfuscationHandler { request in
            var mutableRequest = (request as NSURLRequest).mutableCopy() as! NSMutableURLRequest

            // Mask headers using loop
            for header in headersToMask {
                if mutableRequest.value(forHTTPHeaderField: header) != nil {
                    mutableRequest.setValue("*****", forHTTPHeaderField: header)
                }
            }

            // Mask body fields using recursive function
            if let body = mutableRequest.httpBody,
               let jsonObject = try? JSONSerialization.jsonObject(with: body) {
                let maskedObject = self.maskFields(in: jsonObject, fieldsToMask: bodyFieldsToMask)
                if let newBody = try? JSONSerialization.data(withJSONObject: maskedObject) {
                    mutableRequest.httpBody = newBody
                }
            }

            return mutableRequest.copy() as! URLRequest
        }
    }

    // Recursive helper to mask fields at any depth
    private func maskFields(in object: Any, fieldsToMask: Set<String>) -> Any {
        if var dictionary = object as? [String: Any] {
            for (key, value) in dictionary {
                if fieldsToMask.contains(key) {
                    dictionary[key] = "*****"
                } else if value is [String: Any] || value is [Any] {
                    dictionary[key] = maskFields(in: value, fieldsToMask: fieldsToMask)
                }
            }
            return dictionary
        } else if let array = object as? [Any] {
            return array.map { maskFields(in: $0, fieldsToMask: fieldsToMask) }
        }
        return object
    }

    // ... rest of AppDelegate methods ...
}

Key Points:

Masking MUST be called AFTER Luciq.start()
Use Set<String> for O(1) lookup performance
Recursive function handles nested JSON at any depth
For SwiftUI: Use Self.maskFields (static) inside init closure
For UIKit: Use self.maskFields (instance) in AppDelegate

Step 5 — Mask Repro Step Screenshots [MANDATORY]

📋 Workflow: See common-workflow.md - Optional Step 1

iOS Implementation

Default Configuration (maskNothing with guidance):

// Configure screenshot masking based on your app's privacy requirements
// Options: .textInputs, .labels, .media, or combine multiple types
// Example: Luciq.setAutoMaskScreenshots([.textInputs, .labels])
Luciq.setAutoMaskScreenshots(.maskNothing)  // Default: no automatic masking

// SwiftUI views are automatically masked when you change the masked types from .maskNothing
// Uncomment the line below to disable automatic SwiftUI view masking
// Luciq.autoMaskSwiftUIViews = false

If user customizes masking:

// For text inputs only:
Luciq.setAutoMaskScreenshots([.textInputs])

// For labels only:
Luciq.setAutoMaskScreenshots([.labels])

// For text inputs + labels:
Luciq.setAutoMaskScreenshots([.textInputs, .labels])

// For all types (comprehensive):
Luciq.setAutoMaskScreenshots([.textInputs, .labels, .media])

// Or use .media for comprehensive masking:
Luciq.setAutoMaskScreenshots([.media])

Available iOS Mask Types:

.maskNothing - No automatic masking (default)
.textInputs - UITextField, UITextView, secure text fields
.labels - UILabel, UIButton text
.media - Comprehensive masking (includes all types)

SwiftUI Auto Masking:

When masking types are changed from .maskNothing, SwiftUI views are automatically masked
To disable this behavior: Luciq.autoMaskSwiftUIViews = false

Step 6 — Upload dSYM Files [MANDATORY]

📋 Workflow: See common-workflow.md - Step 6

iOS Implementation

This step is configured automatically based on Step 1D detection.

Option A: Fastlane Plugin (if fastlane_detected == true)

First, install the Fastlane plugin:

fastlane add_plugin luciq_official

Then add to your Fastfile:

# In Fastfile, add to your archive lane:
lane :archive do
  gym(
    scheme: "<SCHEME_NAME>",
    archive_path: "./build/<APP_NAME>.xcarchive"
  )
  # IMPORTANT: For local archives, you MUST specify dsym_array_paths
  # The plugin will NOT automatically find dSYMs from local archives
  luciq_official(
    api_token: "<APP_TOKEN>",
    dsym_array_paths: ["./build/<APP_NAME>.xcarchive/dSYMs/<APP_NAME>.app.dSYM"]
  )
end

# For bitcode-enabled apps or App Store Connect downloads:
# (dsym_array_paths not needed - plugin uses downloaded dSYMs automatically)
lane :refresh_dsyms do
  download_dsyms(version: "latest")
  luciq_official(api_token: "<APP_TOKEN>")
end

Plugin Parameters:

Parameter

Required

Description

api_token

Yes

Your Luciq app token from Step 1A

dsym_array_paths

Yes (for local archives)

Array of paths to dSYM files/folders

eu

Set to true for EU data center

end_point

Custom API endpoint (if applicable)

Common Mistake: Omitting dsym_array_paths for local archives. Without this parameter, the plugin only looks for dSYMs downloaded via download_dsyms action and will show: "Fastlane dSYMs file is not found!"

Option B: Run Script Build Phase (if fastlane_detected == false)

Via Xcode UI (Manual - for reference only):

In Xcode: Select target → Build Phases → + → New Run Script Phase
Name it "Upload dSYM to Luciq"
Add the following script:

#- -- SCRIPT BEGIN - --

# SKIP_SIMULATOR_BUILDS=1

# Check PROJECT_DIR first (CocoaPods, Carthage, Manual)
SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Luciq_dsym_upload.sh' | head -1)

# If not found, check SPM location
if [ -z "$SCRIPT_SRC" ]; then
  SCRIPT_SRC=$(find "$BUILT_PRODUCTS_DIR" -name 'Luciq_dsym_upload.sh' | head -1)
fi

if [ -z "$SCRIPT_SRC" ]; then
  echo "Luciq: err: script not found. Make sure the Luciq SDK is properly installed."
  exit 1
fi

APP_TOKEN="YOUR-APP-TOKEN-HERE"
source "${SCRIPT_SRC}"
#- -- SCRIPT END - --

Programmatic - REQUIRED for agent integration:

The agent MUST modify project.pbxproj to add a Run Script Build Phase.

1. Add PBXShellScriptBuildPhase section (after PBXSourcesBuildPhase, before XCBuildConfiguration):

/* Begin PBXShellScriptBuildPhase section */
		<UNIQUE_ID> /* Upload dSYM to Luciq */ = {
			isa = PBXShellScriptBuildPhase;
			buildActionMask = 2147483647;
			files = (
			);
			inputFileListPaths = (
			);
			inputPaths = (
			);
			name = "Upload dSYM to Luciq";
			outputFileListPaths = (
			);
			outputPaths = (
			);
			runOnlyForDeploymentPostprocessing = 0;
			shellPath = /bin/sh;
			shellScript = "#- -- SCRIPT BEGIN - --\n\n# SKIP_SIMULATOR_BUILDS=1\n\n# Check PROJECT_DIR first (CocoaPods, Carthage, Manual)\nSCRIPT_SRC=$(find \"$PROJECT_DIR\" -name 'Luciq_dsym_upload.sh' | head -1)\n\n# If not found, check SPM location\nif [ -z \"$SCRIPT_SRC\" ]; then\n  SCRIPT_SRC=$(find \"$BUILT_PRODUCTS_DIR\" -name 'Luciq_dsym_upload.sh' | head -1)\nfi\n\nif [ -z \"$SCRIPT_SRC\" ]; then\n  echo \"Luciq: err: script not found. Make sure the Luciq SDK is properly installed.\"\n  exit 1\nfi\n\nAPP_TOKEN=\"YOUR-APP-TOKEN-HERE\"\nsource \"${SCRIPT_SRC}\"\n#- -- SCRIPT END - --\n";
		};
/* End PBXShellScriptBuildPhase section */

2. Add to PBXNativeTarget > buildPhases array (as the LAST item):

buildPhases = (
	<EXISTING_ID> /* Sources */,
	<EXISTING_ID> /* Frameworks */,
	<EXISTING_ID> /* Resources */,
	<UNIQUE_ID> /* Upload dSYM to Luciq */,
);

Shell Script Escaping Notes:

Use \n for newlines in the shellScript string
Use \" for double quotes inside the string
Use ' for single quotes (no escaping needed)

Important Notes:

The script runs automatically after each build as part of the build phases
The <APP_TOKEN> should be replaced with the token from Step 1A
Download Luciq_dsym_upload.sh from the Luciq dashboard if not present
Use exit 0 (not exit 1) when script is not found to avoid build failures

🛑 MANDATORY STEPS COMPLETE

Optional Step 1 — Configure Repro Steps Mode

📋 Workflow: See common-workflow.md - Optional Step 1

iOS Implementation

Based on user selections, apply configuration:

// Example: User selected Bug Reporting and Session Replay (1,3)
Luciq.setReproStepsFor(.bug, with: .enable)
Luciq.setReproStepsFor(.sessionReplay, with: .enable)
Luciq.setReproStepsFor(.allCrashes, with: .enabledWithNoScreenshots)  // Not selected

// Example: User selected All products (4)
Luciq.setReproStepsFor(.all, with: .enable)

// Example: User selected only Crash Reporting (2)
Luciq.setReproStepsFor(.allCrashes, with: .enable)
Luciq.setReproStepsFor(.bug, with: .enabledWithNoScreenshots)  // Not selected
Luciq.setReproStepsFor(.sessionReplay, with: .enabledWithNoScreenshots)  // Not selected

// Example: User selected None (5)
Luciq.setReproStepsFor(.all, with: .enabledWithNoScreenshots)

Issue Type Options:

.bug - Bug Reporting
.allCrashes - Crash Reporting
.sessionReplay - Session Replay
.all - All products

Key Points:

Selected products → .enable (with screenshots)
Non-selected products → .enabledWithNoScreenshots (without screenshots)

Optional Step 2 — Add User Identification

📋 Workflow: See common-workflow.md - Optional Step 2

import LuciqSDK

class AuthenticationManager: ObservableObject {
    func signIn(email: String, password: String) -> Bool {
        // ... authentication logic ...

        if authenticationSuccessful {
            // Identify user AFTER successful auth, BEFORE navigation
            Luciq.identifyUser(
                withID: nil,              // or user.id
                email: user.email,        // or nil
                name: user.name           // or nil
            )

            currentUser = user
            isAuthenticated = true
            return true
        }

        return false
    }

    func signUp(email: String, password: String, name: String) -> Bool {
        // ... signup logic ...

        if signupSuccessful {
            // Identify user after signup
            Luciq.identifyUser(
                withID: nil,
                email: email,
                name: name
            )

            return true
        }

        return false
    }
}

API Signature:

Luciq.identifyUser(
    withID: String?,     // Required parameter, can be nil
    email: String?,      // Required parameter, can be nil
    name: String?        // Required parameter, can be nil
)

Examples:

Email only: Luciq.identifyUser(withID: nil, email: user.email, name: user.name)
ID only: Luciq.identifyUser(withID: user.id, email: nil, name: user.name)
Both: Luciq.identifyUser(withID: user.id, email: user.email, name: user.name)

iOS Implementation - Logout Flow

class AuthenticationManager: ObservableObject {
    func logout() {
        // Call Luciq logout BEFORE clearing session
        Luciq.logOut()

        // Then clear user data
        currentUser = nil
        isAuthenticated = false
        UserDefaults.standard.removeObject(forKey: "loggedInUserEmail")
    }
}

Step 7 — Verification & Testing [WRAP UP & VALIDATE]

📋 Workflow: See common-workflow.md - Step 7

iOS Build Verification

xcodebuild -project YourProject.xcodeproj \
           -scheme YourScheme \
           -configuration Debug \
           -destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
           build

Expected: ** BUILD SUCCEEDED **

iOS-Specific Build Errors:

Error

Cause

Fix

no such module 'Luciq'

Used import Luciq instead of import LuciqSDK

Change to import LuciqSDK

version not found

Invalid SPM version

Check version from releases/latest

Missing package product 'Luciq'

Package not added to target

Add "Luciq" product in Xcode

iOS Runtime Testing

Run app in Xcode (Cmd+R)
Trigger Luciq:
- Shake: Hardware → Shake (Cmd+Ctrl+Z in simulator)
- Screenshot: Cmd+S in simulator
- Floating Button: Tap the button overlay
Verify Luciq UI appears
Submit test report
Check dashboard

iOS-Specific Troubleshooting

Issue: "Command SwiftCompile failed"

Cause: Import or syntax error Fix: Verify all imports are import LuciqSDK, check Swift syntax

Issue: NetworkLogger not found

Cause: Import missing Fix: Ensure import LuciqSDK at top of file

Issue: Shake not working in simulator

Cause: Simulator gesture needed Fix: Use Hardware → Shake or Cmd+Ctrl+Z

Issue: Reports missing user info

Cause: identifyUser called with all nil parameters Fix: Pass at least email or ID (not all nil)

Issue: "Fastlane dSYMs file is not found!"

Cause: Missing dsym_array_paths parameter in Fastlane plugin call Fix: For local archives (using gym/build_app), you MUST specify the dSYM path:

luciq_official(
  api_token: "<APP_TOKEN>",
  dsym_array_paths: ["./build/<APP_NAME>.xcarchive/dSYMs/<APP_NAME>.app.dSYM"]
)

Note: This parameter is only optional when using download_dsyms to fetch dSYMs from App Store Connect.

Quick Reference

// ALWAYS use this import
import LuciqSDK

// Default initialization (shake + floatingButton)
Luciq.start(withToken: "token", invocationEvents: [.shake, .floatingButton])

// User identification
Luciq.identifyUser(withID: nil, email: "[email protected]", name: "John")

// Logout
Luciq.logOut()

// Screenshot masking (default: maskNothing)
// Configure screenshot masking based on your app's privacy requirements
// Options: .textInputs, .labels, .media, or combine multiple types
Luciq.setAutoMaskScreenshots(.maskNothing)  // Default: no automatic masking

// SwiftUI views are automatically masked when you change masked types from .maskNothing
// Luciq.autoMaskSwiftUIViews = false  // Uncomment to disable

// Network masking (after start)
NetworkLogger.setRequestObfuscationHandler { request in
    // ... masking logic ...
}

PreviousMigrating from CocoaPods to SPM NextOne Code Apps For iOS

Last updated 17 days ago

Good evening

Guide for AI Coding Agents to Integrate Luciq on iOS

⚠️ UNIVERSAL EXECUTION RULES ⚠️

Critical Rules - Apply to ALL Platforms:

Execution Guidelines:

Official Documentation:

Integration Workflow Overview

Step 1 — Collect Required Information [MANDATORY]

1A: Get App Token

1B: Determine Integration Method

1C: Apply Default Configuration (Inform + Opt-in)

Step 2 — Add SDK Dependency [MANDATORY - Platform-Specific]

Pre-Dependency Critical Step:

Step 3 — Initialize the SDK [MANDATORY - Platform-Specific]

Invocation Events Configuration

Step 4 — Configure Network Logging [MANDATORY]

Concepts (Platform-Agnostic):

Step 5 — Mask Repro Step Screenshots [MANDATORY]

Concepts (Platform-Agnostic):

Step 6 — Upload Symbolication Files [MANDATORY]

Concepts (Platform-Agnostic):

iOS (dSYM Upload):

Android (Mapping File Upload):

Customization Options:

🛑 MANDATORY STEPS COMPLETE - STOP HERE

Optional Steps Menu

Optional Step 1 — Configure Repro Steps Mode

Concepts (Platform-Agnostic):

Optional Step 2 — Add User Identification

Concepts (Platform-Agnostic):

Step 3A: Identify Login Flows

Step 3B: Identify Logout Flows

Step 7 — Verification & Testing (Wrap up & validate) [USER-INITIATED ONLY]

After Mandatory Steps Complete

1. Build Verification [ONLY WHEN USER REQUESTS]

2. Runtime Testing [MANUAL]

3. Final Summary [DISPLAY AFTER BUILD SUCCESS]

Error Handling & Troubleshooting

Common Issues Across Platforms:

Extension Points for Platform Guides

Required Sections:

Reference Format:

Luciq SDK Integration - iOS Guide

⚠️ iOS-SPECIFIC CRITICAL RULES ⚠️

Package vs Import Naming (MUST FOLLOW):

iOS-Specific Execution Rules:

Official iOS Documentation:

IOS-SPECIFIC IMPLEMENTATION DETAILS

Pre-Integration Checklist

Step 1 — Collect Required Information [MANDATORY]

iOS-Specific Implementation

1C: Apply Default Configuration (Inform + Opt-in)

1D: Detect Fastlane for dSYM Upload

Step 2 — Add the Luciq SDK Dependency [MANDATORY]

iOS Implementation

Step 3 — Initialize the SDK [MANDATORY]

iOS Implementation

Step 3B: Add Info.plist Permissions

Step 4 — Configure Network Logging [MANDATORY]

iOS Implementation

Step 5 — Mask Repro Step Screenshots [MANDATORY]

iOS Implementation

Step 6 — Upload dSYM Files [MANDATORY]

iOS Implementation

🛑 MANDATORY STEPS COMPLETE

Optional Step 1 — Configure Repro Steps Mode

iOS Implementation

Optional Step 2 — Add User Identification

iOS Implementation - Login Flow

iOS Implementation - Logout Flow

Step 7 — Verification & Testing [WRAP UP & VALIDATE]

iOS Build Verification

iOS Runtime Testing

iOS-Specific Troubleshooting

Issue: "Command SwiftCompile failed"

Issue: NetworkLogger not found

Issue: Shake not working in simulator

Issue: Reports missing user info

Issue: "Fastlane dSYMs file is not found!"

Quick Reference