App Links (Android): Setup & Troubleshooting

What are Android App Links?

Android App Links are verified HTTPS URLs that open your app directly when the domain is proven to belong to the app. Verification is done via Digital Asset Links — a JSON file (/.well-known/assetlinks.json) on your domain that lists your app’s package name and SHA-256 certificate fingerprints.

When a user taps an eligible link, Android checks the verification status. If the relationship is verified and your activity declares an intent filter for the domain, the link opens the app (no chooser dialog). If not verified or the app isn’t installed, it falls back to the browser (and from there you can redirect to Play).

• Secure ownership: only apps listed in assetlinks.json can claim your domain.
• Better UX: no custom-scheme collisions or pickers; links look and share like normal URLs.
• SEO-friendly: one canonical web URL works on web and can deep-link into the app.

How SDDL helps: you enter your package name and SHA-256 fingerprints once; SDDL publishes assetlinks.json automatically and provides smart links that preserve context across install (restored in-app via the SDK).

1) Enable App Links

Gradle setup

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.github.nonanerz:sddl-android-sdk:2.0.9") // use latest
}

AndroidManifest intent-filter

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTop">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="{YOUR_ID}.sddl.me OR {your.custom.domain}"
            android:pathPrefix="/" />
    </intent-filter>

</activity>

You do not host assetlinks.json yourself — SDDL publishes it automatically for your domain based on your app configuration (package name + SHA-256 fingerprints).

2) Handle links with the SDDL Android SDK

Kotlin example:

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        SDDLHelper.resolve(this, intent, ::routeWith, ::handleDeepLinkError, readClipboard = false)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        SDDLHelper.resolve(this, intent, ::routeWith, ::handleDeepLinkError, readClipboard = false)
    }

    private fun routeWith(payload: JsonObject) {
        // Navigate using values from payload
    }

    private fun handleDeepLinkError(error: String) {
        // Optional: log or show a non-blocking message
    }
}

3) Checks & Tips

• Domains: use {YOUR_ID}.sddl.me or your verified custom domain (HTTPS only).
• Set android:autoVerify="true" so Android verifies the domain → links open the app directly.
• Add all SHA-256 fingerprints (debug + release) in SDDL to publish a complete assetlinks.json.
• After changing fingerprints or manifest, uninstall and reinstall the app to refresh verification.
• If links start opening in the browser, clear the default handler for your browser or re-check domain verification.
• Implement a “cold start” call in your app to restore deferred context after install via the SDK.

4) Testing

• On device: copy an https:// link to your domain and tap it from a note/email — it should open your app.
• Use adb to simulate: adb shell am start -a android.intent.action.VIEW -d "https://your.domain/path".
• If verification is pending, give it a minute after install or reinstall the app (Android refreshes association during install).

FAQ