Models and Errors

Models, callbacks, stores, interfaces, and errors exposed by the GrowSurf Android SDK.

Core models

GrowSurfConfiguration

Field	Type	Description
campaignId	String	GrowSurf program ID.
publicKey	String	Mobile SDK public key.
baseUrl	String	Mobile SDK API base URL.

GrowSurfAttribution

Field	Type	Description
referredBy	String?	Referrer participant ID or vanity key.
ref	String?	Referrer value mirrored for provider compatibility.
unique	Boolean?	Whether the attribution provider marked the click as unique.
provider	String?	Attribution provider name.
clickId	String?	Provider click ID.
visit	GrowSurfVisitAttribution?	Visit details the SDK recorded for this link.

GrowSurfVisitAttribution

Field	Type	Description
contractVersion	Int	Contract version. The current value is 1.
visitId	String	Stable random visit ID used for idempotent retries.
occurredAt	Long	Visit time as Unix milliseconds.
utm	GrowSurfAttributionUtm?	The nine allowlisted UTM values.
referrer	GrowSurfAttributionUrl?	Referrer origin and path only.
destination	GrowSurfAttributionUrl?	Destination origin and path only.
trigger	GrowSurfAttributionTrigger	QR_CODE, DEEP_LINK, DEFERRED_DEEP_LINK, INSTALL_REFERRER, or MANUAL.
provider	GrowSurfAttributionProvider?	BRANCH, APPSFLYER, ADJUST, SINGULAR, PLAY_INSTALL_REFERRER, or CUSTOM.
clickId	String?	Provider click ID when available.

GrowSurfAttributionUtm exposes id, source, medium, campaign, sourcePlatform, term, content, creativeFormat, and marketingTactic. GrowSurfAttributionUrl exposes origin and path. It never includes a query string or fragment.

GrowSurfParticipantInput

Field	Type	Description
email	String	Participant email address.
firstName	String?	Participant first name.
lastName	String?	Participant last name.
referredBy	String?	Explicit referrer value.
attribution	GrowSurfAttribution?	Explicit attribution payload.
metadata	Map<String, Any?>?	Custom JSON metadata to store on the participant.
termsAccepted	Boolean?	Explicit Terms consent for direct signup to an open affiliate program. Omit for referred customers.

mobileInstanceId is generated and sent by the SDK automatically. It is not part of GrowSurfParticipantInput.

GrowSurfParticipantUpdateInput

Field	Type	Description
firstName	String?	Updated first name.
lastName	String?	Updated last name.
metadata	Map<String, Any?>?	Updated JSON metadata.

GrowSurfCampaign

Field	Type
id	String
name	String?
type	String?
referralCount	Int?
participantCount	Int?
impressionCount	Int?
inviteCount	Int?
winnerCount	Int?
currencyISO	String?
status	String?
rewards	List<GrowSurfCampaignReward>

GrowSurfCampaignReward

Field	Type
id	String?
type	String?
event	String?
title	String?
isVisible	Boolean?
description	String?
referralDescription	String?
isUnlimited	Boolean?
limit	Int?
conversionsRequired	Int?
numberOfWinners	Int?
imageUrl	String?
order	Int?
limitDuration	String?
nextMilestonePrefix	String?
nextMilestoneSuffix	String?
couponCode	String?
referralCouponCode	String?
metadata	Map<String, Any?>
commissionStructure	Map<String, Any?>?
value	GrowSurfCampaignRewardTaxValuation?
referredValue	GrowSurfCampaignRewardTaxValuation?
referredRewardUpfront	Boolean?

GrowSurfCampaignRewardTaxValuation

Field	Type
fairMarketValueUSD	Double?
taxCharacter	String?

GrowSurfParticipant

Field	Type
id	String
email	String?
firstName	String?
lastName	String?
isAffiliate	Boolean?
affiliateStatus	String?
shareUrl	String?
referredBy	String?
paypalEmailAddress	String?
referralCount	Int?
leadCount	Int?
inviteCount	Int?
monthlyReferralCount	Int?
prevMonthlyReferralCount	Int?
rank	Int?
monthlyRank	Int?
prevMonthlyRank	Int?
vanityKeys	List<String>
unreadCommissionsCount	Int?
unreadPayoutsCount	Int?
payoutSettings	GrowSurfPayoutSettings?
taxInfo	GrowSurfTaxInfo?

