Quick Start

This guide walks you through creating an app, installing the SDK, and getting your first attributed install.

Prerequisites

• An Android or iOS app project (or a Kotlin Multiplatform project targeting both)

1. Install the CLI, log in, and create your app

   # macOS
   brew install bmcreations/tap/trace
   
   # log in with your account (opens browser)
   trace login
   
   # create your app
   trace init

   This gives you an API key (e.g. tr_live_xxxx) and a hash salt (64-character hex string). The app is linked to your account automatically.

   See CLI Installation for other platforms or trace login --api-key=xxx for CI/CD.

2. Add the SDK

   Android

   Add the Trace SDK to your module-level build.gradle.kts:

   dependencies {
       implementation("io.traceclick:trace-sdk:<version>")
   }

   iOS

   Add the Trace SDK via Swift Package Manager:

   https://github.com/bmcreations/trace-sdk-ios

   Or add to your Package.swift:

   .package(url: "https://github.com/bmcreations/trace-sdk-ios", from: "<version>")

   KMP

   Add the Trace SDK to your shared module’s build.gradle.kts:

   kotlin {
       sourceSets {
           commonMain.dependencies {
               implementation("io.traceclick:trace-sdk:<version>")
               // Optional: Navigation3 integration for Compose Multiplatform
               implementation("io.traceclick:trace-sdk-nav3-kmp:<version>")
           }
       }
   }

   All Compose components (TraceProvider, rememberDeepLinkMapper, rememberTraceEntryDecorator) work in commonMain — the same code runs on both Android and iOS via Compose Multiplatform. See kmp/ for a complete working example.

3. Initialize on app launch

   Android

   class MyApp : Application() {
       override fun onCreate() {
           super.onCreate()
           Trace.initialize(
               context = this,
               config = TraceConfig(
                   apiKey = "tr_live_xxxxxxxxxxxx",
                   hashSalt = "your_64_char_hex_salt",
                   region = Region.US
               )
           )
       }
   }

   iOS

   @main
   struct MyApp: App {
       init() {
           TraceClient.shared.initialize(
               config: TraceConfig(
                   apiKey: "tr_live_xxxxxxxxxxxx",
                   hashSalt: "your_64_char_hex_salt"
               )
           )
       }
   }

   The SDK is KMP — Android and KMP projects use the same API. On iOS, the Swift package wraps the KMP framework.

   That’s it. The SDK automatically reports the install to Trace and performs attribution on first launch.

4. Create a short link

   CLI

   trace links create --deep-link-path /welcome \
     --campaign-id launch_campaign \
     --fallback-url https://yourapp.com

   Output:

   ✓ Link created
     Short Code   abc123
     Short URL    https://yourapp.traceclick.io/l/abc123
     QR Code URL  https://yourapp.traceclick.io/l/abc123.png

   curl

   curl -X POST https://api.traceclick.io/v1/links \
     -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{
       "deepLinkPath": "/welcome",
       "campaignId": "launch_campaign",
       "fallbackUrl": "https://yourapp.com"
     }'

   Response:

   {
     "shortCode": "abc123",
     "shortUrl": "https://yourapp.traceclick.io/l/abc123"
   }

5. Handle the deep link

   Android

   Trace.setDeepLinkListener { deepLink ->
       // deepLink.path = "/welcome"
       // deepLink.isDeferred = true (arrived via install attribution)
       navigateTo(deepLink.path)
   }

   iOS

   TraceClient.shared.setDeepLinkListener { deepLink in
       // deepLink.path = "/welcome"
       // deepLink.isDeferred = true
       navigateTo(deepLink.path)
   }

What just happened?

1. You created a short link with a deep link path of /welcome
2. When a user clicks that link, Trace records the click and redirects to the app store
3. After the user installs and opens the app, the SDK calls Trace
4. Trace matches the install to the click and returns the attribution result
5. The deferred deep link (/welcome) is delivered to your listener

Next steps

• CLI commands — manage apps, links, metrics, and privacy from the terminal
• Android setup — full integration guide including deep link routing and Navigation3
• iOS setup — Universal Links, SwiftUI .onDeepLink() integration
• Configuration — regions, debug mode, test mode, privacy opt-out
• Deep links — type-safe routing, auth gates, deferred link handling
• Links API — create and manage short links programmatically
• Webhooks — get real-time notifications for installs, opens, and events via Slack, Discord, Teams, or custom HTTP endpoints