Skip to main content

Attribution & Analytics

ChottuLink gives you full-funnel visibility into how users discover, install, and engage with your app. There are three layers:

  • Install Attribution — at first launch, the SDK determines whether the install was organic or came from a ChottuLink click (ATTRIBUTED). It captures the originating link, UTM parameters, and match type, and makes this data available instantly via getAttributionData().
  • Event Analytics — after attribution, you can identify users, track signups, record revenue conversions, and send custom events. All events are queued locally and uploaded in batches, surviving network outages and app restarts.
  • Dashboard & Reporting — view every click, first open, lead, and conversion in the ChottuLink Events dashboard, and trace each attributed install to a customer record.
Prerequisites

Initialize the ChottuLink SDK before calling any of the methods on this page. See your platform's setup guide: iOS · Android · Flutter · React Native · Capacitor · Unity

What is Attribution?​

Attribution answers the question: "Which link caused this user to install my app?" It also helps answer: "How many signups, conversions, and how much revenue did that link generate?"

When a user installs your app, ChottuLink checks whether they previously clicked a ChottuLink link before the install.

There are two possible outcomes:

  • ORGANIC — no matching ChottuLink click was found. The user found and installed your app through another channel (App Store search, word of mouth, etc.).
  • ATTRIBUTED — the install is linked to a specific ChottuLink click. The originating link's data — including the short URL, destination URL, and any UTM parameters — is attached to the install record.

Why it matters: Attribution connects your marketing spend to real outcomes. Instead of guessing which campaigns drive installs, you can see exactly which links, UTM sources, and creatives are working — and which aren't. You can then tie post-install actions (signups, purchases) back to the original campaign that acquired the user.

SDK Reference​

The following methods are available in the ChottuLink SDK for reading attribution data and tracking post-install events.

getAttributionData()​

Returns the cached attribution result for the current install. This is a synchronous call — no network request is made.

When to call this

Call getAttributionData() after SDK initialization — typically when your app's first screen becomes visible.

On subsequent app launches the result is a fast, cached read. On the very first launch, the async attribution fetch runs in the background and may not have completed in the first second or two. If the method returns nil immediately after a cold start:

  • Retry once after a 1–2 second delay, or
  • Use your SDK's initialization callback, which fires after attribution is available — see your platform's setup guide.
note

Returns nil / null / the platform equivalent if:

  • The SDK has not been initialized
  • The user has opted out of tracking via optOut(true)
  • Attribution has not yet completed on this launch (rare — only possible in the very first seconds after a cold start before the async fetch finishes)
import ChottuLinkSDK

if let attribution = ChottuLink.getAttributionData() {

    if attribution.isAttributed {
        // Install came from a ChottuLink click
        print("Attribution type: \(attribution.attributionType)") // "ATTRIBUTED"
        print("Clicked link: \(attribution.clickedShortUrl ?? "N/A")")
        print("Destination: \(attribution.destinationUrl ?? "N/A")")

        // UTM parameters
        print("UTM Source: \(attribution.utmSource ?? "N/A")")
        print("UTM Medium: \(attribution.utmMedium ?? "N/A")")
        print("UTM Campaign: \(attribution.utmCampaign ?? "N/A")")

    } else {
        // Organic install — no matching ChottuLink click found
        print("Attribution type: \(attribution.attributionType)") // "ORGANIC"
    }

} else {
    // SDK not initialized, or user has opted out
    print("Attribution data not available")
}

Return type: CLAttributionData?

CLAttributionData properties
PropertyTypeDescription
attributionTypeString"ORGANIC" or "ATTRIBUTED"
isAttributedBooltrue when attributionType == "ATTRIBUTED"
matchFoundBoolWhether a matching click was found
installIdString?Server-assigned install ID
shortUrlString?Canonical short URL clicked
clickedShortUrlString?Raw clicked URL with query params intact
destinationUrlString?Final destination URL
destinationWithUtmString?Destination URL with UTM params appended
utmSourceString?UTM source
utmMediumString?UTM medium
utmCampaignString?UTM campaign
utmTermString?UTM term
utmContentString?UTM content

identify()​

Links the anonymous device to a known user in your system. Call this after a user logs in or signs up. The customer ID is persisted locally and included in all subsequent tracked events, enabling you to connect attribution and event data to real users in your analytics.

note

The id field is required and must be non-empty. Calls with an empty or blank id are silently ignored.

import ChottuLinkSDK

// Minimal — only the user ID is required
ChottuLink.identify(CLCustomerMeta(id: "user_123"))