GrowSurfCreateParticipantResponse

Field	Type
success	Boolean?
participantToken	String?
expiresIn	Int?
participant	GrowSurfParticipant?
isNew	Boolean?
requiresParticipantToken	Boolean?
window	GrowSurfWindowResponse?

GrowSurfAddReferredParticipantResponse

Field	Type
added	Boolean
validReferral	Boolean
referredBy	String?
notAddedReason	GrowSurfAddReferredParticipantNotAddedReason?
participantToken	String?
expiresIn	Int?
participant	GrowSurfParticipant?
isNew	Boolean?
requiresParticipantToken	Boolean?

For referred customers in affiliate programs, added is true and participantToken can be null.

GrowSurfAddReferredParticipantNotAddedReason

Case	Value
NO_REFERRER	no_referrer
INVALID_REFERRER	invalid_referrer
PARTICIPANT_ALREADY_EXISTS	participant_already_exists

Referral and reward models

Model	Fields
GrowSurfReferralsResponse	referrals, limit, nextOffset, more
GrowSurfReferral	id, email, firstName, lastName, referralStatus, referredBy, createdAt, updatedAt, referrerEmail, referralTriggeredAt, referralCreditExpiredAt, isAwaitingSignup, canShowFollowUp, canFollowUp, followUpAvailableAt, displayStatus
GrowSurfRewardsResponse	rewards, limit, nextId
GrowSurfReward	id, status, unread, approved, rewardId, isReferrer, isFulfilled, isAvailable, approvedAt, fulfilledAt, referredId, referrerId, amount, currencyISO, commissionStructure
GrowSurfSuccessResponse	success, message
GrowSurfPayoutDestinationConfirmationResponse	success, status, provider, providerDisplayName, expiresAt
GrowSurfAttributionResponse	success, valid, referredBy, accepted, duplicate, availability, reason, visitId, isUnique, receipt
GrowSurfValidateReferrerResponse	success, valid, referredBy
GrowSurfInviteResponse	success, message, messageType, invitesSent

displayStatus is optional and does not change referralStatus. OFFER_CLAIMED means the contact claimed an offer but has not completed signup. The GrowSurf window uses the program’s editable Claimed Offer label. Completed signup takes precedence, including signup that still needs a qualifying purchase.

canShowFollowUp allows the Follow up action only for a direct invitation from the current participant with Company as the Invite Email sender. A later offer claim preserves that invitation; a popup claim alone does not qualify. The Window shows the action when canFollowUp is also true. Confirmation sends the configured invitation email. The action is hidden while sending is unavailable, including the three-day cooldown. Opening the action never sends an email.

GrowSurfReward.status is PENDING, FULFILLED, or CANCELLED. The native GrowSurf window keeps cancelled rows out of earned reward totals and unread badges.

GrowSurf window models

GrowSurfWindowIdentity

Case	Description
Anonymous	Loads the window without participant identity.
ParticipantFields(GrowSurfParticipantInput)	Creates a new participant from fields before loading the window. Existing participants need a participant token; use ExistingParticipantToken(String).
ExistingParticipantToken(String)	Uses a participant token created by your backend or by the SDK.

GrowSurfWindowTheme

Field	Type	Description
primaryColor	Long?	Optional ARGB primary color override, such as 0xFF13795B.
colorScheme	GrowSurfWindowColorScheme	SYSTEM, LIGHT, or DARK.
cornerRadiusDp	Float?	Optional corner radius override in dp.
presentationStyle	GrowSurfWindowPresentationStyle	AUTOMATIC, FULL_SCREEN, or SHEET.

GrowSurfWindowCallbacks

Callback	Type
onOpen	() -> Unit
onClose	() -> Unit
onParticipantCreated	(GrowSurfParticipant, String?) -> Unit
onShareTracked	(String) -> Unit
onInviteSent	() -> Unit
onPayoutOrSettingsAction	(String) -> Unit
onError	(Throwable) -> Unit

