Hopae does not publish a mobile SDK. Use the Hopae Connect API reference as the source of truth.
Recommended architecture
For an embedded IDV experience, use this boundary: 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.Hosted OIDC alternative
You can also start the hosted OIDC flow from a native app. Openhttps://connect.hopae.com/v2/auth, and the user comes back on your redirect_uri, which must be on the app’s Redirect URL Allowlist. Keep the token exchange on your backend. A few connections don’t run in a WebView: see WebViews.
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. 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
Handle mobile flow types
Your backend returnsflowType and flowDetails from Create Verification. Your app performs the user-facing action.
Full responses for each flow type: Flow Types. Percent-encode your URL before you append it as
return_url, or its own query and fragment are lost.
Availability depends on the connection, platform, and app environment. Confirm the complete combination in Sandbox before a billable production test.
Same-device journeys
A QR displayed on a phone cannot be scanned by that same phone. Design a separate same-device path:- Detect that the verification started on a mobile device.
- Instead of rendering a QR code, open
flowDetails.authorizationUrl(redirect flows), the eID app fromflowDetails.qrData(QR flows), orflowDetails.linkData(DC flows). - Preserve the
verificationIdbefore leaving your app. - Resume when the user is back in your app, or on your
return_url,redirectUri, or OIDCredirect_uri. Match it to the verification you started, and read the result from your backend, not from the URL. - Offer a cross-device fallback (a QR code of
qrData; foredo-app,qrDatais already an image) when the user is on a device without the eID app.
WebViews
Some identity providers don’t allow their sign-in inside a WebView. If your app shows Hopae’s pages in a WebView, open these connections in a browser instead:
With hosted OIDC, the user selects the connection on Hopae’s page, which stays where you opened it. If your workflow has one of these connections, open
/v2/auth in the phone’s browser, or leave them out of the workflow you open in a WebView.
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 for OIDC, that each callback is on the app’s Redirect URL Allowlist.
- On iPad, Safari identifies as a Mac by default, so Hopae’s pages show the QR code for another device instead of opening the eID app. Test on iPad if you support it.
- Hopae Connect needs a network connection for the whole verification. There is no offline mode.
- Verify that no secret or sensitive response is logged by the app.
- Complete a controlled, billable production test before launch. See Go Live.
Troubleshooting information
When asking Hopae for help, include:- Application (App ID/client ID) and environment (sandbox / production)
connectionIdandconnectionInstanceId- iOS or Android version and device model
- your app version
verificationIdand timestamp- integration method and observed
flowType - sanitized error (
error.code,request_id) and relevant callback details

