# Android SDK (Beta)

The GrowSurf Android SDK lets you add referral sharing and attribution to a native Android 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, Google Play Install Referrer payloads, and deferred deep links from providers such as Branch, Adjust, AppsFlyer, or Singular.
* Track referred users through Play 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:

* Android API 23 or later
* `android.useAndroidX=true`
* Kotlin coroutines
* Compose runtime dependencies resolved through the core SDK artifact
* Maven Central in your Gradle repositories

#### 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/UePngBTAY3vCvOxFhvwx" 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/eaZqhesanMDoxLA3ckru" 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

Add the core SDK from Maven Central.

{% tabs %}
{% tab title="Kotlin DSL" %}

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    implementation("com.growsurf:growsurf-android-sdk:0.2.0")
}
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.growsurf:growsurf-android-sdk:0.2.0'
}
```

{% endtab %}
{% endtabs %}

If you use Branch, Adjust, AppsFlyer, or Singular, add the matching GrowSurf adapter.

{% tabs %}
{% tab title="Kotlin DSL" %}

```kotlin
dependencies {
    implementation("com.growsurf:growsurf-android-sdk-attribution-branch:0.2.0")
    implementation("com.growsurf:growsurf-android-sdk-attribution-adjust:0.2.0")
    implementation("com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.2.0")
    implementation("com.growsurf:growsurf-android-sdk-attribution-singular:0.2.0")
}
```

{% endtab %}

{% tab title="Groovy" %}

```groovy
dependencies {
    implementation 'com.growsurf:growsurf-android-sdk-attribution-branch:0.2.0'
    implementation 'com.growsurf:growsurf-android-sdk-attribution-adjust:0.2.0'
    implementation 'com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.2.0'
    implementation 'com.growsurf:growsurf-android-sdk-attribution-singular:0.2.0'
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Keep your provider's own SDK setup in your app. The GrowSurf adapter passes provider callback data into GrowSurf. Maven Central is recommended because Gradle resolves the SDK's required dependencies for you.
{% 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/android-sdk#enable-mobile-sdk-access-on-growsurf)

```kotlin
import com.growsurf.sdk.GrowSurfSdk

val growsurf = GrowSurfSdk.configure(
    context = context,
    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:

```kotlin
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:

```kotlin
intent.data?.let { uri ->
    growsurf.handleDeepLink(uri)
}
```

For Google Play installs, call `handleDeferredDeepLink()` once before participant creation:

```kotlin
lifecycleScope.launch {
    growsurf.handleDeferredDeepLink()
}
```

For deferred deep links from an attribution provider:

```kotlin
growsurf.handleAttributionParameters(
    mapOf(
        "grsf" to "referrer_id",
        "click_id" to "click_123",
        "unique" to "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.

```kotlin
val created = growsurf.createParticipant(
    GrowSurfParticipantInput(
        email = "person@example.com",
        firstName = "Ada",
        lastName = "Lovelace",
        metadata = mapOf("plan" to "pro"),
    )
)

val participant = created.participant
```

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

## Show the GrowSurf window

{% hint style="info" %}
The native GrowSurf window is a fully native Compose, 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.

```kotlin
growsurf.presentGrowSurfWindow(
    activity = this,
    identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken),
    theme = GrowSurfWindowTheme(
        primaryColor = 0xFF13795B,
        presentationStyle = GrowSurfWindowPresentationStyle.AUTOMATIC,
    ),
    callbacks = GrowSurfWindowCallbacks(
        onParticipantCreated = { participant ->
            Log.d("GrowSurf", "Participant: ${participant.id}")
        },
        onShareTracked = { type ->
            Log.d("GrowSurf", "Share tracked: $type")
        },
        onError = { error ->
            Log.e("GrowSurf", "GrowSurf window error", error)
        },
    ),
)
```

Use `GrowSurfWindowIdentity.Anonymous` to show the signup state, `GrowSurfWindowIdentity.ParticipantFields(...)` to create or load a participant from fields, or `GrowSurfWindowIdentity.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 Android cannot open a channel-specific target, the SDK falls back to the system share sheet.

## 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:

```kotlin
growsurf.setParticipantToken(participantToken)
```

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

```kotlin
growsurf.shutdown()
```

## Show referral data in your app

```kotlin
val participant = growsurf.getParticipant(participantId)
val referrals = growsurf.getParticipantReferrals(participantId)
val rewards = growsurf.getParticipantRewards(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:

```kotlin
growsurf.triggerReferral(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/GhQfB3WsJlg97Hqpy7n9" %}
[Attribution Providers](/developer-tools/android-sdk/attribution-providers.md)
{% endcontent-ref %}

{% content-ref url="/pages/XLxytePFauV0nWRkLmv8" %}
[API Reference](/developer-tools/android-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/android-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.