Overview

This guide helps you migrate your Android project from the Instabug SDK to the Luciq SDK. This change is part of a company-wide rebranding initiative. You can perform the migration manually by following the step-by-step instructions or use our automated migration script for a faster transition.

Prerequisites

Before starting the migration process, ensure your project meets the following requirements and take the necessary precautions.

Supported Instabug Versions

This migration guide supports projects currently using:

• Instabug SDK (Manual & Automated): 16.x.x and above
• Target Luciq SDK: 18.0.0
• All Instabug modules: Core, APM, Crash, Bug, Survey, Features Request, NDK Crash, Compose, Compose APM, OkHttp Interceptors, gRPC Interceptors, Compiler Extension, Test Report

🚧

If you're using Instabug version prior to 16.0.0, it's recommended to upgrade Instabug SDK, consulting change logs, first before proceeding with this migration process.

Pre-Migration Checklist

🔒 Backup Your Project

[ ] Commit all changes to your version control system (e.g., Git).
[ ] Create a dedicated backup branch to allow for a clean rollback if needed.
[ ] Build and run your project to confirm it's in a stable, working state before you begin.

💡 Tip: Assess your project's complexity using our Migration Complexity Assessment to choose the best approach for you.

🔍 Project Assessment

[ ] Identify all Instabug dependencies in your project
[ ] List custom Instabug configurations in build files
[ ] Note any custom ProGuard rules related to Instabug
[ ] Check for hardcoded Instabug references in code comments or strings

⚙️ Environment Preparation

[ ] Sync project and resolve any existing build issues
[ ] Clean build cache: ./gradlew clean
[ ] Ensure stable internet connection (for dependency downloads)

Migration Complexity Assistant

When to Use Manual vs. Automated Migration

✅ Use Automated Migration When:

• You have a standard Instabug setup with minimal customization.
• You are using a supported Instabug version.
• Your project doesn't have complex custom build scripts that reference Instabug.
• You are comfortable using command-line tools and have created a backup.

⚠️ Use Manual Migration When:

• You have a heavily customized Instabug implementation.
• You are using an older, unsupported version of the Instabug SDK.
• Your project has complex build logic or dependencies that the script might not handle.
• You prefer granular control over every step of the migration process.

Step-by-Step Manual Migration

Step 1: Migrate Your Dependency

💡 Quick Option: This step can be automated using our migration script. Continue reading for manual instructions.

The general rule of thumb for migrating Instabug SDK dependencies is to:

1. Replace com.instabug.library artifacts' group with ai.luciq.library
2. Replace the word/prefix instabug of artifacts' name(s) with luciq
3. Upgrade the artifact version to 18.0.0

The exact artifact names' mapping is as follows

Example (1): Using Version Catalog libs.versions.toml

Before:

[versions]
instabug = "16.0.1"
# Rest of versions

[libraries]
instabug = {group = "com.instabug.library", name = "instabug", version.ref = "instabug"}
instabug-compose = {group = "com.instabug.library", name = "instabug-compose", version.ref = "instabug"}

After:

[versions]
luciq = "18.0.0"
# Rest of versions

[libraries]
instabug = {group = "ai.luciq.library", name = "luciq", version.ref = "luciq"}
instabug-compose = {group = "ai.luciq.library", name = "luciq-compose", version.ref = "luciq"}

Example (2): Declaring dependencies in build.gradle

Before:

dependencies {
    implementation 'com.instabug.library:instabug:16.0.1'
    implementation 'com.instabug.library:instabug-compose:16.0.1'
}

After:

dependencies {
    implementation 'ai.luciq.library:luciq:18.0.0'
    implementation 'ai.luciq.library:luciq-compose:18.0.0'
}

Step 2: Migrate your plugin integration

To migrate your plugin integration, the following steps should be executed:

1. Replace com.instabug.library:instabug-plugin:16.0.1 classpath artifact with ai.luciq.library:luciq-plugin:18.0.0 (If you're adding the plugin as a classpath to your root project's build.gradle file)
2. Replace com.instabug.library root plugin id with ai.luciq.library and upgrade the version to 18.0.0 (If you're adding the plugin as an id to your root project's build.gradle file or Version Catalog)
3. Replace Instabug's plugin ids in your app/module level build.gradle file as per plugins mapping

