API Reference

Public methods, Java callback overloads, attribution adapters, and models exposed by the GrowSurf Android SDK.

If you're using an AI tool such as Cursor, ChatGPT Codex, or Claude Code to help you implement GrowSurf, we recommend utilizing our MCP server.

Use this page to look up individual GrowSurf Android SDK methods. Most SDK methods are Kotlin coroutine methods. Java examples are included where the SDK exposes callback overloads or synchronous/static methods.

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

SDK LIFECYCLE ↓

Configure

Call this once before using GrowSurf. It connects the SDK to your GrowSurf campaign, Mobile SDK public key, and Android context.

Kotlin

val growsurf = GrowSurfSdk.configure(
    context = context,
    campaignId = "abc123",
    publicKey = "pk_mobile",
)

Java

Parameter	Data Type	Description
context	Context	(Required) Android context used for encrypted token storage, attribution storage, mobile instance ID storage, and Play Install Referrer access.
campaignId	String	(Required) Your GrowSurf program ID.
publicKey	String	(Required) Your Mobile SDK public key.
baseUrl	String	(Optional in Kotlin) Custom Mobile SDK API base URL. Defaults to https://api.growsurf.com/mobile/v2.

Returns a configured GrowSurfSdk instance.

Optionally, for advanced apps, initialize directly with explicit stores, transport, dispatcher, or install referrer client. Pass the production stores shown below (or your own conformances to the public store interfaces):

val growsurf = GrowSurfSdk(
    configuration = GrowSurfConfiguration(
        campaignId = "abc123",
        publicKey = "pk_mobile",
    ),
    tokenStore = EncryptedPreferencesGrowSurfTokenStore(context),
    attributionStore = PreferencesGrowSurfAttributionStore(context),
)

---

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.

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 Unit.

Example use

growsurf.setParticipantToken(participantToken)

Use this method with tokens created by the REST API mobile participant token endpoint after a user is already signed in.

---

Get participant token

Returns the participant token currently held by the SDK, or null 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.

growsurf.getParticipantToken()

Returns String?.

Example use

growsurf.getParticipantToken()?.let { token ->
    // Persist the token to your backend so the user stays signed in to GrowSurf.
}

The default EncryptedPreferencesGrowSurfTokenStore can propagate KeyStore or EncryptedSharedPreferences errors. Wrap this call in try/catch and rethrow CancellationException to preserve structured concurrency.

---

Get current participant ID

Returns the current participant's ID from the stored participant token, or null if none.

Kotlin coroutine

val participantId = growsurf.getCurrentParticipantId()

Java callback

Returns String?.

Example use

