API Reference

Public methods, attribution adapters, and models exposed by the GrowSurf iOS SDK.

Using AI? Follow Build with AI.

Use this page to look up individual GrowSurf iOS SDK methods. All SDK methods use Swift concurrency unless otherwise noted.

Use the Mobile SDK public key in your app. Do not embed your secret REST API key in an iOS app.

SDK LIFECYCLE ↓

Configure

Call this once before using GrowSurf. It connects the SDK to your GrowSurf program and Mobile SDK public key.

let growsurf = GrowSurf.configure(
    campaignId: "abc123",
    publicKey: "pk_mobile"
)

Parameter	Data Type	Description
campaignId	String	(Required) Your GrowSurf program ID.
publicKey	String	(Required) Your Mobile SDK public key.
baseURL	URL	(Optional) Custom Mobile SDK API base URL. Defaults to https://api.growsurf.com/mobile/v2.

Returns a configured GrowSurf instance.

Example use

import GrowSurfSDK

let growsurf = GrowSurf.configure(
    campaignId: "p9josq",
    publicKey: "pk_mobile"
)

Optionally, for advanced apps, initialize directly with explicit stores or a custom transport. Pass the production stores shown below, or your own conformances to the public store protocols:

let growsurf = GrowSurf(
    configuration: GrowSurfConfiguration(
        campaignId: "abc123",
        publicKey: "pk_mobile"
    ),
    tokenStore: GrowSurfKeychainTokenStore(),
    attributionStore: GrowSurfUserDefaultsAttributionStore(),
    mobileInstanceIdStore: GrowSurfUserDefaultsMobileInstanceIdStore()
)

---

Set participant token

Use this after your backend creates a mobile participant token for a signed-in user. It lets participant-scoped SDK calls load or update that participant's data.

try await growsurf.setParticipantToken(participantToken)

Parameter	Data Type	Description
token	String	(Required) A mobile participant token returned by your backend or by a participant creation method.

Returns Void.

Example use

try await growsurf.setParticipantToken(participantToken)

---

Get participant token

Returns the participant token currently held by the SDK, or nil if none is stored. Useful right after the GrowSurf window's ParticipantFields signup flow so your app can persist the freshly minted token for the user's next session.

try await growsurf.participantToken()

Returns String?.

Example use

if let token = try await growsurf.participantToken() {
    // Persist the token to your backend so the user stays signed in to GrowSurf.
}

---

Get current participant ID

Returns the current participant's ID decoded from the stored participant token, or nil if no participant token is set.

let participantId = try await growsurf.currentParticipantId()

Returns String?.

Example use

if let participantId = try await growsurf.currentParticipantId() {
    print("Current participant:", participantId)
}

---

Get mobile instance ID

Returns the app-install ID the SDK sends with participant creation for mobile anti-fraud. You usually only need this if your backend creates mobile participant tokens and needs to pass the same ID to GrowSurf.

try await growsurf.mobileInstanceId()

Returns a lowercase UUID String.

Example use

let mobileInstanceId = try await growsurf.mobileInstanceId()

---

Shutdown

Call this when a user signs out or you need to reset GrowSurf state on the device. It clears the stored session token, participant token, and pending attribution.

try await growsurf.shutdown()

Returns Void.

Example use

try await growsurf.shutdown()

---

CAMPAIGNS ↓

Get campaign

Use this to read the details and rewards of the configured GrowSurf program. The SDK creates or uses a session token before calling GrowSurf.

try await growsurf.getCampaign()

Returns GrowSurfCampaign.

Example use

let campaign = try await growsurf.getCampaign()
print(campaign.id)
print(campaign.rewards)

---

Get leaderboard

Use this to show leaderboard rows in a custom referral screen. You can page through results with page or cursor parameters.