The exact mapping of Instabug's plugins is as follows

Example (1): Instabug's plugin added as a classpath

Before:

buildScript {
    dependencies {
        classpath 'com.instabug.library:instabug-plugin:16.0.1'
    }
}

After:

buildScript {
    dependencies {
        classpath 'ai.luciq.library:luciq-plugin:18.0.0'
    }
}

Example (2): Instabug's plugin added as root project plugin

Before:

plugins {
    id("com.instabug.library") version "16.0.1" apply false
}

After:

plugins {
    id("ai.luciq.library") version "18.0.0" apply false
}

Example (3): Instabug's Plugin defined in Version Catalog

Before:

[versions]
instabug = "16.0.1"

[libraries]
# Libraries defined here

[plugins]
instabug = { id = "com.instabug.library", version.ref = "instabug" }

After:

[versions]
luciq = "18.0.0"

[libraries]
# Libraries defined here

[plugins]
instabug = { id = "ai.luciq.library", version.ref = "luciq" }

Example (4): Module's level plugin integration

Before:

plugins {
    id("instabug")
    id("instabug-apm")
    id("instabug-crash")
}

After:

plugins {
    id("luciq")
    id("luciq-apm")
    id("luciq-crash")
}

Step 3: Migrate your plugin configurations

If you're not using Instabug plugin, you can safely skip this step.

Changes done in plugin configurations can be listed as follows:

1. Instabug and instabug configuration closures and removed in favor of a unified luciq closure
2. APM's specific debugEnabled configuration property is removed in favor in a more generic setDebugLogsEnabled() configuration method under luciq block directly.

The exact mapping of Instabug's plugin configurations' changes in naming is as follows:

To complete Plugin's configurations' migration, the following should be done in order:

1. Change the name of instabug/Instabug blocks to luciq
2. If you are using both blocks, instabug and Instabug, merge the blocks' contents under a single luciq block.
3. If the configuration block, which is now luciq, has APM (upper case) block inside, change it to apm (lower case)
4. If apm block has debugEnabled = {boolean} property set, remove it and add setDebugLogsEnabled({boolean}) to the top-level luciq block

Example (1): Using only the legacy Instabug config block

Before:

Instabug {
   APM {
      debugEnabled = true
      networkEnabled = false
      fragmentSpansEnabled = true
   }
}

After:

luciq {
   // Added for backward compatibility with apm.debugEnabled = true
   setDebugLogsEnabled(true)
   apm {
      // debugEnabled = true is removed
      networkEnabled = false
      fragmentSpansEnabled = true
   }
}

Example (2): Using both blocks, Instabug (legacy) and instabug

Before:

Instabug {
   APM {
      debugEnabled = true
      networkEnabled = false
      fragmentSpansEnabled = true
   }
}

instabug {
   setDebugLogsEnabled(false)
   setCaptureComposeNavigationDestinations(true)
   compilerExtension{
      // Compiler extension configurations
   }
}

After:

luciq {
   // Value changed to true for backward compatibility with apm.debugEnabled = true
   setDebugLogsEnabled(true)
   setCaptureComposeNavigationDestinations(true)
   apm {
      // debugEnabled = true is removed
      networkEnabled = false
      fragmentSpansEnabled = true
   }
   compilerExtension{
      // Compiler extension configurations
   }
}

Example (3): Using only the new instabug block

Before:

instabug {
   setDebugLogsEnabled(false)
   setCaptureComposeNavigationDestinations(true)
   apm {
      debugEnabled = true
      networkEnabled = false
      fragmentSpansEnabled = true
   }
   compilerExtension{
      // Compiler extension configurations
   }
}

After:

luciq {
   // Value changed to true for backward compatibility with apm.debugEnabled = true
   setDebugLogsEnabled(true)
   setCaptureComposeNavigationDestinations(true)
   apm {
      // debugEnabled = true is removed
      networkEnabled = false
      fragmentSpansEnabled = true
   }
   compilerExtension{
      // Compiler extension configurations
   }
}

Step 4: Migrate your source code (Kotlin/Java)

The key changes done when it comes to source code:

1. All SDK packages are now prefixed with ai.luciq instead of com.instabug
2. All publicly usable classes/methods containing Instabug, IBG, instabug or ibg in their naming is now replaced with Luciq or luciq according to casing.

