Skip to main content
Hopae Connect is API-first. If your product already ships an iOS, Android, or React Native SDK, keep that client experience and call Hopae Connect through your backend.
Hopae does not publish a mobile SDK. Use the Hopae Connect API reference as the source of truth.
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.
Never embed the App Secret in a mobile binary, JavaScript bundle, browser storage, or public repository.

Hosted OIDC alternative

You can also start the hosted OIDC flow from a native app. Open https://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
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. 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:
  1. Detect that the verification started on a mobile device.
  2. Instead of rendering a QR code, open flowDetails.authorizationUrl (redirect flows), the eID app from flowDetails.qrData (QR flows), or flowDetails.linkData (DC flows).
  3. Preserve the verificationId before leaving your app.
  4. Resume when the user is back in your app, or on your return_url, redirectUri, or OIDC redirect_uri. Match it to the verification you started, and read the result from your backend, not from the URL.
  5. Offer a cross-device fallback (a QR code of qrData; for edo-app, qrData is already an image) when the user is on a device without the eID app.
Some eID apps don’t send the user back: the user switches back themselves. Keep polling, and update your screen when your app is in the foreground again.

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)
  • 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.