Skip to content
Ferry Ferry Docs

Link payloads

A Ferry link carries a small payload that tells your app what to open.

{
  "data": {
    "screen": "product",
    "product_id": "sku_123",
    "offer": "WELCOME"
  },
  "url": "https://www.example.com/products/sku_123"
}

Payload shape

FieldTypePurpose
dataString-to-string objectPrimary routing instructions for the app
urlHTTPS URL, optionalWeb or app fallback context selected by a trusted link creator

Every value inside data is a string. This keeps the payload stable across Swift, Kotlin, Dart, TypeScript, URLs, and the Ferry edge.

Route from data

Treat data as a versioned message to your navigation layer:

screen = product
product_id = sku_123

Prefer durable identifiers and actions over visual details. For example, send product_id=sku_123, then fetch the current product title and price inside the app.

Good payloads:

{ "screen": "product", "product_id": "sku_123" }
{ "screen": "invite", "invite_code": "ABCD12" }
{ "screen": "cart", "coupon": "WELCOME" }

Avoid payloads that contain:

  • Secrets or access tokens.
  • Names, email addresses, phone numbers, or other personal data.
  • Entire application objects.
  • Presentation details that become stale.
  • Platform-specific view-controller or activity names.

Handle unknown values safely

Apps and links are released independently. An older app can receive a link created after that app version shipped.

Always provide a safe fallback:

switch link.data["screen"] {
case "product":
    router.showProduct(id: link.data["product_id"])
case "cart":
    router.showCart()
default:
    router.showHome()
}

Do not crash when a key is missing or a new route is unknown.

A template link is created once in the Ferry dashboard. Query parameters on an opened link are merged into its payload at the edge.

For a template with:

{ "screen": "profile" }

Opening:

https://acme.feryl.io/share?user_id=u_42

delivers:

{
  "screen": "profile",
  "user_id": "u_42"
}

Use templates when many links share the same route and differ only by a few data values. This avoids an SDK call for each share.

Client-created payloads

Links created from a public SDK are deliberately data-only. The app cannot choose a redirect destination, campaign metadata, or a permanent lifetime. Ferry applies the project’s configured fallback and a seven-day expiry.

See create links in your app for the supported sharing flow.