The exact mapping for publicly available classes/methods is as follows:

To conduct a successful migration, the following steps should be executed to all Java/Kotlin files in your source code:

1. Replace the prefix com.instabug of any import statement with ai.luciq
2. If you're using any of Instabug's public classes with fully qualified name in code, replace package prefix com.instabug with ai.luciq
3. Follow classes/methods mapping table to replace any Instabug symbol in use with Luciq's equivalent
4. If you're adding any of Instabug's classes to your proguard-rules files for any reason, make sure to replace com.instabug package prefix with ai.luciq there too!

Step 5: Migrate your Manifest file

You don't have to execute this step unless one of the following cases applies:

1. You're specifying your Instabug's application token as a metadata element, com.instabug.APP_TOKEN, for early SDK initialization.
2. You're overriding one of Instabug's defined framework components, like Activities or ContentProviders, to either remove or alter the specifications originally declared.

If none of the above applies, you can safely skip this step.

The exact mapping table for Instabug's framework components, having “Instabug” in their names, is as follows:

To complete the migration of your Manifest.xml file, you need to do the following:

1. If you're specifying Instabug token as a metadata element with key com.instabug.APP_TOKEN, you need to change the key to ai.luciq.APP_TOKEN
2. If you're overriding any of Instabug components, you need to replace com.instabug package name prefix of components with ai.luciq
3. Map components' names as specified by the mapping table.

Step 6: Migrate your resources

If your project is not using instabug_config.json file for customizing Instabug’s endpoints, you can safely skip this step.

To complete the configurations' file migration, you need to do the following:

1. Change the file name to luciq_config.json instead of instabug_config.json
2. In the file content, replace the key instabug_domain with luciq_domain

Automated Migration Script

Introduction

To simplify and accelerate the migration process, we've developed a comprehensive automated migration script that handles all the steps outlined in this guide. The Luciq Migrator is a Python-based tool that automatically migrates your Android project from Instabug SDK to Luciq SDK, covering:

• Gradle Files: Version catalogs (libs.versions.toml), dependencies, and plugin configurations → See Step 1 & Step 2
• Plugin Configurations: Legacy and new configuration block migrations → See Step 3
• Java/Kotlin Source Code: Package imports, class names, method names, and fully qualified references → See Step 4
• Android Manifests: App tokens and ContentProvider declarations → See Step 5
• Resource Files: Configuration files (instabug_config.json → luciq_config.json) → See Step 6
• ProGuard Rules: Package name references → See Step 4

The script ensures 100% accuracy by following the exact mapping tables defined in this guide, while providing safety features like automatic backups and dry-run previews.

Where to find it?

You can find the migration script in Luciq's Github public repository (link).

Step-by-Step Usage Guide

Step 1: Extract the Migration Scripts

1. Extract the luciq-migrator.zip file in your Android project root directory:

   cd /path/to/your/android/project
   unzip luciq-migrator.zip
   

2. Verify the directory structure:

   your-android-project/
   ├── luciq-migrator/          # ← Migration scripts directory
   ├── src/                     # ← Your project source code
   ├── build.gradle             # ← Your project files
   └── ...
   

Step 2: Make the Script Executable

chmod +x luciq-migrator/migrate-to-luciq.sh

Step 3: Preview Changes (Recommended)

Always preview changes first to understand what will be modified:

./luciq-migrator/migrate-to-luciq.sh --dry-run --output-file migration-preview.txt

This will show you:

• All files that will be modified
• Exact changes that will be made
• Migration statistics
• No actual changes are applied

Step 4: Run the Migration

Once you're satisfied with the preview, run the full migration:

./luciq-migrator/migrate-to-luciq.sh

The script will:

• Create a complete backup of your project in migration-backup/
• Migrate all files according to the mapping tables
• Provide detailed statistics of the migration process

Step 5: Verify the Migration

After migration, verify that everything was converted correctly:

# Check for any remaining Instabug references
grep -r "com\.instabug" . --exclude-dir=migration-backup

# Build your project to ensure everything compiles
./gradlew clean build

Options Catalog

The migration script provides several options to customize the migration process:

Basic Options

Advanced Options

Combining Options

You can combine multiple options for specific use cases:

# Preview source-only changes
./luciq-migrator/migrate-to-luciq.sh --source-only --dry-run