growsurf.getCurrentParticipantId()?.let { participantId ->
    Log.d("GrowSurf", "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.

getMobileInstanceId() is a suspend function, so call it from a coroutine.

growsurf.getMobileInstanceId()

Returns a UUID String.

Example use

lifecycleScope.launch {
    val mobileInstanceId = growsurf.getMobileInstanceId()
}

Participant creation methods send mobileInstanceId automatically. Read it manually only when your backend creates a mobile participant token and needs to pass mobileInstanceId to the REST API.

---

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.

growsurf.shutdown()

Returns Unit.

Example use

growsurf.shutdown()

---

CAMPAIGNS ↓

Get campaign

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

growsurf.getCampaign()

Returns GrowSurfCampaign.

Example use

val campaign = growsurf.getCampaign()
Log.d("GrowSurf", campaign.id)

---

Get leaderboard

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

growsurf.getLeaderboard(
    limit = 20,
    page = 1,
    offsetKey = null,
    leaderboardType = null,
)

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

val leaderboard = growsurf.getLeaderboard(limit = 10)
leaderboard.participants.forEach { row ->
    Log.d("GrowSurf", "Rank ${row.rank}: ${row.email}")
}

---

GROWSURF WINDOW ↓

Present GrowSurf window

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

The native GrowSurf window uses the GrowSurf window settings from your dashboard. This method is not a coroutine method.

growsurf.presentGrowSurfWindow(
    activity = activity,
    identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken),
    theme = GrowSurfWindowTheme(),
    callbacks = GrowSurfWindowCallbacks(),
)

Parameter	Data Type	Description
activity	Activity	(Required) Activity that hosts 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

val controller = growsurf.presentGrowSurfWindow(
    activity = this,
    identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken),
    theme = GrowSurfWindowTheme(
        primaryColor = 0xFF13795B,
        presentationStyle = GrowSurfWindowPresentationStyle.AUTOMATIC,
    ),
    callbacks = GrowSurfWindowCallbacks(
        onShareTracked = { type ->
            Log.d("GrowSurf", "Share tracked: $type")
        },
        onParticipantCreated = { participant, participantToken ->
            Log.d("GrowSurf", "Participant: ${participant.id}")
        },
        onError = { error ->
            Log.e("GrowSurf", "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 campaign, participant, share, reward, leaderboard, and affiliate data used by the window.

growsurf.getGrowSurfWindow(identity = GrowSurfWindowIdentity.Anonymous)

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

Returns GrowSurfWindowResponse.

Example use

val window = growsurf.getGrowSurfWindow(
    identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken),
)

val 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.

---

ATTRIBUTION ↓

Handle deep link

Call this when your app opens from a referral deep link. If the URI contains grsf, ref, or referredBy, the SDK saves the attribution so you can apply it when the user signs up.

growsurf.handleDeepLink(uri)

Parameter	Data Type	Description
uri	Uri	(Required) The deep link URI opened by your app.

Returns GrowSurfAttribution?. Returns null when no GrowSurf referral value is found.

Example use

intent.data?.let { uri ->
    val attribution = growsurf.handleDeepLink(uri)
    Log.d("GrowSurf", "Referrer: ${attribution?.referredBy}")
}

---

Handle deferred deep link

Call this if you want to read Google Play Install Referrer before signup. addReferredParticipant(...) checks it automatically when no explicit or pending attribution exists.

growsurf.handleDeferredDeepLink(forceRefresh = false)

Parameter	Data Type	Description
forceRefresh	Boolean	(Optional) When true, queries Play Install Referrer again even if the SDK already checked it. Defaults to false.

Returns GrowSurfAttribution?. Returns null when no GrowSurf referral value is found.

Example use

val attribution = growsurf.handleDeferredDeepLink()

addReferredParticipant(...) checks Play Install Referrer automatically when no explicit or pending attribution exists. Call this manually only when you want to inspect attribution earlier.

---

Handle attribution parameters

Call this from an attribution provider callback, such as Branch, Adjust, AppsFlyer, or Singular. If the parameters include grsf, ref, or referredBy directly or inside URL-like values, the SDK saves the attribution for signup.

growsurf.handleAttributionParameters(parameters, provider = "branch")

Parameter	Data Type	Description
parameters	Map<String, String>	(Required) Provider callback parameters. The SDK recognizes direct values and nested URL-like values containing grsf, ref, or referredBy.
provider	String?	(Optional) Attribution provider name, such as branch, adjust, appsflyer, or singular.

Returns GrowSurfAttribution?. Returns null when no GrowSurf referral value is found.

Example use

val attribution = growsurf.handleAttributionParameters(
    mapOf(
        "grsf" to "referrer_id",
        "click_id" to "click_123",
        "unique" to "true",
    ),
    provider = "branch",
)

---

Get pending attribution

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

growsurf.getPendingAttribution()

Returns GrowSurfAttribution?.

Example use

val attribution = growsurf.getPendingAttribution()

---

Clear pending attribution

Clear saved referral attribution when it should no longer apply, such as after you handle it or when a different user signs in.

growsurf.clearPendingAttribution()

Returns Unit.

Example use

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.

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

val validation = growsurf.validateReferrer()

if (validation.valid) {
    Log.d("GrowSurf", "Valid referrer: ${validation.referredBy}")
}

Explicit referrer

---

PARTICIPANTS ↓

Add referred participant

Use this for referred signups. The SDK looks for saved attribution, an explicit referrer, or Play Install Referrer attribution, validates it, and only creates the participant when the referral is valid.

Kotlin coroutine

val result = growsurf.addReferredParticipant(
    GrowSurfParticipantInput(
        email = "[e-mail]",
        firstName = "Ada",
        lastName = "Lovelace",
        metadata = mapOf("plan" to "pro"),
    ),
)

if (result.added) {
    Log.d("GrowSurf", "Referred participant: ${result.participant?.id}")
}

Java callback

Parameter	Data Type	Description
input	GrowSurfParticipantInput	(Required) Participant fields, optional explicit referredBy, optional attribution, and optional metadata.
callback	GrowSurfCallback<GrowSurfAddReferredParticipantResponse>	(Optional) Java-friendly callback overload.

Returns GrowSurfAddReferredParticipantResponse.

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 for anti-fraud.

Kotlin coroutine

val response = growsurf.addParticipant(
    GrowSurfParticipantInput(
        email = "[e-mail]",
        firstName = "Ada",
        lastName = "Lovelace",
        metadata = mapOf("plan" to "pro"),
    ),
)

response.participant?.let { participant ->
    Log.d("GrowSurf", "Created participant: ${participant.id}")
}

Java callback

Parameter	Data Type	Description
input	GrowSurfParticipantInput	(Required) Participant fields, optional attribution, and optional metadata.
callback	GrowSurfCallback<GrowSurfCreateParticipantResponse>	(Optional) Java-friendly callback overload.

Returns GrowSurfCreateParticipantResponse.

Use this method for public signup flows where the SDK should create a new participant. 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 GrowSurfWindowIdentity.ExistingParticipantToken(...).

---

Get participant

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

growsurf.getParticipant()

Returns GrowSurfParticipant.

Example use

val participant = growsurf.getParticipant()
Log.d("GrowSurf", participant.shareUrl.orEmpty())

---

Update participant

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

growsurf.updateParticipant(input)

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

Returns GrowSurfParticipant.

Example use

val participant = growsurf.updateParticipant(
    GrowSurfParticipantUpdateInput(
        firstName = "Ada",
        lastName = "Lovelace",
        metadata = mapOf("plan" to "enterprise"),
    ),
)

---

Update vanity links

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

growsurf.updateVanityLinks(vanityKeys)

Parameter	Data Type	Description
vanityKeys	List<String>	(Required) Vanity keys to associate with the participant.

Returns GrowSurfParticipant.

Example use

val participant = growsurf.updateVanityLinks(
    vanityKeys = listOf("ada", "ada-pro"),
)

---

REFERRALS AND INVITES ↓

Get participant referrals

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

growsurf.getParticipantReferrals(
    limit = 20,
    offset = 0,
)

Parameter	Data Type	Description
limit	Int?	(Optional) Number of referrals to return.
offset	Int?	(Optional) Offset for pagination.

Returns GrowSurfReferralsResponse.

Example use

val response = growsurf.getParticipantReferrals(
    limit = 20,
)

response.referrals.forEach { referral ->
    Log.d("GrowSurf", "${referral.email}: ${referral.referralStatus}")
}

---

Send invites

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

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

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

Returns GrowSurfInviteResponse.

Example use

val response = growsurf.sendInvites(
    emailAddresses = listOf("[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 copy, email, sms, or a social channel.

growsurf.trackShare(type)

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

Returns GrowSurfSuccessResponse.

Example use

growsurf.trackShare(
    type = "copy",
)

---

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. For purchases or other high-trust events, trigger referral credit from your backend instead.

growsurf.triggerReferral()

Returns GrowSurfSuccessResponse.

Example use

val response = 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.

growsurf.getParticipantRewards(
    limit = 20,
    nextId = null,
)

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

val rewards = 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.

growsurf.markParticipantRewardsRead()

Returns GrowSurfSuccessResponse.

Example use

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).

growsurf.getParticipantReferralSummary()

Returns GrowSurfReferralSummary.

Example use

val summary = growsurf.getParticipantReferralSummary()
Log.d("GrowSurf", "Referrals: ${summary.referrals}")

---

AFFILIATE PROGRAMS ↓

Get participant commissions

Affiliate programs only

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

growsurf.getParticipantCommissions(
    limit = 20,
    nextId = null,
)

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

val commissions = 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.

growsurf.markParticipantCommissionsRead()

Returns GrowSurfSuccessResponse.

Example use

growsurf.markParticipantCommissionsRead()

---

Get participant payouts

Affiliate programs only

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

growsurf.getParticipantPayouts(
    limit = 20,
    nextId = null,
)

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

val payouts = 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.

growsurf.markParticipantPayoutsRead()

Returns GrowSurfSuccessResponse.

Example use

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.

growsurf.getParticipantAffiliateSummary()

Returns GrowSurfAffiliateSummary.

Example use

val summary = growsurf.getParticipantAffiliateSummary()
Log.d("GrowSurf", "Upcoming payout: ${summary.upcomingPayout}")

---

Request PayPal confirm email

Affiliate programs only

Use this when your affiliate program needs the participant to confirm their PayPal email before payouts can continue.

growsurf.requestPaypalConfirmEmail()

Returns GrowSurfSuccessResponse.

Example use

val response = growsurf.requestPaypalConfirmEmail()

---

Request tax info session

Use this when the campaign 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 a browser or Chrome Custom Tab) 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.

growsurf.requestTaxInfoSession()

Returns GrowSurfTaxSessionResponse.

Example use

val session = growsurf.requestTaxInfoSession()
session.hostedUrl?.let { url ->
    startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(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.

---

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)
GrowSurfBranchAttribution.handle(parameters, growsurf)

Method	Description
normalize(parameters: Map<String, *>)	Converts a mixed map, then parses attribution without storing it.
normalize(json: JSONObject)	Parses JSON attribution without storing it.
handle(parameters: Map<String, *>, sdk: GrowSurfSdk)	Converts, parses, and stores attribution on the provided SDK instance.
handle(json: JSONObject, sdk: GrowSurfSdk)	Parses and stores attribution on the provided SDK instance.

Example use

Kotlin

import com.growsurf.sdk.attribution.branch.GrowSurfBranchAttribution

val attribution = GrowSurfBranchAttribution.handle(branchParams, growsurf)

Java normalize

---

Adjust attribution adapter

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

GrowSurfAdjustAttribution.normalize(uri)
GrowSurfAdjustAttribution.handle(uri, growsurf)

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

Example use

Kotlin

import com.growsurf.sdk.attribution.adjust.GrowSurfAdjustAttribution

val attribution = GrowSurfAdjustAttribution.handle(adjustDeepLink, growsurf)

Java normalize

---

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)
GrowSurfAppsFlyerAttribution.handle(parameters, growsurf)

Method	Description
normalize(parameters: Map<String, *>)	Converts a mixed map, then parses attribution without storing it.
normalize(json: JSONObject)	Parses JSON attribution without storing it.
handle(parameters: Map<String, *>, sdk: GrowSurfSdk)	Converts, parses, and stores attribution on the provided SDK instance.
handle(json: JSONObject, sdk: GrowSurfSdk)	Parses and stores attribution on the provided SDK instance.

Example use

Kotlin

import com.growsurf.sdk.attribution.appsflyer.GrowSurfAppsFlyerAttribution

val attribution = GrowSurfAppsFlyerAttribution.handle(conversionData, growsurf)

Java normalize

---

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)
GrowSurfSingularAttribution.handle(parameters, growsurf)

Method	Description
normalize(parameters: Map<String, *>)	Converts a mixed map, then parses attribution without storing it.
normalize(json: JSONObject)	Parses JSON attribution without storing it.
normalize(uri: Uri)	Parses a URI without storing it.
normalize(url: String)	Parses a URL string or encoded URL string without storing it.
handle(parameters: Map<String, *>, sdk: GrowSurfSdk)	Converts, parses, and stores attribution on the provided SDK instance.
handle(json: JSONObject, sdk: GrowSurfSdk)	Parses and stores attribution on the provided SDK instance.
handle(uri: Uri, sdk: GrowSurfSdk)	Parses and stores attribution on the provided SDK instance.
handle(url: String, sdk: GrowSurfSdk)	Parses and stores attribution on the provided SDK instance.

Example use

Kotlin

import com.growsurf.sdk.attribution.singular.GrowSurfSingularAttribution

val attribution = GrowSurfSingularAttribution.handle(singularPayload, growsurf)

Java normalize

---

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.

Kotlin

val attribution = GrowSurfAttributionNormalizer.normalize(
    parameters = mapOf(
        "deep_link_value" to "https://example.com/signup?grsf=referrer_id",
        "click_id" to "click_123",
    ),
    provider = "appsflyer",
)

Java

Parameter	Data Type	Description
parameters	Map<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?.

---

Normalize attribution URI

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

GrowSurfAttributionNormalizer.normalize(uri, provider = "adjust")

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

Returns GrowSurfAttribution?.

Example use

val attribution = GrowSurfAttributionNormalizer.normalize(
    Uri.parse("https://example.com/signup?grsf=referrer_id"),
    provider = "adjust",
)

---

Normalize attribution JSON

Use this when a provider gives you a JSON payload and you need to find grsf, ref, or referredBy without storing attribution on the SDK.

GrowSurfAttributionNormalizer.normalize(json, provider = "branch")

Parameter	Data Type	Description
json	JSONObject	(Required) JSON provider payload.
provider	String?	(Optional) Provider name to attach to the attribution result.

Returns GrowSurfAttribution?.

Example use

val attribution = GrowSurfAttributionNormalizer.normalize(
    JSONObject().put("~referring_link", "https://example.com?grsf=referrer_id"),
    provider = "branch",
)

---

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 Map<String, String> without storing attribution.

GrowSurfAttributionNormalizer.stringParameters(parameters)

Parameter	Data Type	Description
parameters	Map<String, *> or JSONObject	(Required) Provider callback payload. Nested values are flattened into string values.

Returns Map<String, String>.

Example use

val stringParameters = GrowSurfAttributionNormalizer.stringParameters(providerPayload)

growsurf.handleAttributionParameters(
    stringParameters,
    provider = "branch",
)