# Quick start

> Install and configure the Grovs Android SDK in your app.

Source: https://docs.grovs.io/docs/sdk/android/quick-start

Install the SDK, configure it in your `Application` class and open your first link on a device. Takes about ten minutes.

**Using an AI coding agent?**

Copy one prompt into Claude Code, Cursor or Copilot and it does these steps in your project.

```text
Add Grovs deep linking to this Android app (example app: Medly).

1. Add implementation("io.grovs:Grovs:3.1.0") to the app-level build.gradle.
2. In the Application class onCreate, call Grovs.configure(this, apiKey, useTestEnvironment = ...). Read the key from BuildConfig or the existing secrets setup (env GROVS_API_KEY). Use the test environment only in debug builds.
3. In the launcher activity, call Grovs.onStart(this) from onStart and Grovs.onNewIntent(intent, this) from onNewIntent.
4. Add intent filters to the launcher activity: the custom URL scheme from the Grovs dashboard (SDK Setup → Android), and autoVerify App Links for the production and test link hosts.
5. Register Grovs.setOnDeeplinkReceivedListener in the launcher activity and route the payload to the existing navigation.
6. Build, then list what you changed plus the package name and SHA-256 fingerprint to register in the Grovs dashboard.

Docs: https://docs.grovs.io/docs/sdk/android/quick-start.md
```

