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

# Mobile App Integration

> Integrate Hopae Connect into native mobile apps and existing IDV SDKs using an API-first architecture.

Hopae Connect is API-first. If your product already ships an iOS, Android, React Native, or Expo SDK, keep that client experience and call Hopae Connect through your backend.

<Info>
  Hopae does not publish a separate mobile SDK. The [Expo repository](https://github.com/hopae-official/hconnect-expo-sdk) is a reference example, not an SDK contract. Use the Hopae Connect API reference as the source of truth.
</Info>

## Recommended architecture

For an embedded IDV experience, use this boundary:

```mermaid theme={null}
sequenceDiagram
    participant App as Your mobile app or SDK
    participant Backend as Your backend
    participant Hopae as Hopae Connect API (/connect/v2)
    participant Wallet as Browser, wallet, or OS credential UI

    App->>Backend: Start verification
    Backend->>Hopae: POST /verifications (connectionId, userInput)
    Hopae-->>Backend: verificationId + flowType + flowDetails
    Backend-->>App: Short-lived flow data
    App->>Wallet: Launch the required user interaction
    Wallet-->>App: Return via callback URL
    App->>Backend: Resume session
    Backend->>Hopae: GET /verifications/{id} (poll), then /userinfo
    Hopae-->>Backend: Verified user data and provenance
    Backend-->>App: Application result
```

Your mobile app or SDK owns the user experience. Your backend owns the App ID and App Secret, lists connections, creates and polls verification sessions, and retrieves verified data.

<Warning>
  Never embed the App Secret in a mobile binary, JavaScript bundle, browser storage, or public repository.
</Warning>

### Hosted OIDC alternative

You can also start the [hosted OIDC flow](/v2/guides/oidc-integration) from a native app. Use a platform browser session such as `ASWebAuthenticationSession` on iOS or a Custom Tab on Android against `https://connect.hopae.com/v2/auth`, then return to your app through a registered callback URI. Register the app's custom scheme in its Redirect URL Allowlist. Avoid embedded WebViews for authentication: several providers (BankID Sweden, AusweisApp, Google Wallet credentials, …) cannot run inside one.

## Choose your application boundary

An Application is a relying-party and configuration boundary. It does not have to map one-to-one to a platform or legal entity. Each application is either sandbox or production, with its own configuration and credentials. See [Apps & Environments](/v2/guides/concepts/apps).

Create separate Web and Mobile Applications when they need different:

* App Secrets or redirect URIs
* workflows or enabled connections
* security or data-access boundaries
* Sandbox and production rollout schedules
* operational owners or analytics
* legal-entity or relying-party registrations

Web, iOS, and Android can share one Application when those settings and responsibilities are genuinely the same. Split iOS and Android as well when their platform support, workflow, or release schedule differs.

## Handle mobile flow types

Your backend returns `flowType` and `flowDetails` from [Create Verification](/v2/api-reference/verifications/create-verification). Your app performs the user-facing action.

| `flowType` | Mobile handling |
| - | - |
| `redirect` (or hosted OIDC) | Open `flowDetails.authorizationUrl` in a secure system browser session and resume the app through an allowlisted callback URI. |
| `qr` | On the same device, open `flowDetails.linkData`. It launches the eID app and returns the user. Use `qrData` only for cross-device journeys (a QR rendered on another screen). |
| `push` | Show `flowDetails.verificationCode` and a waiting state while your backend polls. Handle cancellation and expiry. |
| `query` | Nothing on the device. The create response is already `completed` or `failed`. Your backend fetches `userinfo`. |
| `dc` (digital credential) | Open `flowDetails.linkData` in the **system browser** (Chrome 141+ on Android, Safari 26+ on iOS) with `&return_url=<your https URL>` appended. The hosted page invokes the wallet through the Digital Credentials API, submits the response to Hopae, and redirects to `return_url`. The Digital Credentials API is not available inside WebViews. |

Full responses for each flow type: [Flow Types](/v2/guides/reference/flow-types).

<Note>
  Availability depends on the connection, platform, and app environment. Confirm the complete combination in Sandbox before a billable production test.
</Note>

## Same-device journeys

A QR displayed on a phone cannot be scanned by that same phone. Design a separate same-device path:

1. Detect that the verification started on a mobile device.
2. Use `flowDetails.linkData` (QR and DC flows) or `authorizationUrl` (redirect flows) instead of rendering a QR.
3. Preserve the `verificationId` before leaving your app.
4. Resume through an allowlisted callback and reject mismatched or replayed state.
5. Offer a cross-device fallback (render `qrData`) when the user is on a device without the eID app.

Do not transform `qrData` into a link yourself. `linkData` is the supported same-device entry point.

## Existing SDKs and JavaScript

If you already expose an IDV SDK, it can call your API exactly as it does for your other verification methods. Your API then calls Hopae Connect. You do not need to embed a Hopae client library in the mobile SDK.

A pure JavaScript wrapper can reduce HTTP and redirect boilerplate, but it cannot replace native platform APIs in every iOS and Android flow. Treat JavaScript and Expo code as examples around the API contract, with small platform adapters where a system browser or OS credential UI is required.

## Network connectivity

Hopae Connect is an online identity-verification and orchestration service. A verification requires network connectivity to create or resume the session, coordinate the flow, validate or submit the result, and return normalized evidence.

Some underlying digital credentials can support offline or proximity presentation. That capability does not make the Hopae Connect service offline. Offline verification is outside the current product scope.

## Mobile testing checklist

Test each required connection on every supported platform and app environment.

* Use physical devices for wallet, NFC, camera, app-link, and biometric behavior.
* Test both same-device and cross-device journeys.
* Test cancellation, timeout (30-minute session TTL), missing credential, app backgrounding, and process restart.
* Confirm callback and universal/app-link routing for every release build, and that the callback scheme is allowlisted per app.
* Verify that no secret or sensitive response is logged by the app.
* Complete a controlled, billable production test before launch. See [Go Live](/v2/guides/getting-started/go-live).

## Troubleshooting information

When asking Hopae for help, include:

* Application (App ID/client ID) and environment (sandbox / production)
* `connectionId` and `connectionInstanceId`
* iOS or Android version and device model
* your app version
* `verificationId` and timestamp
* integration method and observed `flowType`
* sanitized error (`error.code`, `request_id`) and relevant callback details

Do not send the App Secret, API keys, private test credentials, or unredacted personal data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.