Bring Your Own Links

Companies with established deep link infrastructure can add deferred deep link support without replacing their URLs with Trace short links. Embed a lightweight JS snippet on your landing pages — Trace records click fingerprints and matches them to installs using the same attribution pipeline.

Note

BYOL is included on the Scale plan. On the Growth plan it’s available as a paid add-on ($49/month). Enable it with:

trace apps addon --addon byol

Sandbox clicks are always free on any plan — add sandbox: true (or data-sandbox="true") to test your integration before enabling the add-on.

How it works

1. A user visits your landing page (e.g. yourapp.com/product/123)
2. The trace.js snippet records a click fingerprint to the Trace API
3. The user installs your app from the App Store or Play Store
4. On first open, the Trace SDK matches the install to the click
5. Your app receives the deep link payload (/product/123) as a deferred deep link

Setup

1. Add the snippet to your landing page

Generate a ready-to-paste snippet with the CLI:

trace byol snippet --deep-link-path /product/123 --campaign-id summer-sale

This outputs a <script> tag pre-filled with your publishable key and app store URLs. You can also build it manually:

Declarative

Add the script tag with data- attributes. The click is recorded automatically on page load.

<script src="https://api.traceclick.io/trace.js"
        data-api-key="tr_pub_xxxxxxxxxxxx"
        data-deep-link-path="/product/123"
        data-deep-link-params='{"sku":"ABC","ref":"email"}'
        data-campaign-id="summer-sale">
</script>

Programmatic

Load the script once, then call Trace.recordClick() when needed (e.g. on button click, after consent).

<script src="https://api.traceclick.io/trace.js"></script>
<script>
Trace.recordClick({
  apiKey: "tr_pub_xxxxxxxxxxxx",
  deepLinkPath: "/product/123",
  deepLinkParams: { sku: "ABC", ref: "email" },
  campaignId: "summer-sale"
}).then(function(response) {
  console.log("Click recorded:", response.clickId);
});
</script>

Tip

Use your publishable key (tr_pub_...) in the snippet — it’s safe to embed in public HTML and can only record clicks, not read data. Find it with trace byol snippet or trace apps info --json.

2. Handle deep links in your app

Deep links from BYOL arrive the same way as Trace short link deep links — through the SDK listener:

Trace.setDeepLinkListener { deepLink ->
    val path = deepLink.path        // "/product/123"
    val params = deepLink.params    // {"sku": "ABC", "ref": "email"}
    val deferred = deepLink.isDeferred // true
    navigateTo(path, params)
}

See Deep Links for the full routing guide including type-safe Nav3 integration and auth gates.

3. (Optional) App store redirect

The snippet can redirect users to the correct app store after recording the click. Add data-redirect="true" and your store URLs:

<script src="https://api.traceclick.io/trace.js"
        data-api-key="tr_pub_xxxxxxxxxxxx"
        data-deep-link-path="/product/123"
        data-redirect="true"
        data-android-url="https://play.google.com/store/apps/details?id=com.yourapp"
        data-ios-url="https://apps.apple.com/app/yourapp/id123456789"
        data-fallback-url="https://yourapp.com/download">
</script>

Or programmatically:

Trace.recordClick({
  apiKey: "tr_pub_xxxxxxxxxxxx",
  deepLinkPath: "/product/123",
  redirect: true,
  androidUrl: "https://play.google.com/store/apps/details?id=com.yourapp",
  iosUrl: "https://apps.apple.com/app/yourapp/id123456789",
  fallbackUrl: "https://yourapp.com/download"
});

Tip

On Android, the snippet automatically appends the clickId as a Play Store referrer (&referrer=trace_click_id=...). This upgrades the match from fingerprint-based to deterministic — the install referrer carries the click ID directly to the SDK.

If you’ve already configured your Play Store and App Store URLs in your app settings (via trace apps update), you can omit data-android-url and data-ios-url — the API returns your configured store URLs and the snippet uses them as fallbacks.

Manual referrer (without redirect)

If you handle the redirect yourself, you can still use the clickId for deterministic Android matching:

Trace.recordClick({ ... }).then(function(r) {
  var playUrl = "https://play.google.com/store/apps/details?id=com.yourapp"
    + "&referrer=" + encodeURIComponent("trace_click_id=" + r.clickId);
  window.location.href = playUrl;
});

Snippet reference

Script attributes

Attribute	Required	Description
data-api-key	Yes	Your Trace API key
data-deep-link-path	Yes	Path delivered to the app (e.g. /product/123)
data-deep-link-params	No	JSON object of extra parameters
data-campaign-id	No	Campaign identifier for analytics grouping
data-redirect	No	Set to "true" to redirect to the app store after recording
data-android-url	No	Play Store URL (overrides app settings)
data-ios-url	No	App Store URL (overrides app settings)
data-fallback-url	No	Fallback URL for desktop/unknown platforms
data-sandbox	No	Set to "true" to record a test click (no add-on required)

Trace.recordClick(options)

Option	Type	Required	Description
apiKey	string	Yes	Your Trace API key
deepLinkPath	string	Yes	Path delivered to the app
deepLinkParams	object	No	Extra key-value parameters
campaignId	string	No	Campaign identifier
redirect	boolean	No	Redirect to the app store after recording
androidUrl	string	No	Play Store URL (overrides app settings)
iosUrl	string	No	App Store URL (overrides app settings)
fallbackUrl	string	No	Fallback URL for desktop/unknown platforms
sandbox	boolean	No	Record a test click (no add-on required)

Returns a Promise<{ clickId: string, androidUrl?: string, iosUrl?: string }>.

Collected signals

The snippet automatically collects the same device signals as Trace short links:

• Screen dimensions (physical pixels)
• Device pixel ratio
• Timezone
• OS version (via Client Hints with User-Agent fallback)
• Device model
• Locale

These signals are used for fingerprint matching during install attribution.

API endpoint

The snippet calls POST /v1/clicks/record under the hood. You can also call it directly from your server if you prefer server-side click recording.

curl -X POST https://api.traceclick.io/v1/clicks/record \
  -H "X-Api-Key: tr_pub_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "tr_pub_xxxxxxxxxxxx",
    "deepLinkPath": "/product/123",
    "deepLinkParams": {"sku": "ABC"},
    "campaignId": "summer-sale",
    "screenWidth": 1080,
    "screenHeight": 2400,
    "screenDensity": 3.0,
    "timezone": "America/New_York",
    "osVersion": "15.0",
    "deviceModel": "Pixel 9",
    "locale": "en-US"
  }'

Returns 201 Created:

{
  "clickId": "a1b2c3d4-...",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.yourapp",
  "iosUrl": "https://apps.apple.com/app/yourapp/id123456789"
}

The androidUrl and iosUrl fields are populated from your app settings. They are null if not configured.

Rate limited to 300 requests per minute per API key.