[FEATURE] Manual initialization support

[musilto7]

Summary

Please add support for manual initialization of DebugOverlay as an alternative to the automatic AndroidX Startup initializer.

Motivation

Our app has minSdk = 23. Since DebugOverlay requires a higher API level, we need to conditionally disable it on SDK 23 devices. Currently the only way to do this is to disable DebugOverlayStartupInitializer entirely in the manifest:

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    tools:node="merge">
    <meta-data
        android:name="com.ms.square.debugoverlay.DebugOverlayStartupInitializer"
        tools:node="remove" />
</provider>

But this disables DebugOverlay for all SDK versions, not just SDK 23.

Proposed API

Expose a public install() method so we can call it manually with an SDK version check:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
            DebugOverlay.install(this)
            DebugOverlay.configure {
                  // configuration
            }
        }
    }
}

Current behavior

DebugOverlay.install() is marked @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) and @InternalDebugOverlayApi, making it inaccessible to app code. There is no supported way to manually initialize the library.

Expected behavior

A public install(application: Application) method that allows manual initialization, so developers can conditionally initialize DebugOverlay based on SDK version or any other runtime condition.

Thank you!

[coderabbitai]

🔗 Related PRs

#87 - [refactor] make DebugOverlayNetworkInterceptor auto-register with DebugOverlay [merged]
#90 - [refactor] remove the non-androidx startup installer [merged]
#118 - [misc] enable binary compatibility validation tool [merged]
#119 - [feat] address a case where a debug overlay shows below dialogs [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Manabu-GT]

Hi @musilto7, thanks for the write-up!

Quick question: have you actually observed DebugOverlay crash or misbehave on SDK 23?
Asking because I don't recall using any API that strictly requires SDK 24+.

I assumed you added this in your app's AndroidManifest.xml to allow your minSdk = 23 app to depend on the library:
<uses-sdk tools:overrideLibrary="com.ms.square.debugoverlay" />

If it actually crashes or misbehaves, please share the stack trace so I can take a look.

Thanks!