GrowSurfWindowController

Method	Description
close()	Closes the presented GrowSurf window.

GrowSurfWindowResponse

Field	Type
version	String?
campaign	GrowSurfWindowCampaign?
signup	GrowSurfWindowSignup?
visibleSections	Map<String, Boolean>
share	GrowSurfWindowShareConfig?
participant	GrowSurfParticipant?
affiliateAccess	GrowSurfWindowAffiliateAccess?
unreadCounts	GrowSurfWindowUnreadCounts?
payoutSettings	GrowSurfPayoutSettings?
content	Map<String, Any?>
resources	GrowSurfWindowResourcesContent?
referrals	GrowSurfReferralsResponse?
rewards	GrowSurfRewardsResponse?
leaderboard	GrowSurfLeaderboardResponse?
referralSummary	GrowSurfReferralSummary?
affiliateSummary	GrowSurfAffiliateSummary?
commissions	GrowSurfCommissionsResponse?
payouts	GrowSurfPayoutsResponse?

Additional window models

Model	Fields
GrowSurfWindowCampaign	id, type, status, companyName, companyLogoImageUrl, goal, currencyISO, shouldDisplayPoweredBy, rewardTypes, rewards, design, countryLabels
GrowSurfWindowSignup	state, canCreateParticipant, affiliateEnrollment
GrowSurfWindowAffiliateEnrollment	access, title, message, actionText, applicationUrl, terms
GrowSurfWindowAffiliateEnrollmentTerms	isRequired, agreementPrefix, title, url
GrowSurfWindowAffiliateAccess	status, title, message
GrowSurfWindowShareConfig	preferredUrl, fallbackUrl, nativeShare, channels, invite
GrowSurfWindowShareChannel	type, label, order, subject, message, nativePreferred
GrowSurfWindowUnreadCounts	commissions, payouts
GrowSurfWindowResourcesContent	isPublicDisplayed, title, viewResourcesLinkText, backLinkText, copyButtonText, copiedText, emptyState, icon, items
GrowSurfWindowResourcesIcon	type, imageUrl
GrowSurfWindowResource	id, type, title, description, category, url, text, file
GrowSurfWindowResourceFile	fileName, mimeType, bytes
GrowSurfWindowResourceDownloadResponse	url, expiresIn
GrowSurfPayoutSettings	provider, paypalEmailAddress, canRequestPaypalConfirmEmail, hostedActions, requiredActions, payoutInstructionsMode, taxInfo, payoutDestinations
GrowSurfPayoutDestinations	activeProvider, enabledProviders, requiresChoice, providers
GrowSurfPayoutDestinationProvider	provider, providerDisplayName, status, claimEmail, needsRepairReason, canConfirm
GrowSurfTaxInfo	status, formType, residencyCountryCode, vatNumber, statusReason, payoutSettings
GrowSurfTaxInfoRefreshPayoutSettings	hostedActions, requiredActions
GrowSurfTaxSessionResponse	hostedUrl, status
GrowSurfTaxInfoSaveResponse	success, taxInfo
GrowSurfLeaderboardResponse	participants, nextKey, page, hasMore
GrowSurfLeaderboardParticipant	id, rank, monthlyRank, prevMonthlyRank, email, isWinner, referralCount, monthlyReferralCount, prevMonthlyReferralCount, pendingReferralCount, revenueAmount, commissionAmount
GrowSurfReferralSummary	referrals, leads, expiredReferrals, clicks, rewardsEarned, pendingRewards, invitesSent, currencyISO
GrowSurfAffiliateSummary	referralRevenue, totalPaidOut, upcomingPayout, referrals, leads, clicks, currencyISO
GrowSurfCommissionsResponse	commissions, totalCount, totalAmount, summary, nextId
GrowSurfCommission	id, amount, currencyISO, status, holdDuration, createdAt, amountInCampaignCurrency, saleAmountInCampaignCurrency, campaignCurrencyISO, unread
GrowSurfPayoutsResponse	payouts, totalCount, totalAmount, summary, nextId
GrowSurfPayout	id, amount, currencyISO, status, paymentMethod, queuedAt, reversedAt, createdAt, amountInCampaignCurrency, campaignCurrencyISO, unread

