Skip to content
Ferry Ferry Docs

Android SDK

The Ferry Android SDK supports Android API 24 and later. It uses AndroidX and the Play Install Referrer client, and accepts only a project pk_ public key.

Add the dependency

The SDK is available from Maven Central. Make sure mavenCentral() is included in your repositories, then add the dependency:

app/build.gradle.kts
dependencies {
    implementation("io.ferrylink:ferry-android:0.1.0")
}

1. Configure in your Application

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Ferry.configure(
            context = this,
            publicKey = "pk_test_xxx"
        )
    }
}

configure records the key. Deferred matching starts when the app first registers Ferry.onLink.

Ferry.onLink { link ->
    when (link.data["screen"]) {
        "product" -> router.showProduct(link.data["product_id"])
        "cart" -> router.showCart()
        else -> router.showHome()
    }
}

link.isDeferred is true for a first-install match and false for a direct App Link open. Use that field when the distinction matters. Do not infer it from the match method.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Ferry.onLink { link -> route(link) }
        Ferry.handle(intent)
    }


    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        Ferry.handle(intent)
    }
}
<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">
    <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="acme.feryl.io" />
        <data android:scheme="https" android:host="go.acme.com" />
    </intent-filter>
</activity>

Every listed hostname must serve /.well-known/assetlinks.json with the app package name and signing certificate fingerprint. Ferry publishes this file from the project configuration for hostnames assigned to that project.

5. Track events

Ferry.track(FerryTrackEvent.Login, customerId = "customer_42")
Ferry.track(FerryTrackEvent.Signup, customerId = "customer_42")
Ferry.track(
    FerryTrackEvent.Purchase(
        transactionId = "txn_1",
        value = 9.99,
        currency = "USD",
        productId = "pro_monthly"
    ),
    customerId = "customer_42"
)

Observe installation results

Ferry.onInstallation { result ->
    val isFirstRecord = result.isNewInstallation
    val attribution = result.attribution
}

An organic first open has no link to route, so it appears through onInstallation rather than onLink.

Important behavior

  • Play Install Referrer is the strongest Android first-install signal.
  • Fingerprint matching is used only when the referrer does not carry a Ferry click ID.
  • A definitive attributed or organic response resolves the installation.
  • A temporary transport failure may retry on a later launch, up to the SDK’s bounded attempt limit.
  • Events are queued and batched automatically.
  • SDK failures degrade to no link and do not crash the host app.

Next steps