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

# Android

> Embed the postcode widget in a native Android app with ng.nipost:postcode-widget.

```kotlin theme={null}
dependencies {
  implementation("ng.nipost:postcode-widget:0.1.0")
}
```

Maven publication is pending — until it lands, consume the SDK as a Gradle
project dependency or a local AAR.

## Usage

```kotlin theme={null}
import ng.nipost.postcode.widget.IdentifierType
import ng.nipost.postcode.widget.PostcodeWidget
import ng.nipost.postcode.widget.PostcodeWidgetConfig

PostcodeWidget.show(
  context,
  PostcodeWidgetConfig(
    publishableKey = "nipost_pk_live_…",
    identifierType = IdentifierType.EMAIL,
    prefilledIdentifier = "ada@example.com",
  ),
) { selection ->
  if (selection != null) {
    Log.d("Postcode", "picked ${selection.formatted}")
  }
}
```

`show()` launches the widget in its own activity — identity screen (replaced by
a confirm screen when `prefilledIdentifier` is set), bookmarks, search, and the
map-based discover flow — and invokes the callback with the
[`PostcodeSelection`](/widget/overview#the-selection-payload), or `null` if the
user backed out. `selection.toJson()` produces exactly the wire shape every
other SDK delivers.

## Configuration

| Field                                | Notes                                                         |
| ------------------------------------ | ------------------------------------------------------------- |
| `publishableKey`                     | **Required.** Your `nipost_pk_…` key.                         |
| `identifierType`                     | `IdentifierType.NIN` or `IdentifierType.EMAIL`.               |
| `prefilledIdentifier`                | Locks the identity field and shows a confirm screen when set. |
| `platformBaseUrl` / `gatewayBaseUrl` | Override hosts (staging / local dev).                         |
| `theme`                              | `PostcodeWidgetTheme` color and radius overrides.             |

The SDK requires `minSdk 24` but no Compose host — it brings its own Compose UI
inside its own activity, so any Android app works. Hosts declare no extra
permissions: `INTERNET` and location arrive via manifest merge, and the widget
requests location permission itself for the "Get your Postcode" discover flow.