> **Note:** Upgrading? See [3.0 to 3.1](https://docs.grovs.io/docs/upgrade-guides/android-3-1) or [1.x to 3.0](https://docs.grovs.io/docs/upgrade-guides/android-3-0).

## Requirements

- Android 5.0 (API 21)+
- Kotlin 1.8+ or Java 8+
- Your package name and SHA-256 signing fingerprint registered in the Grovs dashboard. See [How to Get the Package Name](https://docs.grovs.io/docs/how-to-guides/android/package-name) and [How to Get the SHA-256 Fingerprint](https://docs.grovs.io/docs/how-to-guides/android/sha256-fingerprint).

## Installation

Add the dependency to your app-level `build.gradle`. It's published on [Maven Central](https://central.sonatype.com/artifact/io.grovs/Grovs).

```groovy
dependencies {
    implementation("io.grovs:Grovs:3.1.0")
}
```

## Configuration

### 1. Initialize the SDK

In your `Application` class:

```kotlin
import io.grovs.Grovs
import io.grovs.model.LogLevel

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Optional: verbose logging while integrating
        Grovs.setDebug(LogLevel.INFO)

        Grovs.configure(this, "your-api-key", useTestEnvironment = false)

        // Optional: identify the user
        Grovs.identifier = "user_id_from_your_app"
        Grovs.attributes = mapOf("name" to "John Doe", "plan" to "premium")
    }
}
```

### Configuration options

`configure` has four overloads. Each adds one parameter and requires all earlier ones:

```kotlin
Grovs.configure(application, apiKey, useTestEnvironment, baseURL = null)
Grovs.configure(application, apiKey, useTestEnvironment, baseURL, autoTrackScreenViews)
Grovs.configure(application, apiKey, useTestEnvironment, baseURL, autoTrackScreenViews, clipboardDomains)
Grovs.configure(application, apiKey, useTestEnvironment, baseURL, autoTrackScreenViews, clipboardDomains, enabled)
```

Only `baseURL` has a default. Shorter overloads behave as if `autoTrackScreenViews = true`, `clipboardDomains = null` and `enabled = true`.

| Parameter              | Default     | Description                                                                                                                                                                                                   |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `application`          | Required    | Your `Application` instance.                                                                                                                                                                                  |
| `apiKey`               | Required    | Project API key from the Grovs dashboard.                                                                                                                                                                     |
| `useTestEnvironment`   | Required    | `true` targets the test environment (its own domain, links and data). `false` targets production. Use `true` only in development builds.                                                                      |
| `baseURL`              | Grovs cloud | Domain of a [self-hosted backend](https://docs.grovs.io/docs/self-hosting/configure/sdk-configuration), for example `"https://sdk.example.com"`. The SDK appends the API path.                                |
| `autoTrackScreenViews` | `true`      | Track Activity and Fragment screen views automatically. See [Events & Screen Tracking](https://docs.grovs.io/docs/sdk/android/analytics#automatic-screen-tracking).                                           |
| `clipboardDomains`     | none        | Extra link hosts accepted by [clipboard-assisted deferred deep linking](https://docs.grovs.io/docs/sdk/android/deep-linking#clipboard-assisted-deferred-deep-linking). Grovs-owned hosts are always accepted. |
| `enabled`              | `true`      | Whether the SDK may collect and send anything this launch. Pass your stored consent value; it isn't persisted. See [Privacy & Consent](https://docs.grovs.io/docs/sdk/android/privacy).                       |

To set a later parameter, pass every earlier one, by name or position:

```kotlin
Grovs.configure(
    this,
    "your-api-key",
    useTestEnvironment = false,
    baseURL = null,
    autoTrackScreenViews = false,
    clipboardDomains = listOf("links.yourdomain.com"),
    enabled = hasConsent
)
```

`identifier`, `attributes` and `pushToken` can be set before or after `configure`. Values set earlier are kept and sent once the SDK authenticates.

Calling `configure` again replaces the previous configuration. Shorter overloads reset `enabled` to `true`, so a `setSDK(false)` before `configure` doesn't carry over. Pass consent through `configure` instead.

### 2. Forward lifecycle events

In your **launcher activity**, forward `onStart` and `onNewIntent` so the SDK can resolve incoming links:

```kotlin
class MainActivity : AppCompatActivity() {
    override fun onStart() {
        super.onStart()
        Grovs.onStart(this)
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        Grovs.onNewIntent(intent, this)
    }
}
```

### 3. Add intent filters

Add these to your launcher activity in `AndroidManifest.xml`:

```xml
<!-- Custom URL scheme -->
<intent-filter>
    <data android:scheme="your_app_scheme" android:host="open" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
</intent-filter>

<!-- App links (production) -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your_app_host" />
</intent-filter>

<!-- App links (test) -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your_app_test_host" />
</intent-filter>
```

The SDK declares the `INTERNET` and `ACCESS_NETWORK_STATE` permissions itself. It doesn't declare `POST_NOTIFICATIONS`; see [Push notifications](https://docs.grovs.io/docs/sdk/android/push-notifications#3-ask-for-permission-and-pass-the-token).

## Next steps

- [Handle incoming deep links →](https://docs.grovs.io/docs/sdk/android/deep-linking)
- [Generate smart links →](https://docs.grovs.io/docs/sdk/android/link-creation)
- [Receive push campaigns →](https://docs.grovs.io/docs/sdk/android/push-notifications)
- [Show in-app messages →](https://docs.grovs.io/docs/sdk/android/in-app-messages)
- [Track events and screens →](https://docs.grovs.io/docs/sdk/android/analytics)
- [Gate collection on user consent →](https://docs.grovs.io/docs/sdk/android/privacy)
- [Explore the Android example app →](https://github.com/grovs-io/grovs-android-example-app)

## See also

- [How to Get the Package Name](https://docs.grovs.io/docs/how-to-guides/android/package-name): the application ID the Grovs dashboard asks for
- [How to Get the SHA-256 Fingerprint](https://docs.grovs.io/docs/how-to-guides/android/sha256-fingerprint): debug and release fingerprints for App Links verification
- [How to Add a New Intent Filter](https://docs.grovs.io/docs/how-to-guides/android/intent-filter): intent filters in more detail
- [How to Add a package with Gradle](https://docs.grovs.io/docs/how-to-guides/android/gradle): Gradle dependency setup
- [Deep link not opening the app](https://docs.grovs.io/docs/troubleshooting/deep-link-not-opening-app): links open the browser instead of the app
- [SDK configuration issues](https://docs.grovs.io/docs/troubleshooting/sdk-configuration-issues): common setup and initialization problems