Skip to content
Ferry Ferry Docs

SDK quickstart

This quickstart takes you from a new Ferry project to a link that routes inside your app.

Before you begin

You need:

  • An iOS, Android, Flutter, or React Native app.
  • A Ferry account and project.
  • Your app’s bundle ID or Android package name.
  • At least one store destination and a web fallback URL.

  1. Create a project

    In the Ferry dashboard, create a project for one app. Select the project’s analytics timezone, then add the app identifiers and destinations Ferry should use when the app is not installed.

  2. Claim a link domain

    Claim a shared hostname such as acme.feryl.io, or connect one custom hostname such as go.acme.com.

    Each hostname belongs to one Ferry project. Ferry uses that project to publish the platform association files and choose the correct redirect behavior.

  3. Copy the public project key

    Copy the pk_ key for the project. This key is intentionally safe to ship in the app and is the only credential a Ferry SDK accepts.

    Never add an sk_ key to application code, mobile configuration, or a bundled environment file.

  4. Add your platform SDK

    Choose the guide for your app:

  5. Register your link handler

    Every SDK exposes one listener for both direct and deferred links. Register it early and route using the customer-defined data payload.

    Ferry link received
      data.screen = "product"
      data.product_id = "sku_123"
      isDeferred = false or true
    

    Your router
      open product "sku_123"

  6. Connect the app to the domain

    iOS requires the Associated Domains entitlement. Android requires an autoVerify App Links intent filter. Flutter and React Native still require the corresponding native platform configuration.

  7. Create and open a test link

    In the dashboard, create a link with a payload such as:

    {
      "data": {
        "screen": "product",
        "product_id": "sku_123"
      }
    }

    Open the generated https:// link on a physical device. Confirm that an installed app opens the expected screen.

  8. Test a fresh installation

    Delete the app, open the same Ferry link, install the app from its store destination, then launch it. The same link listener should receive a link with isDeferred set to true when Ferry finds a match.

Success checklist

  • An installed-app link opens the correct screen.
  • A fresh installation receives the intended payload when a match is available.
  • The app has only a pk_ public key.
  • The project dashboard receives a link open.
  • Optional login, signup, and purchase events appear under the originating link.

Next, read link payloads before defining production routes.