Droid Manual // Android Knowledge Base

Droid Manual

Integrating Third-Party SDKs in Android

October 28, 2026 · 8 min read

Introduction

Integrating third-party SDKs is one of the most routine yet delicate tasks in Android development. A single misconfigured dependency can bloat your APK, trigger runtime crashes, or introduce subtle memory leaks that surface only under production load. This tutorial walks through the practical concerns every engineer faces when pulling in external libraries—starting from the basics of Gradle resolution and moving into conflict management, multidex boundaries, keep rules, and lazy bootstrapping. The goal is to leave you with a repeatable workflow that keeps builds fast, packages lean, and SDK lifecycles under your control.

Adding SDKs via Gradle Dependencies

The first step is always declaring the library in the right Gradle file. Modern Android projects typically use the version catalog approach, which centralizes all third-party references and eliminates magic strings scattered across modules. A well-maintained catalog also makes it trivial to upgrade versions in a single place.

// gradle/versions.gradle.kts
val timber = "com.jakewharton.timber:timber:5.0.1"
val coil = "io.coil-kt:coil:2.6.0"
val retrofit = "com.squareup.retrofit2:retrofit:2.11.0"
val okhttp = "com.squareup.okhttp3:okhttp:4.12.0"
val moshi = "com.squareup.moshi:moshi-kotlin:1.15.1"

This version catalog file defines all SDK coordinate pairs as plain string constants. You reference them from your module-level build.gradle.kts using the libs auto-generated accessor or by applying the catalog directly. Keeping versions in one file prevents accidental drift between modules and makes a full audit as simple as opening a single source file.

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

dependencies {
    implementation(libs.timber)
    implementation(libs.coil)
    implementation(libs.retrofit)
    implementation(libs.okhttp)
    implementation(libs.moshi)
    implementation(libs.moshi.kotlin)
}

The implementation configuration is critical here—it ensures the SDK's transitive dependencies are available at compile time within the module but are not leaked into the public API surface. If you ever need the library on the classpath during compilation but not at runtime, you would switch to compileOnly, but for the vast majority of SDK integrations implementation is the correct choice.

Resolving Dependency Conflicts

When two SDKs depend on different versions of the same library, Gradle resolves the conflict by picking the highest non-conflicting version it can find. This silent resolution is a common source of bugs, especially when an older version of a support library is silently preferred and drops APIs your code expects.

// app/build.gradle.kts
configurations.all {
    resolutionStrategy {
        force("androidx.core:core-ktx:1.13.1")
        force("com.google.guava:guava:33.2.1-jre")
    }
}

The resolutionStrategy.force() call tells Gradle to always select the specified version regardless of what any transitive dependency requests. Use this sparingly—forcing too many coordinates creates a maintenance burden and can break other libraries that genuinely need their expected version. A better first step is usually to inspect the tree before forcing anything.

./gradlew :app:dependencies --configuration releaseCompileClasspath

Running the dependencies task produces a full tree showing every transitive pull. Look for repeated library coordinates with mismatched versions; those are your conflict hotspots. Pinning versions in the version catalog rather than scattering force() calls throughout build files gives you a single source of truth and makes audits straightforward.

Multidex Configuration

Adding enough SDKs—and particularly pulling in large ones like Facebook's entire ecosystem—can push your method count past the 65,536 limit that triggers a multidex build. Modern Android projects starting from API 21 and above do not need an explicit multidex setup because the runtime supports it natively, but if your minSdk is lower or you are building a split APK, you still need to configure it explicitly.

<!-- AndroidManifest.xml -->
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:theme="@style/Theme.MyApp">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

Notice that the android:name attribute points to a custom Application subclass. This is required because the default Application class does not include multidex forwarding logic. Your custom application class must extend MultiDexApplication or call MultiDex.install(this) during initialization.

// app/src/main/java/com/example/myapp/MyApplication.kt
package com.example.myapp

import android.app.Application
import androidx.multidex.MultiDex

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        MultiDex.install(this)
    }
}

Calling MultiDex.install(this) ensures the secondary DEX files are loaded before any SDK initialization code runs. If you skip this step on devices below API 21, the app will crash with a ClassNotFoundException the moment the SDK tries to load a class from a secondary DEX. On API 21 and above, the system loader handles secondary DEX files automatically, but calling install() remains harmless and keeps your behavior consistent across all supported devices.

ProGuard and R8 Rules

Every SDK adds classes that R8 or ProGuard needs to preserve at shrink time. Without proper keep rules, the optimizer will strip constructors, rename fields, or remove methods that the SDK accesses reflectively. Most well-maintained libraries ship their own proguard-rules.pro file, which you must include explicitly.

// app/build.gradle.kts
android {
    buildTypes {
        release {
            minifyEnabled(true)
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
                "retrofit.pro",
                "moshi.pro"
            )
        }
    }
}

The proguardFiles list accepts multiple files in order, and each file appends its rules to the active rule set. Shipping the library-specific .pro files from the SDK vendor alongside your project's own proguard-rules.pro ensures you cover both custom application rules and the vendor requirements in one pass.