// Full — with all optional fields
ChottuLink.identify(CLCustomerMeta(
    id: "user_123",
    name: "Jane Doe",
    email: "jane@example.com",
    phone: "+14155550100",
    emailSha256: "b4c9a...",   // Optionally share SHA-256 hash of the email instead of raw email
    phoneSha256: "e3d8f..."    // Optionally share SHA-256 hash of the phone instead of raw phone
))
CLCustomerMeta parameters
ParameterTypeRequiredDescription
idString✅ YesYour system's unique identifier for this user.
nameString?NoUser's display name.
emailString?NoUser's email address.
phoneString?NoUser's phone number.
emailSha256String?NoOptionally share SHA-256 hash of the email instead of raw email
phoneSha256String?NoOptionally share SHA-256 hash of the phone instead of raw phone.

trackLead()​

Tracks a lead or registration event. Use this when a user signs up, starts a trial, or completes any top-of-funnel action.

import ChottuLinkSDK

// Minimal — records a default "signup" event
ChottuLink.trackLead(nil)

// With a custom event name
ChottuLink.trackLead(CLLeadMeta(eventName: "trial_started"))

// With a custom event name and metadata
ChottuLink.trackLead(CLLeadMeta(
    eventName: "trial_started",
    metadata: [
        "plan": "pro",
        "referral_code": "FRIEND25"
    ]
))
CLLeadMeta parameters
ParameterTypeRequiredDescription
eventNameString?NoName of the event. Defaults to "signup" when nil.
metadata[String: Any]?NoArbitrary key-value data attached to the event.

trackConversion()​

Tracks a revenue or conversion event. Use this for purchases, subscription upgrades, in-app purchases, or any bottom-of-funnel action that has a monetary value. Events are deduplicated on the server using transactionId.

Revenue must be greater than zero

Calls with revenue <= 0 are silently ignored. Always pass a positive value.

import ChottuLinkSDK

// Minimal — revenue is the only required field
ChottuLink.trackConversion(CLConversionMeta(revenue: 29.99))

// Full — with all optional fields
ChottuLink.trackConversion(CLConversionMeta(
    revenue: 29.99,
    currency: "USD",              // ISO 4217 currency code
    eventName: "subscription",   // defaults to "purchase" when nil
    productId: "pro_monthly",
    transactionId: "txn_abc123", // strongly recommended for server-side deduplication
    metadata: [
        "trial_converted": true,
        "promo_code": "SUMMER25"
    ]
))
CLConversionMeta parameters
ParameterTypeRequiredDescription
revenueDouble✅ YesRevenue amount. Must be greater than 0.
currencyString?NoISO 4217 currency code (e.g. "USD", "EUR"). Defaults to your organisation's base currency when nil.
eventNameString?NoName of the event. Defaults to "purchase" when nil.
productIdString?NoThe product or SKU identifier associated with this conversion.
transactionIdString?NoA unique transaction ID used for server-side deduplication. Strongly recommended for purchase events.
metadata[String: Any]?NoArbitrary key-value data attached to the event.

trackEvent()​

Tracks any custom business event. Use this for anything that doesn't fit trackLead or trackConversion — tutorial steps, feature usage, content views, social shares, and so on.

import ChottuLinkSDK

// Simple — no extra data
ChottuLink.trackEvent(name: "tutorial_completed", data: nil)

// With metadata
ChottuLink.trackEvent(
    name: "feature_used",
    data: [
        "feature": "qr_code_scanner",
        "duration_seconds": 45,
        "success": true
    ]
)
Parameters
ParameterTypeRequiredDescription
nameString✅ YesThe event name (e.g. "tutorial_completed", "item_viewed").
data[String: Any]?NoArbitrary key-value metadata. Values should be String, Int, Double, or Bool.

logout()​

Call this when the user logs out of your app. The anonymous device ID is preserved — only the customer linkage is removed.

import ChottuLinkSDK

ChottuLink.logout()

After logout():

  • All pending events are uploaded immediately
  • The customer ID is cleared from local storage
  • Subsequent identify() calls will establish a new customer linkage
  • The anonymous device ID remains unchanged

optOut()​

Opts the user in or out of all SDK tracking. When opted out, all tracking methods (identify, trackLead, trackConversion, trackEvent) become no-ops and getAttributionData() returns nil. The preference is persisted across app launches.

All tracking stops immediately when opted out

When optOut(true) is active, no events are queued or sent and attribution data is not surfaced. Events are not buffered for later delivery — they are dropped. Call optOut(false) to re-enable tracking.

import ChottuLinkSDK

// Opt the user OUT of all tracking
ChottuLink.optOut(true)

// Opt the user back IN
ChottuLink.optOut(false)

// Read the current opt-out state
if ChottuLink.isOptedOut {
    print("User has opted out of tracking")
}
Parameters
ParameterTypeDescription
enabledBooltrue to opt out (disable all tracking). false to opt back in (re-enable tracking).