Models and Errors

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

This reference documents the models, callbacks, advanced interfaces, stores, 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.

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, String>?	Custom metadata to store on the participant.

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, String>?	Updated 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?
title	String?
description	String?
referralDescription	String?
isUnlimited	Boolean?
limit	Int?
conversionsRequired	Int?
numberOfWinners	Int?
imageUrl	String?
order	Int?
limitDuration	String?
nextMilestonePrefix	String?
nextMilestoneSuffix	String?
couponCode	String?
referredRewardUpfront	Boolean?

GrowSurfParticipant

Field	Type
id	String
email	String?
firstName	String?
lastName	String?
shareUrl	String?
paypalEmailAddress	String?
referralCount	Int?
inviteCount	Int?
monthlyReferralCount	Int?
prevMonthlyReferralCount	Int?
rank	Int?
monthlyRank	Int?
prevMonthlyRank	Int?
vanityKeys	List<String>
unreadCommissionsCount	Int?
unreadPayoutsCount	Int?

GrowSurfCreateParticipantResponse

Field	Type
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?

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, referralStatus, createdAt, updatedAt, referralTriggeredAt, referralCreditExpiredAt
GrowSurfRewardsResponse	rewards, limit, nextId
GrowSurfReward	id, status, unread, approved, rewardId, title, description, isReferrer
GrowSurfSuccessResponse	success, message
GrowSurfAttributionResponse	success, valid, referredBy
GrowSurfValidateReferrerResponse	success, valid, referredBy
GrowSurfInviteResponse	success, message, messageType

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) with a token created by your backend or returned by the SDK.
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?
unreadCounts	GrowSurfWindowUnreadCounts?
payoutSettings	GrowSurfPayoutSettings?
content	Map<String, Any?>
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
GrowSurfWindowSignup	state, canCreateParticipant
GrowSurfWindowShareConfig	preferredUrl, fallbackUrl, nativeShare, channels, invite
GrowSurfWindowShareChannel	type, label, order, subject, message, nativePreferred
GrowSurfWindowUnreadCounts	commissions, payouts
GrowSurfPayoutSettings	provider, paypalEmailAddress, canRequestPaypalConfirmEmail, hostedActions, requiredActions, taxInfo
GrowSurfTaxInfo	status, formType
GrowSurfTaxSessionResponse	hostedUrl, status
GrowSurfLeaderboardResponse	participants, offsetKey, 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, saleAmountAmountInCampaignCurrency, campaignCurrencyISO, unread
GrowSurfPayoutsResponse	payouts, totalCount, totalAmount, summary, nextId
GrowSurfPayout	id, amount, currencyISO, status, queuedAt, createdAt, amountInCampaignCurrency, campaignCurrencyISO, unread

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	EncryptedSharedPreferences-backed token store used by default.
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	EncryptedSharedPreferences-backed window cache store used by default.
UrlConnectionGrowSurfHttpTransport	Default HTTP transport.
PlayStoreGrowSurfInstallReferrerClient	Default Google Play Install Referrer client.

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.