# proguard-rules.pro
-keepattributes Signature, InnerClasses, EnclosingMethod
-keepclasseswithmembers class * {
    @retrofit2.http.* <methods>;
}
-keepclassmembers class * {
    @org.json.annotation.* <fields>;
}

These rules preserve annotated members so that reflection-based frameworks like Retrofit and Moshi can locate them at runtime. The @keep annotation approach is the modern replacement for hand-written proguard-rules.pro entries— annotate the classes or fields you need preserved and R8 will respect them automatically. Prefer annotations over manual rules whenever the SDK author provides them, because annotation-based rules survive refactoring and IDE renames.

Lazy Initialization of SDKs

Initializing every SDK during application startup is a fast track to a sluggish cold start. Many SDKs—analytics, crash reporting, push notifications—do not need to be active the instant Application.onCreate() finishes. A lazy holder pattern defers initialization until the first real usage, reducing startup time and preserving memory for SDKs that may never be touched in a given session.

// app/src/main/java/com/example/myapp/sdk/LazyAnalytics.kt
package com.example.myapp.sdk

import android.content.Context
import com.example.myapp.analytics.AnalyticsClient

class LazyAnalytics(private val context: Context) {
    private var instance: AnalyticsClient? = null

    fun get(): AnalyticsClient {
        return instance ?: AnalyticsClient.initialize(context).also { instance = it }
    }

    fun shutdown() {
        instance?.shutdown()
        instance = null
    }
}

The LazyAnalytics wrapper holds a nullable reference and performs initialization only on the first call to get(). This means the analytics SDK payload sits dormant until your UI actually logs an event. The shutdown() method is included so you can release resources on specific flows, such as when a user opts out of tracking or signs out.

// app/src/main/java/com/example/myapp/MyApplication.kt
package com.example.myapp

import android.app.Application
import androidx.multidex.MultiDex
import com.example.myapp.sdk.LazyAnalytics
import com.example.myapp.sdk.LazyCrashReporter

class MyApplication : Application() {
    val analytics by lazy { LazyAnalytics(this) }
    val crashReporter by lazy { LazyCrashReporter(this) }

    override fun onCreate() {
        super.onCreate()
        MultiDex.install(this)
    }
}

Using Kotlin's built-in by lazy delegate inside the Application class gives you thread-safe, single-shot initialization with zero additional boilerplate. The delegates themselves resolve only when analytics or crashReporter is accessed for the first time, keeping the cold-start path lean and predictable.

Keeping the Build Lean

Beyond configuration, the health of your SDK surface depends on regular audits. Every added dependency increases APK size, attack surface, and build complexity. A disciplined approach to SDK hygiene pays compound interest over the lifetime of the project.

// app/build.gradle.kts
android {
    packaging {
        jniLibs {
            excludes += listOf(
                "**/libfb.so",
                "**/librealm-jni.so"
            )
        }
        resources {
            excludes += listOf(
                "META-INF/*.properties",
                "META-INF/LICENSE.md",
                "META-INF/NOTICE.md"
            )
        }
    }
    buildFeatures {
        buildConfig = false
    }
}

The packaging.jniLibs.excludes block lets you strip unused native libraries from multi-architecture SDK packages—common when an SDK bundles .so files for every ABI but your app only targets arm64-v8a. The resources.excludes block removes redundant metadata files that add bytes without providing value. Disabling buildConfig prevents the generator from creating a class that inflates the DEX when the app does not actually use it.

Between each code example, you should verify the outcome manually: open the APK Analyzer, check the dependency tree for duplicates, and run a signed release build to confirm that R8 preserved the right symbols. A fast feedback loop here saves hours of debugging later.

Common Pitfalls

Several mistakes recur every time a new team adds third-party SDKs, and recognizing them early prevents costly rework.

Caching stale resolutions: Gradle occasionally serves cached transitive results that do not reflect a newly forced version. Always run ./gradlew --refresh-dependencies after changing resolution rules to ensure the graph is recomputed.

Ignoring dual-use libraries: Some SDKs bundle their own copy of Gson, OkHttp, or Coroutines. When two SDKs ship incompatible versions of the same library, the conflict is resolved at runtime in unpredictable ways. Use dependencyInsight to trace which provider wins in each scenario.

Over-minifying: Aggressive shrinking without reviewing the R8 mapping file can silently break SDK reflection. Keep the mapping.txt from each release build and spot-check suspicious stack traces against it.

Initializing on the main thread: Many SDKs perform disk reads or network checks during initialize(). Forgetting to defer this work until a background thread causes ANRs on startup, particularly on slower devices.

Conclusion

Integrating third-party SDKs is less about copying coordinates into a build file and more about understanding the lifecycle, resolution, and shrink behaviors that surround every external dependency. Use a version catalog to keep coordinates visible, resolve conflicts transparently with tree inspection, configure multidex correctly for lower API levels, ship the right R8 keep rules, lazy-initialize heavy SDKs, and prune unused packaging assets regularly. When you treat SDK integration as a disciplined process rather than a copy-paste task, your app stays fast, small, and stable even as the library surface grows.

More Android guides