GrowSurfWindowResource.type is FILE, LINK, or TEXT. Items keep the server-authorized order. category can be null. A FILE contains only safe display metadata; call getParticipantResourceDownloadUrl(resourceId) when the participant opens it. The response never includes private storage coordinates or a durable file URL.

GrowSurfWindowCampaign.design carries the raw participantAvatarStyle value for custom screens. It is CHARACTERS, INITIALS, ANIMALS, or GRADIENT. The built-in window renders it automatically. Treat a missing or unknown value as INITIALS.

payoutDestinations is null when no payout provider applies to the participant. If you build your own settings UI, render providerDisplayName instead of hardcoding a provider name, show the payout method picker when requiresChoice is true, and show the confirm action only when that provider's canConfirm is true. The PayPal-specific provider and paypalEmailAddress fields still work as before.

Advanced interfaces and stores

Use these APIs for tests or custom storage/transport integrations.

Type	Public methods
GrowSurfCallback<T>	onSuccess(result), onError(error)
GrowSurfTokenStore	getSessionToken(), getParticipantToken(), saveSessionToken(token), saveParticipantToken(token), clear()
GrowSurfAttributionStore	getAttribution(), saveAttribution(attribution), clearAttribution(), hasCheckedDeferredDeepLink(), markDeferredDeepLinkChecked()
GrowSurfMobileInstanceIdStore	getMobileInstanceId()
GrowSurfWindowCacheStore	getWindow(cacheKey, nowMillis), saveWindow(cacheKey, windowJson, expiresAtMillis), clear()
GrowSurfInstallReferrerClient	getInstallReferrer()
GrowSurfHttpTransport	execute(request)
GrowSurfHttpRequest	method, url, headers, body, timeoutMillis
GrowSurfHttpResponse	statusCode, body
EncryptedPreferencesGrowSurfTokenStore	Encrypted token store used by default. Clears only GrowSurf token data after confirmed unrecoverable crypto state.
PreferencesGrowSurfAttributionStore	SharedPreferences-backed attribution store used by default.
PreferencesGrowSurfMobileInstanceIdStore	SharedPreferences-backed mobile instance ID store used by default.
PreferencesGrowSurfWindowCacheStore	SharedPreferences-backed window cache store.
EncryptedPreferencesGrowSurfWindowCacheStore	Encrypted window cache store used by default.
UrlConnectionGrowSurfHttpTransport	Default HTTP transport.
PlayStoreGrowSurfInstallReferrerClient	Default Google Play Install Referrer client.

Android backup rules

Android backs up SharedPreferences, but every GrowSurf preference file is device-scoped or regenerable, and a restored copy causes problems rather than preserving anything useful. Exclude all six from cloud backup and device transfer:

File	Why a restored copy is harmful
growsurf_tokens.xml	Encrypted. Android does not back up the Keystore key, so the restored ciphertext is unreadable.
growsurf_window_cache_encrypted.xml	Encrypted, same reason.
growsurf_attribution.xml	A restored "already checked" flag makes the SDK skip the Install Referrer query, so a genuinely new referred install loses its referral with no error.
growsurf_identity.xml	Holds the per-install id. Restoring it clones one install identity onto a second device.
growsurf_window_cache.xml	Cleartext cache. Regenerable, and a restored copy is stale.
growsurf_participant_engagement.xml	Holds pending participant engagement for this install. Restoring it can replay old portal or share activity on another device.

If your app does not have backup rules, point the <application> element in your manifest to the rules included with the SDK:

<application
    android:fullBackupContent="@xml/growsurf_backup_rules"
    android:dataExtractionRules="@xml/growsurf_data_extraction_rules"
    ... />

Android supports one app-wide file for each rule type. If your app already has either file, keep your existing rules and add all six GrowSurf exclusions to it. Do not replace exclusions required by another SDK.

Errors

The SDK throws:

• GrowSurfException for SDK state errors such as missing participant tokens.

• GrowSurfHttpException for non-2xx HTTP responses. Exposes a statusCode: Int property and the response body as the exception message.