Android

The SDK is on Maven Central. Make sure mavenCentral() is among your repositories, in settings.gradle.kts for a standard Android project:

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
  }
}

Then add the dependency in your module’s build.gradle.kts:

dependencies {
  implementation("ng.gov.postcode:postcode-widget:0.1.0")
}

Or with a version catalog, in gradle/libs.versions.toml:

[versions]
postcodeWidget = "0.1.0"

[libraries]
postcode-widget = { group = "ng.gov.postcode", name = "postcode-widget", version.ref = "postcodeWidget" }

The library needs minSdk 24 or higher. It brings its own UI, so the host app does not need Jetpack Compose, and the INTERNET and location permissions it declares merge into your manifest automatically.

Usage

import ng.gov.postcode.widget.IdentifierType
import ng.gov.postcode.widget.PostcodeWidget
import ng.gov.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: the identity screen (replaced by a confirm screen when prefilledIdentifier is set), saved postcodes, and the map-based discover flow. It invokes the callback with the PostcodeSelection, 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.
`environment`	`PostcodeEnvironment.PRODUCTION` (default) or `.STAGING`. Keys are minted per environment, so a `nipost_pk_test_…` key only resolves on staging.
`platformBaseUrlOverride`	A host outside the standard environments (local stack, preview deploy). Wins over `environment`.
`theme`	`PostcodeWidgetTheme` color and radius overrides.

The SDK requires minSdk 24 and brings its own 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 Postcode on Map” discover flow.

Getting started

Concepts

Widget

Usage

Configuration

​Usage

​Configuration

Usage

Configuration