Skip to main content

Query Parameter Passthrough

Instead of creating a link per entity, create one opt-in link and append query parameters per use. They reach your app on open and after a deferred install.

Setup​

Create (or update) the link with passthrough enabled:

curl -X POST https://api.ulink.ly/v1/sdk/links \
  -H "x-api-key: $ULINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dynamic",
    "slug": "orders",
    "iosFallbackUrl": "https://apps.apple.com/app/your-app/id0000000000",
    "androidFallbackUrl": "https://play.google.com/store/apps/details?id=com.yourapp",
    "fallbackUrl": "https://yourstore.com/orders",
    "allowQueryPassthrough": true
  }'

Use it​

Append parameters in your emails — no API call per order:

https://your-subdomain.shared.ly/orders?orderId=123&coupon=SUMMER

Replace your-subdomain.shared.ly with the exact domain configured for your project. Do not copy the placeholder as a live link.

Receive it in the app​

The params arrive in the resolved link's parameters, on every path:

// Flutter
ulink.onLink.listen((data) {
  final orderId = data.parameters?['orderId']; // "123"
});
// Android
ulink.onLink.collect { data ->
  val orderId = data.parameters?.jsonObject?.get("orderId")?.jsonPrimitive?.content
}
// iOS
ulink.onLink.sink { data in
  let orderId = data.parameters?["orderId"] as? String
}

Rules & limits​

  • Override: appended params override stored parameters with the same key, and always arrive as strings.
  • Opt-in: only links created with allowQueryPassthrough: true forward params; others ignore appended query strings.
  • Limits: keys [A-Za-z0-9_-]{1,64}, ≤ 25 params, ≤ 1024 chars/value, ≤ 4 KB total; invalid params are dropped. Reserved keys are always stripped and never forwarded: debug, _dbg, _qr, _nodl, _lc, ulhop, d, plus the prototype-chain keys __proto__, constructor, prototype.
  • ulhop: internal to the launch-domain redirect flow. Appending ?ulhop=1 to any link redirects to that link's iOS fallback URL and does not record a click.
  • _lc: a click reference Ulinkly adds to the deep link it opens your app with, so the visit is counted once and shows as opened in the app. The SDKs never return it in parameters. If your app reads the raw deep link URL itself, ignore query parameters it does not know.