# iOS SDK (Beta)

The GrowSurf iOS SDK lets you add referral sharing and attribution to a native iOS app. Use it to capture deep links, track referrals, generate/show referral links, or show referral data in your own UI.

With the SDK, your app can:

* Capture direct deep links and deferred deep links from providers such as Branch, Adjust, AppsFlyer, or Singular.
* Track referred users through App Store installation and signup.
* Present the out-of-the-box GrowSurf popup window from your own button or menu. Or show referral links, referral counts, referral statuses, and rewards inside your app using public SDK methods.

## Before you start

Make sure to have the right requirements below:

* iOS 15 or later
* CocoaPods, Swift Package Manager, or manual XCFramework installation

#### Enable Mobile SDK access on GrowSurf

<details>

<summary><strong>How to enable mobile SDK access in your GrowSurf program</strong></summary>

1. Go to *Program Editor > 5. Installation* then click the *Next* buttons until you reach the final installation page.
2. Click *Configure SDK*

   <figure><img src="/files/KejIb5790sbQkgNtzhV5" alt=""><figcaption></figcaption></figure>
3. Enable the Mobile SDK
4. You'll be using the Mobile SDK Public Key when making calls to GrowSurf

   <figure><img src="/files/Q87HuFxdhWaV3tyTlpq9" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
This public Mobile SDK key is generated by GrowSurf and can be used in your app (it is safe to be exposed). This is different from your secret REST API key, which you should keep on your backend and never expose.
{% endhint %}

</details>

## Install

Choose one install path.

{% tabs %}
{% tab title="CocoaPods" %}
Add the SDK from the public `v0.2.0` podspec:

```ruby
growsurf_podspec = 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.2.0/GrowSurfSDK.podspec'

pod 'GrowSurfSDK', :podspec => growsurf_podspec
```

Optional attribution adapter subspecs:

```ruby
pod 'GrowSurfSDK/BranchAttribution', :podspec => growsurf_podspec
pod 'GrowSurfSDK/AdjustAttribution', :podspec => growsurf_podspec
pod 'GrowSurfSDK/AppsFlyerAttribution', :podspec => growsurf_podspec
pod 'GrowSurfSDK/SingularAttribution', :podspec => growsurf_podspec
```

{% endtab %}

{% tab title="Swift Package Manager" %}
In Xcode, add the public binary package repository:

```
https://github.com/growsurf/growsurf-ios-sdk-distribution.git
```

Choose version `0.2.0` or later, then add the `GrowSurfSDK` product to your app target.

For a `Package.swift` target:

```swift
dependencies: [
    .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.2.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"),
        ]
    ),
]
```

Optional attribution adapter products are available from the same package:

* `GrowSurfBranchAttribution`
* `GrowSurfAdjustAttribution`
* `GrowSurfAppsFlyerAttribution`
* `GrowSurfSingularAttribution`
  {% endtab %}

{% tab title="Manual XCFramework" %}

1. Download `GrowSurfSDK.xcframework.zip` from the public [`v0.2.0` release](https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.2.0).
2. Unzip it and drag `GrowSurfSDK.xcframework` into your Xcode project.
3. In your app target, set `GrowSurfSDK.xcframework` to **Embed & Sign**.
4. Add optional adapter XCFrameworks the same way when you use Branch, Adjust, AppsFlyer, or Singular helpers.
   {% endtab %}
   {% endtabs %}

{% hint style="info" %}
Using Branch, Adjust, AppsFlyer, or Singular? Add the matching GrowSurf adapter and keep your provider's own SDK setup in your app. The GrowSurf adapter passes provider callback data into GrowSurf.
{% endhint %}

## Initialize

Configure the SDK once when your app starts or before your first GrowSurf call.

