Models and Errors

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

This reference documents the models, callbacks, advanced protocols, stores, and errors exposed by the GrowSurf iOS SDK.

Core models

GrowSurfConfiguration

Field	Type	Description
campaignId	String	GrowSurf program ID.
publicKey	String	Mobile SDK public key.
baseURL	URL	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	Bool?	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	[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	[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	[GrowSurfCampaignReward]

GrowSurfCampaignReward

Field	Type
id	String?
type	String?
title	String?
description	String?
referralDescription	String?
isUnlimited	Bool?
limit	Int?
conversionsRequired	Int?
numberOfWinners	Int?
imageUrl	String?
order	Int?
limitDuration	String?
nextMilestonePrefix	String?
nextMilestoneSuffix	String?
couponCode	String?
referredRewardUpfront	Bool?

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	[String]?
unreadCommissionsCount	Int?
unreadPayoutsCount	Int?

GrowSurfCreateParticipantResponse

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

GrowSurfAddReferredParticipantResponse

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

GrowSurfAddReferredParticipantNotAddedReason

Case	Raw value
.noReferrer	no_referrer
.invalidReferrer	invalid_referrer
.participantAlreadyExists	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, isReferrer, title, description
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
primaryColorHex	String?	Optional primary color override, such as #13795B.
colorScheme	GrowSurfWindowTheme.ColorScheme	.system, .light, or .dark.
cornerRadius	Double?	Optional corner radius override.
presentationStyle	GrowSurfWindowTheme.PresentationStyle	.automatic, .fullScreen, or .sheet.

GrowSurfWindowCallbacks

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

GrowSurfWindowController

Method	Description
close()	Closes the presented GrowSurf window.

GrowSurfWindowResponse

Field	Type
version	String?
campaign	GrowSurfWindowCampaign?
signup	GrowSurfWindowSignup?
visibleSections	[String: Bool]
share	GrowSurfWindowShareConfig?
participant	GrowSurfParticipant?
unreadCounts	GrowSurfWindowUnreadCounts?
payoutSettings	GrowSurfPayoutSettings?
content	[String: GrowSurfJSONValue]?
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
GrowSurfJSONValue	.string, .number, .bool, .object, .array, .null

Advanced protocols and stores

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

Type	Public methods
GrowSurfHTTPClient	data(for:)
GrowSurfTokenStore	sessionToken(), participantToken(), saveSessionToken(_:), saveParticipantToken(_:), clear()
GrowSurfAttributionStore	attribution(), saveAttribution(_:), clearAttribution()
GrowSurfMobileInstanceIdStore	mobileInstanceId()
GrowSurfWindowCacheStore	windowData(cacheKey:now:), saveWindowData(_:cacheKey:expiresAt:), clear()
GrowSurfUserDefaultsAttributionStore	UserDefaults-backed attribution store.
GrowSurfUserDefaultsMobileInstanceIdStore	UserDefaults-backed mobile instance ID store.
GrowSurfUserDefaultsWindowCacheStore	UserDefaults-backed window cache store.
GrowSurfFileWindowCacheStore	File-backed window cache store used by default.
GrowSurfKeychainTokenStore	Keychain-backed token store used by default.

Errors

GrowSurfError can be:

• invalidURL

• missingSessionToken

• missingParticipantToken

• invalidResponse

• httpStatus(Int, String?)