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

# Web Content in Mobile App

> Embedding your own web content inside the Lobyco mobile app.

In this section we touch on requirements for custom web pages that will be displayed into your Lobyco mobile app as webviews.

## Overview

This page is important to read through to make sure your webpages that you want to embed will fit and ensure a great customer experience in your Lobyco app.

**Example: You want to embed your webpage that encourages your CST activities into your Lobyco White label app.**

Native Android and iOS apps occasionally load web screens in an embedded browser (WebView / WKWebView).\
Because these components are **not full desktop browsers** and inherit OS-level sandboxing, pages must be built with a stricter set of assumptions about storage, navigation, security and performance.\
The checklist below captures some basics for web pages that should be shown inside native apps.

## 1. Technical Constraints

### Storage

* localStorage & sessionStorage are limited (\~5 MB) and may be wiped by the OS when low on space.
* IndexedDB and Service Workers are **disabled** in our embedded views for security; plan accordingly.

### Cookies

* Only first-party cookies are guaranteed. Third-party cookies, including those set via iframes or redirects, are blocked.
* Keep cookie size ≤ 4 KB each; mobile networks amplify header bloat.

### JavaScript & DOM API

* Most ES2020 features are supported on current OS versions, but always transpile (target ES2019).
* No SharedArrayBuffer, WebRTC or WebUSB in the sandbox.

### Mixed content

* HTTPS is mandatory. Any http\:// asset silently fails.

### File download

Web-initiated downloads aren’t automatic in WebView/WKWebView not supported in Lobyco applications.\
A possible workaround is to configure the link to open in an external browser so the user can download the file from there.

### Camera

Working with the Camera requires extra configurations with permissions and is not supported in Lobyco applications.

### Audio playback

Autoplay is blocked in WebView (Android 8+) and WKWebView; play only after a user tap.\
Pause when the app backgrounds or page becomes hidden.\
WKWebView honors the iOS ringer switch—no sound in silent mode.\
Use playsinline on `<video>` if sound is needed without fullscreen.\
Stick to AAC/MP3 for widest support; large WebAudio pipelines may stutter on low-end devices.

## 2. UX & Design Considerations

### Responsive layout

* Always include `<meta name="viewport" content="width=device-width, initial-scale=1">`.
* Avoid fixed-width elements; test on narrow devices (≤320 dp).

### Navigation

* Provide an in-page back button or ensure the native back action (onPageFinished history) works.
* There is no address bar, refresh button when web page is embeded in the app.
* Keep navigation (redirects) that are possible from a web page tidy.

Example (**BAD**): PrivacyPolicy web page is embedded in the app, but it contains redirects that lead to the company's Facebook/Instagram page. Seeing that inside that app is weird. Such links should open in an external browser.

### Loading states

* Keep first render \< 1 s on 3G; show skeletons if longer.
* Avoid infinite spinners without timeout fallback.

### Gestures

* Prevent horizontal scroll bleed (overflow-x:hidden) to stop jitter with native swipe-back.

## 3. Performance Best-Practices

* Ship a **single, tree-shaken JS bundle** ≤200 kB gzipped.
* Lazy-load images with loading="lazy"; compress to WebP/AVIF.
* Disable heavy timers/animations while the tab is backgrounded (document.visibilityState).
* Cache GET requests via ETag / Cache-Control — the OS may flush cache unpredictably, so handle 0-byte cache misses gracefully.

## 4. Error handling

Pages must own their error UI. Implement a visible in-page state (retry/back) triggered by non-200 fetches or JS exceptions.\
When no web fallback exists, the host catches WebView `onReceivedError` / `WKNavigationDelegate didFail` events (HTTP ≥ 400, SSL, network, resource) and surfaces a native dialog with generic error message.

## 5. Security Checklist

* Enforce CSP: default-src 'self'; frame-ancestors 'none';
* Escape all user-supplied HTML; the app trusts this origin.
* Use CSRF tokens on state-changing POSTs even inside the app.
* Never embed external `<script>` without SRI hashes.
* Validate all data crossing the postMessage bridge.

## 6. Communicating with Native Code

### Redirect interception

When WebView redirects to an **HTTPS deep link** that matches our allow-list, the app intercepts and opens the equivalent native screen.

**Recognised patterns:**

* `tel:[phone_number]` - opens \[phone\_number] in native dial application;
* `mailto:[email]?subject=[subject]&body=[body]` - opens native email app with provided parameters;
* `geo:[lat,lng]` - opens native maps application with coordiantes;
* `https://[something].pdf` - URL leading to PDF files will be opened in the external browser.

Custom Redirect interception might be configured upon request.\
Example `callback://close` intercepted by mobile app and closes the screen with web page.

### Open external browser

Redirect to url with target=\_blank (`<a href="https://lobyco.com#blank" target="_blank">link</a>`) or js `window.open(url, '_blank')` will be intercepted by the application and redirected to the external system browser unless the URL is a whitelisted deep link.

### JS - Native Bridge

With extra development both web and mobile it is possible to configure JS-Native bridge to exchange information between web page and native applications.

```javascript theme={"system"}
export function jsToNative() {  
    if (isIOS()) {  
        window.webkit?.messageHandlers.fromJStoNative.postMessage({});  
    } else if (isAndroid()) {  
        window.webApp?.fromJStoNative();  
    }  
}
```

More information [Android](https://developer.android.com/develop/ui/views/layout/webapps/webview#BindingJavaScript) and [iOS](https://medium.com/john-lewis-software-engineering/ios-wkwebview-communication-using-javascript-and-swift-ee077e0127eb)

## 7. Authentication & Session Management

### Single-Sign-On (SSO)

Mobile application is using OAuth2 web flows for authentication.\
Web page might use the Lobyco authentication service and access user-related information from within the app.

### Login/logout flows

When user logs out in the mobile application, cookies and web storage are cleared, so no information is preserved between user sessions.

## 8 Testing & Debugging

* **Remote debugging**:
  * Android: chrome://inspect on desktop Chrome and choose mobile resolution (320px/414px) and check that all links, buttons, and forms work correctly
  * iOS: Safari → Develop → choose mobile resolution (320px/414px) or choose mobile device and check that links, buttons, and forms work correctly

<Warning>
  **IMPORTANT**: Because the iOS application uses WebKit for web page display, it is crucial that the web page works in Safari browser (which also uses WebKit).
</Warning>

* **Network throttling**: simulate 3G/Edge to catch timeouts.
* No blocking third-party scripts that degrade the experience.