WebView requirements
What a WebView has to support before an OmniLab experience will work inside your app.
Confirm these before your mobile team starts building. Each one fails in a way that looks like a broken experience, not a missing setting, which makes it expensive to find late.
The WebView itself
- JavaScript enabled. Nothing loads without it. It's off by default in a plain Android
WebView. - A current WebView component. Use the platform's standard component or a maintained wrapper. Old embedded browsers fail on animations and modern layout, usually with a blank screen rather than an error.
- Cookies and local storage allowed, including for the experience's domain. The experience uses them to remember a participant between screens. Blocking them makes someone appear signed out mid-journey.
- A full-screen or edge-to-edge container. A WebView in a short, fixed-height box crops games.
Permissions
Your app grants permissions, not OmniLab. The WebView must also pass the page's request on to the native prompt: declaring the permission in the app manifest isn't enough.
| The experience uses | Your app must provide |
|---|---|
| A QR code scan, such as in a treasure hunt | Camera access |
| A receipt upload, or a photo field in a form | A file picker, with the camera and the photo library |
| A location check, such as in a treasure hunt, an instant game or a self check-in | Location access |
| A booking's calendar file or ticket, or a photo to keep | A way to save a file the page creates itself: see Save downloads |
Test each one on a real device. Simulators grant permissions differently, and pass where a real phone fails.
Why sign-in works here
A WebView loads the experience as the page, not inside one, so the experience is first-party in that view. Cookies behave normally, and sessions persist. Passing a signed-in member through with fci needs nothing more than keeping the sign-in hosts in the view. It does need your customer identity system connected first: see Pass a known customer into an experience.
Sign-in briefly leaves the experience domain, through a sign-in address and your identity provider. Keep those pages inside the WebView. A guard that sends them to the phone's browser breaks sign-in: see Build the WebView.
Don't build an HTML page of your own inside the WebView with the experience in a frame. That recreates the third-party problem a plain WebView avoids, and sign-in stops working. Point the WebView straight at the experience address.
Keyboard and forms
If the experience has a form or a sign-in step, check the keyboard doesn't cover the field being typed in, and that the view scrolls to keep it visible. It's the most common WebView defect, and it costs you the sign-up.
Session and navigation
- Decide what your back control does mid-experience. Leaving halfway should be deliberate, not accidental.
- Check the experience survives the app going into the background and coming back.
- Check a lost connection leaves the participant something they can recover from.
Screen sizes
Test the smallest phone you support and the largest tablet. Test both orientations if your app allows rotation.