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

# iOS

> Embed the postcode widget in a native iOS app with the NipostPostcodeWidget Swift Package.

Add the package with Swift Package Manager: in Xcode choose
**File > Add Package Dependencies** and enter
`https://github.com/MilsatLtd/postcode-widget-swift`, then add the
**NipostPostcodeWidget** product to your app target.

The first release is pending; the URL above is where it will be published. The
SDK is developed privately and distributed from that repository as a compiled
framework.

## Usage

```swift theme={null}
import NipostPostcodeWidget

PostcodeWidget.show(
  from: viewController,
  config: PostcodeWidgetConfig(
    publishableKey: "nipost_pk_live_…",
    identifierType: .email,
    prefilledIdentifier: nil
  )
) { selection in
  if let selection {
    print("picked \(selection.formatted)")
  }
}
```

An async variant returns the selection directly:

```swift theme={null}
let selection = await PostcodeWidget.show(from: viewController, config: config)
```

`show()` presents the widget flow — identity screen (replaced by a
confirm screen when `prefilledIdentifier` is set), saved postcodes, and the
map-based discover flow — and delivers the
[`PostcodeSelection`](/widget/overview#the-selection-payload), or `nil` if the
user closed without picking. `selection.toJSON()` produces exactly the wire
shape every other SDK delivers.

## Configuration

| Field                     | Notes                                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey`          | **Required.** Your `nipost_pk_…` key.                                                                                       |
| `identifierType`          | `.nin` or `.email`.                                                                                                         |
| `prefilledIdentifier`     | Locks the identity field and shows a confirm screen when set.                                                               |
| `environment`             | `.production` (default) or `.staging`. Keys are minted per environment — a `nipost_pk_test_…` key only resolves on staging. |
| `platformBaseUrlOverride` | A host outside the standard environments (local stack, preview deploy). Wins over `environment`.                            |
| `styleUrl`                | Override the map style for the discover flow.                                                                               |
| `theme`                   | `PostcodeWidgetTheme` overrides.                                                                                            |

The SDK requires iOS 15+ and brings its own UI, so any iOS app works.
Add `NSLocationWhenInUseUsageDescription` to your app's Info.plist for the
"Get Postcode on Map" discover flow — the widget requests location permission
itself at the moment of use.