> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplink.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK

> Integrate the Uplink native SDK into your Android app

The Uplink Android SDK embeds a worker inside your Android app, making the device controllable from server-side code written with the [JavaScript SDK](/api-reference/overview). Use it when you want Uplink automation to run inside your own branded app.

<Info>
  **Key concepts:**

  * **Device**: A physical Android device or emulator running your app
  * **Worker**: A worker created by the Uplink SDK inside your app (one app can create multiple workers)
  * **Session**: An authenticated connection that pairs your worker with a JavaScript SDK client
</Info>

## Requirements

* Android API 21 (Android 5.0) or later
* Kotlin 2.1 or later
* Java 11 or later

## Installation

The Android SDK is distributed as a Maven artifact.

<Note>
  A fully public Maven distribution is coming soon. In the meantime, reach out to Uplink for access credentials and use the repository configuration below.
</Note>

<Steps>
  <Step title="Add the Maven repository">
    In your root `settings.gradle.kts` (or `build.gradle.kts`):

    ```kotlin theme={null}
    dependencyResolutionManagement {
      repositories {
        mavenCentral()
        maven {
          url = uri("https://maven.pkg.github.com/uplink-code/uplink")
          credentials {
            username = System.getenv("GITHUB_ACTOR")
            password = System.getenv("GITHUB_TOKEN")
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Add the dependency">
    In your app module's `build.gradle.kts`:

    ```kotlin theme={null}
    dependencies {
      implementation("build.uplink:core:0.0.0-alpha10")
    }
    ```
  </Step>

  <Step title="Declare the internet permission">
    In `AndroidManifest.xml`:

    ```xml theme={null}
    <uses-permission android:name="android.permission.INTERNET" />
    ```
  </Step>
</Steps>

## Quick example

```kotlin theme={null}
import android.view.ViewGroup
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import build.uplink.worker
import kotlinx.coroutines.launch

suspend fun startUplink(activity: ComponentActivity, container: ViewGroup, sessionUrl: String) {
  val worker = worker(activity, container)

  worker.connect(sessionUrl)

  activity.lifecycleScope.launch {
    worker.accept()
  }
}
```

## Initialization

### `worker(context, group)`

Creates a new `Worker` and mounts the SDK's `WebView` into the provided `ViewGroup`.

```kotlin theme={null}
fun worker(context: Context, group: ViewGroup): Worker
```

**Parameters:**

* `context`: An Android `Context` — typically your `Activity`
* `group`: The `ViewGroup` that will host the SDK's web view

**Returns:** A new `Worker` ready to connect to a session

```kotlin theme={null}
val worker = worker(activity, container)
```

<Tip>
  The `ViewGroup` you pass in must remain in the view hierarchy for the lifetime of the worker. Tearing down the containing Activity or Fragment will close the worker.
</Tip>

## Obtaining a session

Your backend creates a session using the JavaScript SDK's `uplink.session()` and delivers the resulting session URL to the app. How you deliver it — a backend API response, an app link, a QR code — is up to you.

```kotlin theme={null}
val sessionUrl: String = // from your backend, deep link, or QR code
```

See [Sessions](/sessions) for how sessions are created on the server side.

## Connecting and accepting

### `worker.connect(session)`

Connects the worker to an Uplink session.

```kotlin theme={null}
suspend fun connect(session: String)
```

**Parameters:**

* `session`: The session URL provided by your backend

```kotlin theme={null}
worker.connect(sessionUrl)
```

### `worker.accept()`

Begins accepting commands from the JavaScript SDK client. `accept()` suspends until the worker closes, so launch it in a coroutine scope that matches your app's lifecycle.

```kotlin theme={null}
suspend fun accept()
```

```kotlin theme={null}
lifecycleScope.launch {
  worker.accept()
}
```

## Cleanup

### `worker.close()`

Closes the worker and releases its resources.

```kotlin theme={null}
suspend fun close()
```

```kotlin theme={null}
worker.close()
```

<Warning>
  Closing a worker ends its session. Any browsers the JavaScript SDK has launched on the worker will be terminated.
</Warning>

## Complete example

A minimal `Activity` that starts an Uplink worker and tears it down on destroy:

```kotlin theme={null}
import android.os.Bundle
import android.view.ViewGroup
import android.widget.FrameLayout
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import build.uplink.worker
import build.uplink.worker.Worker
import kotlinx.coroutines.launch

class UplinkActivity : ComponentActivity() {
  private var worker: Worker? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val container = FrameLayout(this)
    setContentView(container, ViewGroup.LayoutParams(MATCH_PARENT, MATCH_PARENT))

    val sessionUrl = intent.getStringExtra("sessionUrl") ?: return
    val worker = worker(this, container).also { this.worker = it }

    lifecycleScope.launch {
      try {
        worker.connect(sessionUrl)
        worker.accept()
      } catch (e: Exception) {
        println("Uplink worker ended: $e")
      }
    }
  }

  override fun onDestroy() {
    super.onDestroy()
    lifecycleScope.launch {
      worker?.close()
    }
  }

  companion object {
    private const val MATCH_PARENT = ViewGroup.LayoutParams.MATCH_PARENT
  }
}
```

## Related

<CardGroup cols={2}>
  <Card title="iOS SDK" icon="apple" href="/api-reference/ios">
    Integrate Uplink into your iOS app
  </Card>

  <Card title="JavaScript SDK" icon="plug" href="/api-reference/overview">
    Control your worker from server-side code
  </Card>

  <Card title="Sessions" icon="key" href="/sessions">
    How sessions are created and secured
  </Card>

  <Card title="Core concepts" icon="book" href="/fundamentals/core-concepts">
    Architecture overview
  </Card>
</CardGroup>