iOS - Postcode

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. Pin Up to Next Major Version from 0.1.0, or in a Package.swift:

dependencies: [
    .package(url: "https://github.com/MilsatLtd/postcode-widget-swift", from: "0.1.0")
]

The SDK is developed privately and distributed from that repository as a compiled XCFramework, which is why the URL is not the SDK’s own repository.

Usage

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:

let selection = await PostcodeWidget.show(from: viewController, config: config)

show() presents the widget flow: the identity screen (replaced by a confirm screen when prefilledIdentifier is set), saved postcodes, and the map-based discover flow. It delivers the PostcodeSelection, 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, so 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.