* You can retrieve `campaignId` by logging into your GrowSurf program dashboard and finding the 6-digit unique ID (e.g, `p9josq`)
* You can retrieve `publicKey` from [*Enable Mobile SDK access on GrowSurf*](https://docs.growsurf.com/developer-tools/ios-sdk#enable-mobile-sdk-access-on-growsurf)

```swift
import GrowSurfSDK

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

Most apps do not need to create a session manually. The SDK creates one when it needs to call GrowSurf:

```swift
try await growsurf.createSession()
```

## Capture attribution

Capture referral attribution before you create the referred friend's participant record.

For direct app links that open your installed app:

```swift
if let url {
    try await growsurf.handleDeepLink(url)
}
```

For deferred deep links from an attribution provider:

```swift
try await growsurf.handleAttributionParameters(
    [
        "grsf": "referrer_id",
        "click_id": "click_123",
        "unique": "true",
    ],
    provider: "branch"
)
```

The SDK stores the referral attribution locally and sends it with the next `createParticipant(_:)` call.

## Create a participant

Create a participant when the user signs up or when your app can identify the user by email.

```swift
let created = try await growsurf.createParticipant(
    .init(
        email: "person@example.com",
        firstName: "Ada",
        lastName: "Lovelace",
        metadata: ["plan": "pro"]
    )
)

let participant = created.participant
```

When GrowSurf creates a new participant, the SDK stores the returned participant token in Keychain.

## Show the GrowSurf window

{% hint style="info" %}
The native GrowSurf window is a fully native SwiftUI, uses your existing dashboard GrowSurf window settings, and is opened only when your app calls `presentGrowSurfWindow(...)`.
{% endhint %}

Call it from your own button, menu item, or referral screen. The SDK does not add a default launcher.

```swift
growsurf.presentGrowSurfWindow(
    from: viewController,
    identity: .existingParticipantToken(participantToken),
    theme: GrowSurfWindowTheme(
        primaryColorHex: "#13795B",
        presentationStyle: .automatic
    ),
    callbacks: GrowSurfWindowCallbacks(
        onParticipantCreated: { participant in
            print("Participant: \(participant.id)")
        },
        onShareTracked: { type in
            print("Share tracked: \(type)")
        },
        onError: { error in
            print(error.localizedDescription)
        }
    )
)
```

Use `.anonymous` to show the signup state, `.participantFields(...)` to create or load a participant from fields, or `.existingParticipantToken(...)` for a signed-in participant token from your backend.

The GrowSurf window includes the referral link, native share sheet, enabled share channels, QR code, email invites, referrals, rewards, leaderboard, affiliate summary, commissions, payouts, participant settings, how-it-works, FAQ, and terms when those sections are enabled for the program. Some channel apps restrict prefilled text, especially Facebook; when iOS cannot open a channel-specific share target, use the system share sheet fallback.

## Use participant tokens

A participant token lets your app access referral data for one participant.

If the app creates a participant, the SDK stores the participant token automatically. For an existing signed-in user, have your backend [create a mobile participant token](/developer-tools/rest-api/api-reference.md#create-mobile-participant-token) and pass it to the app:

```swift
try await growsurf.setParticipantToken(participantToken)
```

Use `shutdown()` when the user signs out:

```swift
try await growsurf.shutdown()
```

## Show referral data in your app

```swift
let participant = try await growsurf.getParticipant(id: participantId)
let referrals = try await growsurf.getParticipantReferrals(id: participantId)
let rewards = try await growsurf.getParticipantRewards(id: participantId)
```

Use these methods to show a native referral portal with the participant's referral link, referral counts, referral statuses, and rewards.

## Trigger referral credit

Use `triggerReferral` when a referred friend completes a low-risk milestone in the app:

```swift
try await growsurf.triggerReferral(participantId: participantId)
```

{% hint style="warning" %}
For purchases, subscriptions, completed bookings, or events that determine whether rewards should be issued, trigger referral credit from your backend with the [REST API](/developer-tools/rest-api.md).
{% endhint %}

## Next steps

{% content-ref url="/pages/YE7Ni8qQb5eckfGra6D3" %}
[Attribution Providers](/developer-tools/ios-sdk/attribution-providers.md)
{% endcontent-ref %}

{% content-ref url="/pages/NfDPGxhzyFbz5HJzp01b" %}
[API Reference](/developer-tools/ios-sdk/api-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/exdoU1ymhoG3SfIjmIsO" %}
[Getting Started for Native Mobile](/getting-started-for-native-mobile.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.growsurf.com/developer-tools/ios-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.