try await growsurf.getLeaderboard(
    limit: 20,
    page: 1,
    offsetKey: nil,
    leaderboardType: nil
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of rows to return.
page	Int?	(Optional) Page number.
offsetKey	String?	(Optional) Cursor key for offset-based pagination.
leaderboardType	String?	(Optional) Leaderboard type filter.

Returns GrowSurfLeaderboardResponse.

Example use

let leaderboard = try await growsurf.getLeaderboard(limit: 10)
for row in leaderboard.participants {
    print(row.rank as Any, row.email as Any)
}

---

GROWSURF WINDOW ↓

Present GrowSurf window

Call this from your own button, menu item, or referral screen to open GrowSurf's native SwiftUI referral window.

The native GrowSurf window uses the GrowSurf window settings from your dashboard. This method is available on iOS.

For anonymous affiliate-program traffic, the window follows the configured enrollment mode. Open programs show direct signup with linked Terms when required. Reviewed programs show the configured hosted Apply action. A valid pending referral still shows customer signup and does not ask the referred customer to accept affiliate Terms.

Signed-in participants also see a traffic report when the Traffic section is turned on in Program Editor > 2. Design and your program is on a paid plan. The report shows visits and unique visitors to their link, visits over time, and where the visits came from. In the tabbed layout, a tab with more than one section shows one section at a time. Participants switch between them with the row of section titles at the top of the tab.

growsurf.presentGrowSurfWindow(
    from: viewController,
    identity: .existingParticipantToken(participantToken),
    theme: GrowSurfWindowTheme(),
    callbacks: GrowSurfWindowCallbacks()
)

Parameter	Data Type	Description
from	UIViewController	(Required) The view controller that presents the native window.
identity	GrowSurfWindowIdentity	(Optional) How the window should identify the current user. Defaults to .anonymous.
theme	GrowSurfWindowTheme	(Optional) Native presentation and theme overrides.
callbacks	GrowSurfWindowCallbacks	(Optional) Event callbacks for window open, close, participant creation (from the signup form), share tracking, invite sending, payout/settings actions, and errors.

Returns GrowSurfWindowController. Call close() on it to dismiss the window programmatically.

Example use

let windowController = growsurf.presentGrowSurfWindow(
    from: self,
    identity: .existingParticipantToken(participantToken),
    theme: GrowSurfWindowTheme(
        primaryColorHex: "#13795B",
        presentationStyle: .automatic
    ),
    callbacks: GrowSurfWindowCallbacks(
        onShareTracked: { type in
            print("Share tracked:", type)
        },
        onParticipantCreated: { participant, participantToken in
            print("Participant:", participant.id)
        },
        onError: { error in
            print("GrowSurf window error:", error)
        }
    )
)

---

Get GrowSurf window

Use this when you are building your own referral screen instead of showing the native GrowSurf window. It returns the program, participant, share, reward, leaderboard, and affiliate data used by the window.

try await growsurf.getGrowSurfWindow(identity: .anonymous)

Parameter	Data Type	Description
identity	GrowSurfWindowIdentity	(Optional) Window identity. Defaults to .anonymous.

Returns GrowSurfWindowResponse.

Example use

let window = try await growsurf.getGrowSurfWindow(
    identity: .existingParticipantToken(participantToken)
)

let shareUrl = window.participant?.shareUrl ?? window.share?.preferredUrl ?? window.share?.fallbackUrl

Use participant.shareUrl as the customer-facing referral link when a participant is available. Fall back to share.preferredUrl or share.fallbackUrl only for rendering.

---

Get participant resource download URL

Use this only when you build a custom Resources screen. It returns a short-lived authorized URL for one published file resource. The SDK derives the participant ID from its stored participant token. Link and text resources do not use this method.

let download = try await growsurf.getParticipantResourceDownloadURL(
    resourceId: resource.id
)

guard let url = URL(string: download.url) else { return }
UIApplication.shared.open(url)

Parameter	Data Type	Description
resourceId	String	(Required) Published FILE resource identifier.

Returns GrowSurfWindowResourceDownloadResponse with url and expiresIn. Request a new URL each time the participant opens the file. Do not save or share the returned URL.

---

ATTRIBUTION ↓

The deep link and provider handlers below each queue one visit with a stable ID and retry later if the device is offline.

Handle deep link

Call this when your app opens from a deep link. The SDK saves the referral code when present. It also records the link's UTM values and other visit details, even when the link has no referral code.

try await growsurf.handleDeepLink(url)

Parameter	Data Type	Description
url	URL	(Required) The deep link URL opened by your app.

Returns GrowSurfAttribution?. Returns nil when the URL has no referral code, UTM value, or click ID.

Example use

if let url {
    let attribution = try await growsurf.handleDeepLink(url)
    print(attribution?.referredBy as Any)
}

---

Handle attribution parameters

Call this from an attribution provider callback, such as Branch, Adjust, AppsFlyer, or Singular. The SDK reads the referral code, UTM values, and other visit details directly or from recognized URL-like values.

try await growsurf.handleAttributionParameters(parameters, provider: "branch")

Parameter	Data Type	Description
parameters	[String: String]	(Required) Provider callback parameters. The SDK recognizes grsf, ref, referredBy, click metadata, and the nine supported UTM fields in direct or nested URL-like values.
provider	String?	(Optional) Attribution provider name, such as branch, adjust, appsflyer, or singular.

Returns GrowSurfAttribution?. Returns nil when the parameters contain no referral code, UTM value, or click ID.

Example use

let attribution = try await growsurf.handleAttributionParameters(
    [
        "grsf": "referrer_id",
        "click_id": "click_123",
        "unique": "true",
        "utm_source": "newsletter",
        "utm_campaign": "launch",
    ],
    provider: "branch"
)

The UTM allowlist is utm_id, utm_source, utm_medium, utm_campaign, utm_source_platform, utm_term, utm_content, utm_creative_format, and utm_marketing_tactic. Destination and referrer URLs keep only their origin and path. Query strings and fragments are not stored.

The SDK sends normalized visits automatically. The server returns signed first-visit and last-visit receipts, and the SDK attaches them to participant creation so the server can apply the program's attribution model. Do not call recordAttribution(_:) after either handler.

---

Record a custom attribution visit

Use this only when your app constructs a GrowSurfAttribution and GrowSurfVisitAttribution itself. Deep-link and provider handlers already record their normalized visits.

try await growsurf.recordAttribution(attribution)

Returns GrowSurfAttributionResponse. If a visit fails to send, the SDK keeps it and retries on a later SDK call. A transient PROCESSING response also stays queued.

---

Get pending attribution

Use this to inspect referral attribution saved on this device before creating or signing in a participant.

try await growsurf.pendingAttribution()

Returns GrowSurfAttribution?.

Example use

if let attribution = try await growsurf.pendingAttribution() {
    print("Pending referrer:", attribution.referredBy as Any)
}

---

Clear pending attribution

Clear the saved referral code, queued visits, and signed receipts when attribution should no longer apply, such as when a different user signs in.

try await growsurf.clearPendingAttribution()

Returns Void.

Example use

try await growsurf.clearPendingAttribution()

---

Validate referrer

Use this to check whether a saved or supplied referrer is valid before you show a referred state or create a participant.

try await growsurf.validateReferrer(attribution)

Parameter	Data Type	Description
attribution	GrowSurfAttribution?	(Optional) Attribution to validate. If omitted, the SDK validates locally stored pending attribution.

Returns GrowSurfValidateReferrerResponse.

Example use

Pending attribution

let validation = try await growsurf.validateReferrer()

if validation.valid {
    print("Valid referrer:", validation.referredBy as Any)
}

Explicit referrer

let validation = try await growsurf.validateReferrer(referredBy: "referrer_id")

if validation.valid {
    print("Valid referrer")
}

---

PARTICIPANTS ↓

Add referred participant

Use this for referred signups. The SDK sends signed visit receipts so GrowSurf can apply the program’s first-click or last-click setting, even when a later referral code is invalid. Without a usable receipt, GrowSurf uses a validated explicit or saved referrer. For a newly added participant, the result’s referredBy identifies the referrer the server credited. validReferral can be true even when referredBy is absent. Existing-participant responses do not disclose that participant’s stored referral credit. A new participant is not added unless GrowSurf verifies a referral.

try await growsurf.addReferredParticipant(input)

Parameter	Data Type	Description
input	GrowSurfParticipantInput	(Required) Participant fields, optional explicit referredBy, optional attribution, and optional metadata.

Returns GrowSurfAddReferredParticipantResponse.

Example use

let result = try await growsurf.addReferredParticipant(
    GrowSurfParticipantInput(
        email: "[e-mail]",
        firstName: "Gavin",
        lastName: "Belson",
        metadata: ["plan": "pro"]
    )
)

if result.added {
    print("Referred participant:", result.participant?.id as Any)
} else {
    print("Not added:", result.notAddedReason as Any)
}

added is true for a new referred customer even when an affiliate program returns no participant token. If no participant is added, notAddedReason will be no_referrer, invalid_referrer, or participant_already_exists.

---

Add participant

Use this for public signup flows where the SDK can create a participant even without a referral. It sends pending attribution when available, stores the returned participant token when present, and includes the SDK-generated mobile instance ID.

try await growsurf.addParticipant(input)

Parameter	Data Type	Description
input	GrowSurfParticipantInput	(Required) Participant fields, optional attribution, and optional metadata.

Returns GrowSurfCreateParticipantResponse.

Example use

let response = try await growsurf.addParticipant(
    GrowSurfParticipantInput(
        email: "[e-mail]",
        firstName: "Gavin",
        lastName: "Belson",
        metadata: ["plan": "pro"]
    )
)

if let participant = response.participant {
    print("Created participant:", participant.id)
}

If the email already belongs to an existing participant, GrowSurf returns requiresParticipantToken: true and does not return a participant token. For signed-in or existing users, use an SDK-issued participant token you already have, or create a mobile participant token from your backend, then pass it to setParticipantToken(_:) or .existingParticipantToken(...).

---

Get participant

Use this after you have a participant token to load the participant's referral data, including their referral link and counts.

try await growsurf.getParticipant()

Returns GrowSurfParticipant.

Example use

let participant = try await growsurf.getParticipant()
print(participant.shareUrl as Any)

---

Update participant

Use this when your app lets a participant update profile fields, such as first name, last name, or metadata.

try await growsurf.updateParticipant(with: input)

Parameter	Data Type	Description
with	GrowSurfParticipantUpdateInput	(Required) Fields to update, such as firstName, lastName, and metadata.

Returns GrowSurfParticipant.

Example use

let participant = try await growsurf.updateParticipant(
    with: GrowSurfParticipantUpdateInput(
        firstName: "Gavin",
        lastName: "Belson",
        metadata: ["plan": "enterprise"]
    )
)

---

Update vanity links

Use this when your app lets a participant manage multiple custom referral link keys at once.

try await growsurf.updateVanityLinks(vanityKeys: ["ada", "ada-pro"])

Parameter	Data Type	Description
vanityKeys	[String]	(Required) Vanity keys to associate with the participant.

Returns GrowSurfParticipant.

Example use

let participant = try await growsurf.updateVanityLinks(
    vanityKeys: ["ada", "ada-pro"]
)

---

REFERRALS AND INVITES ↓

Get participant referrals

Use this to show who a participant has referred and the status of each referral.

The API masks email addresses by default. When the program allows invited email addresses after sign-in, the authenticated sender can see the original address they invited, including after signup or a triggered referral. Invitations without recorded disclosure permission remain masked. Other referrals stay masked. Private invitations and fully masked email settings block disclosure. The SDK uses the participant token already provided by your backend; no extra sign-in prompt is needed.

try await growsurf.getParticipantReferrals(
    limit: 20,
    offset: 0,
    sortBy: "createdAt",
    desc: true
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of referrals to return.
offset	Int?	(Optional) Offset for pagination.
sortBy	String?	(Optional) Field to sort by.
desc	Bool?	(Optional) true for descending sort order.

Returns GrowSurfReferralsResponse.

Example use

let response = try await growsurf.getParticipantReferrals(
    limit: 20,
    offset: 0,
    sortBy: "createdAt",
    desc: true
)

for referral in response.referrals {
    print(referral.email as Any, referral.referralStatus as Any)
}

---

Send invites

Use this to send referral invite emails from a participant's referral screen.

try await growsurf.sendInvites(
    emailAddresses: ["[e-mail]"],
    messageText: "Join me on GrowSurf",
    subjectText: "You're invited"
)

Parameter	Data Type	Description
emailAddresses	[String]	(Required) Email addresses to invite.
messageText	String	(Required) Invite message body.
subjectText	String?	(Optional) Invite email subject.

Returns GrowSurfInviteResponse.

When Follow-Up Reminder is enabled, GrowSurf automatically emails the referrer about new invitations whose contacts have not signed up. The delay is configurable from 2–30 days, default 3. Each contact is included once. There is no participant checkbox or request parameter. Invitations created before the email was enabled do not qualify. The reminder never sends an invitation to those contacts, and a signup awaiting a purchase is already complete.

Example use

let response = try await growsurf.sendInvites(
    emailAddresses: ["[e-mail]"],
    messageText: "Try this app with my referral link.",
    subjectText: "Join me"
)

---

Track share

Call this after a participant shares their referral link from your UI. GrowSurf records the share type, such as copyRefLink, email, sms, or a social channel.

try await growsurf.trackShare(type: "copyRefLink")

Parameter	Data Type	Description
type	String	(Required) Share type, such as copyRefLink, email, sms, or a social channel type returned by the GrowSurf window response.

Returns GrowSurfSuccessResponse.

Example use

try await growsurf.trackShare(type: "copyRefLink")

---

REFERRAL PROGRAMS ↓

Trigger referral

Referral programs only

Use this when a referred participant completes the in-app action that should count as a referral conversion.

try await growsurf.triggerReferral()

Returns GrowSurfSuccessResponse.

Example use

let response = try await growsurf.triggerReferral()

For server-verified purchases, subscriptions, or other high-trust reward events, trigger referral credit from your backend using the REST API or a GrowSurf integration instead of from the app.

---

Get participant rewards

Referral programs only

Use this to show the rewards a participant has earned or can track inside your app.

try await growsurf.getParticipantRewards(
    limit: 20,
    nextId: nil
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of rewards to return.
nextId	String?	(Optional) Cursor ID for the next page.

Returns GrowSurfRewardsResponse.

Example use

let rewards = try await growsurf.getParticipantRewards(
    limit: 20
)

---

Mark participant rewards read

Referral programs only

Call this after showing reward notifications so GrowSurf can clear the participant's unread reward state.

try await growsurf.markParticipantRewardsRead()

Returns GrowSurfSuccessResponse.

Example use

try await growsurf.markParticipantRewardsRead()

---

Get participant referral summary

Referral programs only

Use this for referral programs to show a participant's high-level referral stats (referrals, leads, expired referrals, clicks, rewards earned, pending rewards, invites sent).

try await growsurf.getParticipantReferralSummary()

Returns GrowSurfReferralSummary.

Example use

let summary = try await growsurf.getParticipantReferralSummary()
print(summary.referrals as Any)

---

AFFILIATE PROGRAMS ↓

Get participant commissions

Affiliate programs only

Use this for affiliate programs to show a participant's commission history.

try await growsurf.getParticipantCommissions(
    limit: 20,
    nextId: nil
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of commissions to return.
nextId	String?	(Optional) Cursor ID for the next page.

Returns GrowSurfCommissionsResponse.

Example use

let commissions = try await growsurf.getParticipantCommissions(
    limit: 20
)

---

Mark participant commissions read

Affiliate programs only

Call this after showing commission notifications so GrowSurf can clear the participant's unread commission state.

try await growsurf.markParticipantCommissionsRead()

Returns GrowSurfSuccessResponse.

Example use

try await growsurf.markParticipantCommissionsRead()

---

Get participant payouts

Affiliate programs only

Use this for affiliate programs to show a participant's payout history.

try await growsurf.getParticipantPayouts(
    limit: 20,
    nextId: nil
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of payouts to return.
nextId	String?	(Optional) Cursor ID for the next page.

Returns GrowSurfPayoutsResponse.

Example use

let payouts = try await growsurf.getParticipantPayouts(
    limit: 20
)

---

Mark participant payouts read

Affiliate programs only

Call this after showing payout notifications so GrowSurf can clear the participant's unread payout state.

try await growsurf.markParticipantPayoutsRead()

Returns GrowSurfSuccessResponse.

Example use

try await growsurf.markParticipantPayoutsRead()

---

Get participant affiliate summary

Affiliate programs only

Use this for affiliate programs to show a participant's high-level affiliate stats, such as referral revenue, total paid out, and upcoming payout.

try await growsurf.getParticipantAffiliateSummary()

Returns GrowSurfAffiliateSummary.

Example use

let summary = try await growsurf.getParticipantAffiliateSummary()
print(summary.upcomingPayout as Any)

---

Request PayPal confirm email

Use this when your program collects a PayPal email address from participants before payouts can continue. It sends the participant a confirmation email with a one-time link to a hosted page where they confirm the email address their payouts go to.

try await growsurf.requestPaypalConfirmEmail()

Returns GrowSurfSuccessResponse.

Example use

let response = try await growsurf.requestPaypalConfirmEmail()

---

Request payout destination confirmation

Use this when the participant needs to confirm where they get paid. It sends them a one-time confirmation link for the payout provider you pass, so it works on a program that offers more than one payout method. Only the participant can open the link and confirm. The native GrowSurf window calls this automatically from its payout settings; call it yourself only if you build a custom settings UI.

try await growsurf.requestPayoutDestinationConfirmation(provider: "PAYPAL")

Parameter	Data Type	Description
provider	String	(Required) The payout provider to confirm: PAYPAL, VENMO, or WISECOM for Wise. The provider must be enabled on your program.

Returns GrowSurfPayoutDestinationConfirmationResponse with success, status, provider, providerDisplayName, and expiresAt.

Example use

let response = try await growsurf.requestPayoutDestinationConfirmation(
    provider: "PAYPAL"
)

Read the enabled providers from payoutSettings.payoutDestinations.enabledProviders on the window response, and check canConfirm on that provider before offering the action. Venmo payouts require a confirmed email address and a recipient in the United States. Wise is available on affiliate programs only.

---

Request tax info session

Use this when the program requires tax documentation and the participant needs to complete or resubmit their W-9 / W-8 form before rewards or payouts can continue. It starts a secure hosted tax-form session and returns the hosted URL to open in an in-app browser, plus the participant's new tax status. The native GrowSurf window calls this automatically from its Tax Forms settings row; call it yourself only if you build a custom settings UI.

try await growsurf.requestTaxInfoSession(residencyCountryCode: "US")

Parameter	Data Type	Description
residencyCountryCode	String?	(Optional) ISO 3166-1 alpha-2 tax-residency hint.

Returns GrowSurfTaxSessionResponse.

Example use

let session = try await growsurf.requestTaxInfoSession(residencyCountryCode: "US")
if let urlString = session.hostedUrl, let url = URL(string: urlString) {
    await UIApplication.shared.open(url)
}

GrowSurf never stores participant tax IDs. The W-9 / W-8 is completed on a hosted page served by GrowSurf's IRS-authorized e-file partner.

---

Get tax info status

Use this to read the participant's current sanitized tax status without asking the tax provider to refresh it.

try await growsurf.getTaxInfoStatus()

Returns GrowSurfTaxInfo.

Example use

let taxInfo = try await growsurf.getTaxInfoStatus()
print(taxInfo.status as Any)

---

Refresh tax info status

Call this after the participant returns from the hosted W-9 / W-8 flow. It asks GrowSurf to reconcile the provider-backed status and refreshes the native window cache.

let taxInfo = try await growsurf.refreshTaxInfoStatus()

Returns GrowSurfTaxInfo.

---

Save tax residency

Save the participant's ISO 3166-1 alpha-2 country of tax residence before starting the hosted tax flow.

let response = try await growsurf.saveTaxResidency("GB")

Parameter	Data Type	Description
residencyCountryCode	String	(Required) ISO 3166-1 alpha-2 country code.

Returns GrowSurfTaxInfoSaveResponse.

---

Save VAT number

Save or clear the participant's affiliate VAT number. Pass an empty string to clear the saved value.

let response = try await growsurf.saveTaxVat(number: "GB123456789")

Parameter	Data Type	Description
number	String	(Required) VAT number, or an empty string to clear it.

Returns GrowSurfTaxInfoSaveResponse.

---

ATTRIBUTION ADAPTERS ↓

Branch attribution adapter

Use this helper when Branch returns attribution data. It normalizes Branch payloads and can store the resulting GrowSurf attribution on the SDK.

GrowSurfBranchAttribution.normalize(parameters)
try await GrowSurfBranchAttribution.handle(parameters, sdk: growsurf)

Method	Description
normalize(_ parameters: [String: String])	Parses a string dictionary and returns GrowSurfAttribution? without storing it.
normalize(_ parameters: [String: Any])	Converts a mixed dictionary, then parses attribution without storing it.
normalize(_ parameters: [AnyHashable: Any])	Converts a hashable-key dictionary, then parses attribution without storing it.
handle(_ parameters: [String: String], sdk:)	Parses and stores attribution on the provided SDK instance.
handle(_ parameters: [String: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.
handle(_ parameters: [AnyHashable: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.

Example use

import GrowSurfBranchAttribution

try await GrowSurfBranchAttribution.handle(
    branchParams,
    sdk: growsurf
)

---

Adjust attribution adapter

Use this helper when Adjust returns a deep link. It normalizes the URL and can store the resulting GrowSurf attribution on the SDK.

GrowSurfAdjustAttribution.normalize(url)
try await GrowSurfAdjustAttribution.handle(url, sdk: growsurf)

Method	Description
normalize(_ url: URL)	Parses a URL and returns GrowSurfAttribution? without storing it.
normalize(_ urlString: String)	Parses a URL string or encoded URL string without storing it.
handle(_ url: URL, sdk:)	Parses and stores attribution on the provided SDK instance.
handle(_ urlString: String, sdk:)	Parses and stores attribution on the provided SDK instance.

Example use

import GrowSurfAdjustAttribution

try await GrowSurfAdjustAttribution.handle(
    adjustDeeplinkURL,
    sdk: growsurf
)

---

AppsFlyer attribution adapter

Use this helper when AppsFlyer returns conversion or deep link data. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK.

GrowSurfAppsFlyerAttribution.normalize(parameters)
try await GrowSurfAppsFlyerAttribution.handle(parameters, sdk: growsurf)

Method	Description
normalize(_ parameters: [String: String])	Parses a string dictionary and returns GrowSurfAttribution? without storing it.
normalize(_ parameters: [String: Any])	Converts a mixed dictionary, then parses attribution without storing it.
normalize(_ parameters: [AnyHashable: Any])	Converts a hashable-key dictionary, then parses attribution without storing it.
handle(_ parameters: [String: String], sdk:)	Parses and stores attribution on the provided SDK instance.
handle(_ parameters: [String: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.
handle(_ parameters: [AnyHashable: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.

Example use

import GrowSurfAppsFlyerAttribution

try await GrowSurfAppsFlyerAttribution.handle(
    conversionData,
    sdk: growsurf
)

---

Singular attribution adapter

Use this helper when Singular returns callback parameters or deep link values. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK.

GrowSurfSingularAttribution.normalize(parameters)
try await GrowSurfSingularAttribution.handle(parameters, sdk: growsurf)

Method	Description
normalize(_ parameters: [String: String])	Parses a string dictionary and returns GrowSurfAttribution? without storing it.
normalize(_ parameters: [String: Any])	Converts a mixed dictionary, then parses attribution without storing it.
normalize(_ parameters: [AnyHashable: Any])	Converts a hashable-key dictionary, then parses attribution without storing it.
normalize(_ url: URL)	Parses a URL without storing it.
normalize(_ urlString: String)	Parses a URL string or encoded URL string without storing it.
handle(_ parameters: [String: String], sdk:)	Parses and stores attribution on the provided SDK instance.
handle(_ parameters: [String: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.
handle(_ parameters: [AnyHashable: Any], sdk:)	Converts, parses, and stores attribution on the provided SDK instance.
handle(_ url: URL, sdk:)	Parses and stores attribution on the provided SDK instance.
handle(_ urlString: String, sdk:)	Parses and stores attribution on the provided SDK instance.

Example use

import GrowSurfSingularAttribution

try await GrowSurfSingularAttribution.handle(
    singularPayload,
    sdk: growsurf
)

---

UTILITIES ↓

Normalize attribution parameters

Use this when you need to read GrowSurf attribution from raw provider parameters without storing it. It looks for grsf, ref, or referredBy directly and inside URL-like values.

GrowSurfAttributionNormalizer.normalize(
    parameters: parameters,
    provider: "branch"
)

Parameter	Data Type	Description
parameters	[String: String]	(Required) Raw parameters. The normalizer checks direct fields and URL-like nested values.
provider	String?	(Optional) Provider name to attach to the attribution result.

Returns GrowSurfAttribution?.

Example use

let attribution = GrowSurfAttributionNormalizer.normalize(
    parameters: [
        "deep_link_value": "https://piedpiper.com/signup?grsf=referrer_id",
        "click_id": "click_123",
    ],
    provider: "appsflyer"
)

---

Normalize attribution URL

Use this when you need to parse a URL for grsf, ref, or referredBy without storing attribution on the SDK.

GrowSurfAttributionNormalizer.normalize(url: url, provider: "adjust")

Parameter	Data Type	Description
url	URL	(Required) URL to parse.
provider	String?	(Optional) Provider name to attach to the attribution result.

Returns GrowSurfAttribution?.

Example use

let attribution = GrowSurfAttributionNormalizer.normalize(
    url: URL(string: "https://piedpiper.com/signup?grsf=referrer_id")!,
    provider: "adjust"
)

---

Convert attribution parameters to strings

Use this before passing mixed provider callback payloads to the normalizer or SDK attribution methods. It converts nested values into a [String: String] dictionary without storing attribution.

GrowSurfAttributionNormalizer.stringParameters(from: parameters)

Parameter	Data Type	Description
parameters	[String: Any]	(Required) Provider callback payload. Nested dictionaries and arrays are flattened into string values.

Returns [String: String].

Example use

let stringParameters = GrowSurfAttributionNormalizer.stringParameters(
    from: providerPayload
)

try await growsurf.handleAttributionParameters(
    stringParameters,
    provider: "branch"
)