Mobile & Native Apps
You can put your configurator inside an iOS, Android, React Native or Flutter app today, with no changes to your project. There are two approaches: embed the published configurator in a web view, or build native interface around it.
Option A — Embed the configurator
- 1Publish the project and copy the share URL (see Sharing & Embedding).
- 2Load that URL in a web view: WKWebView on iOS, WebView on Android, react-native-webview, or webview_flutter.
- 3Enable DOM storage. On Android this is OFF by default and the configurator will not render without it.
- 4Leave hardware acceleration enabled so WebGL works — the 3D view has no software fallback.
- 5Handle the AR hand-off (below) and confirm on a physical device.
Web view settings
| Setting | Needed for | What to do |
|---|---|---|
| DOM storage | Theme, language and interface state | Required. Android defaults to off — set domStorageEnabled = true, or the page fails to render. |
| Hardware acceleration | All 3D rendering (WebGL) | Required. Ensure android:hardwareAccelerated is not disabled in your manifest. |
| File chooser | Projects with artwork or image upload options | Android only — implement WebChromeClient.onShowFileChooser, or the upload button does nothing. |
| Camera permission | Wearable AR (face, wrist, body try-on) only | Not needed for standard "place in your room" AR. The prompt appears when the shopper opens AR, not at launch. |
intent:// URL in shouldOverrideUrlLoading and start the activity. On iOS, a raw WKWebView does not present AR Quick Look itself — intercept the navigation to the .usdz file and show a QLPreviewController. Neither path works in a simulator, so test on real hardware.Two more things to handle
| Situation | What to do |
|---|---|
| Checkout | Completing a configuration navigates to your Shopify or WooCommerce checkout. Decide whether that stays in the web view, opens a native screen, or opens the system browser. If your platform opens links in a new window, implement onCreateWindow on Android too. |
| Configurator unavailable | If the account behind the project is inactive, the server responds 402 and a branded "unavailable" card is shown. Leave it visible or show your own message — do not retry in a loop. |
Option B — Native interface around the configurator
Keep the web view for the 3D scene and option controls, and draw the surrounding interface natively — navigation, branding, your call to action, cart, account and analytics. The configurator broadcasts three events your app can subscribe to by injecting a small listener script and forwarding to a native bridge (WKScriptMessageHandler on iOS, @JavascriptInterface on Android, onMessage in React Native).
| Event | Fires when | Payload |
|---|---|---|
| simplio3d:option.changed | A shopper changes a selectable option | blockId, blockName, value, label, type |
| simplio3d:form.submitted | An enquiry form is submitted successfully | requestId, formData |
| simplio3d:quote.submitted | Same moment — a semantic alias | requestId, formData |
form.submitted and quote.submitted fire together on the same submission — subscribe to one, or you will double-count. In option.changed, the shape of value depends on type: checkbox options report an array and number inputs report an object of named values, so switch on type rather than assuming a single value.
Embedding on a web page rather than in an app? You do not need to inject a listener at all — a Custom Script already runs inside the share-view document and can forward these same events to the page hosting your iframe with postMessage. See Sharing & Embedding → “Listening to the Configurator from Your Page” for a worked, origin-checked example.
?c=). Driving a selection into the configurator from native code, and event coverage for modular module placement, are not part of the supported interface yet — tell us if you need either and we will extend it.Which to choose
| Option A — Embed | Option B — Native shell | |
|---|---|---|
| Typical effort | 1–2 days | 1–3 weeks |
| 3D, options and pricing | Configurator | Configurator |
| Header, navigation, call to action | Configurator | Your app |
| Checkout and cart | Opens externally | Your app |
| Analytics and attribution | Web-side | Your app |
Option B builds on the same embed as Option A, so starting with A costs you nothing if you later want native chrome. For the underlying endpoints, see the API reference.