Skip to main content

Module 8 — Attribution & source

This is the part you don't write. When a deep link carrying a campaign key arrives, the SDK attaches attribution to every analytics event for that session, so you can reconstruct the user's journey from the deep link onward.

Automatic attribution​

PropertyMeaning
campaign_keyThe campaign key of the link that opened the session.
deeplink_keyThe same value, under the conventional deeplink_key name.
jidJourney ID, for cross-event attribution.
journey_sourceHow the journey started (e.g. deeplink).
campaign_sourceThe canonical traffic source (see below).

Session-scoped by design. These are attached only to events in the session the link opened. If the app is killed and later opened organically (no deep link), they are not carried over — organic sessions stay clean. Controlled by autoRegisterCampaignKeys (default true).

No register(...) calls are needed on your side. Disable it with deepLinkConfig.autoRegisterCampaignKeys = false to manage it manually.

Canonical traffic source — campaign_source​

The SDK normalizes the messy real-world source signal into exactly one of seven canonical tokens, identical on iOS, Android, and in the dashboard:

instagram   facebook   twitter   tiktok   qr   direct   unknown
  • twitter covers X (x, x.com, t.co → twitter).
  • direct — no source signal at all (organic, SMS, email, browser).
  • unknown — a signal was present but unrecognized.

How it's derived (priority order)​

1. utm_source / ?source     (rawSource)     ← most reliable
2. ?referrer                (URL param)
3. platform hint            (sourceApplication, when present)
→ a signal exists but isn't recognized  → unknown
→ no signal at all                      → direct

The SDK classifies defensively: even a raw ?source=ig or ?source=l.instagram.com becomes instagram. You don't have to send canonical values — but a campaign that does keeps the data cleanest.

Reading it directly​

If you need the token in code (e.g. to branch UI):

let token = PaylisherDeeplinkSource.canonical(rawSource: deepLink.source,
                                              referrer: deepLink.parameters["referrer"],
                                              platformHint: nil)   // "instagram"

Events the SDK emits​

With captureDeepLinkEvents = true (default), handling a link emits Deep Link Opened, carrying (when present): destination, scheme, full_url, campaign_key, campaign_id, source, campaign_source, jid, auth_required, and the parsed parameters. Auth-gated and deferred flows add Deep Link Completed / Cancelled / Timeout and the deferred-match events.

To verify: open a campaign link, then fire any of your own events and confirm they carry campaign_key / deeplink_key / jid for that session.

Next: Module 9 — Creating links →