# Run source-only migration without backup (advanced users)
./luciq-migrator/migrate-to-luciq.sh --source-only --no-backup

# Run migration on a specific project path
./luciq-migrator/migrate-to-luciq.sh /path/to/different/project

Migration Modes

The script supports two migration modes:

🔄 Comprehensive Mode (Default)

• Migrates all file types: Gradle, Java/Kotlin, Manifest, Resources
• Handles complex plugin configurations
• Uses regex-based TOML parsing for version catalog support
• Recommended for most users

📝 Source-Only Mode (--source-only)

• Migrates only: Java/Kotlin files, Manifest, Resources
• Skips all Gradle file migrations
• No external dependencies required
• Use when: You've already migrated Gradle files manually or want staged migration

Safety Features

🛡️ Automatic Backup: Creates complete project backup before migration
👁️ Dry Run Mode: Preview all changes without applying them
📊 Detailed Statistics: Shows exactly what was modified
🔄 Easy Rollback: Restore from backup if issues occur
⚡ Zero Dependencies: No external modules required, uses built-in Python functionality

System Requirements

• Python 3.6+: The script requires Python 3.6 or higher
• No External Dependencies: Uses built-in Python modules only
• All Migration Scripts: Must be kept in the same directory

💡 Pro Tip: Always run --dry-run first to understand the scope of changes, especially on large projects. The migration script is designed to be safe and reversible, but previewing changes helps ensure confidence in the process.

Q&As

Migration Preparations

Q: What should I do before starting the migration process?

Before proceeding with the migration from Instabug to Luciq, you've to:

1. Commit all the changes you currently have on your working branch to ease the ability of reverting migration changes.
2. Clean build cache using ./gradlew clean
3. Sync the project making sure that all dependencies are correctly resolved
4. Build the project to make sure it compiles successfully
5. Ensure stable internet connection for new dependencies download

Instabug Version Compatibility

Q: Is there a recommended Instabug version to be in use before migration?
It's recommended that Instabug version 16.0.0 or higher be in use for the migration to proceed gracefully.

Q: Will Instabug artifacts still be available by the time I do the migration?
Yes. Instabug artifacts will resume to be available with the last version being 16.0.1

Q: Is it possible to proceed with the migration without upgrading to Instabug version 16.0.0?
It's generally not recommended because major releases of Instabug SDK might have included breaking changes, like APIs removal for example, which might be the cause of build issues after completing the migration.

In addition, the guides provided in this document do not take into consideration any previously removed APIs. So, to migrate directly from a version older than 16.0.0 you've to revise Instabug's major releases' change logs to know more about removed APIs and adjust your usage accordingly.

Q: What's the expected output of migrating from older version than 16.0.0 without revising change logs?
If any of the previously removed APIs is in use by your project before the migration, it will end up with unresolved references compilation issues.

Automated Script

Q: Are there specific system requirements to run the automated script?
The automated script is written in python. So, the only requirement is to have Python 3.6+ installed.

To figure out which python version installed, you can run python3 --version.

Q: What exactly does the script do?
The script performs a comprehensive migration covering all of the 6-steps outlined. In a nutshell, the script:

1. Alters legacy Instabug dependencies with Luciq equivalent in your project configuration files.
2. Adjusts SDK's Gradle Plugin configurations
3. Do the necessary adjustments to your source code files (Kotlin/Java).

Q: What types of build configurations the script supports?
The automated script supports:

1. Version catalog (.toml)
2. buildSrc modules
3. build.gradle files (groovy/kts)

Q: When should I totally depend on the script to carry-out the migration?
In most cases, the script will carry-out the migration gracefully unless your project's build configuration files are custom or not following general Android development patterns.

Q: If build configurations are custom in my project, will I have to carry-out all the migration steps manually?
No, you can upgrade your dependencies (build configuration files) executing migration steps 1 through 3 in the guide manually then run the script with --source-only mode to handle your source code.

Q: My project is version controlled. Is it mandatory for the script to create a backup folder?
No. If your project is version controlled, it's generally advisable to run the script with --no-backup option to prevent it from creating the backup folder.

Q: Am using Instabug version lower than 16.0.0, is it still possible to use the automated script?
It's generally not recommended for the same considerations listed in Instabug Version Compatibility section.