WebView integration
You can run the VTO web plugin inside your mobile app with a WebView. This gives you the full web experience on iOS, Android, React Native and Flutter, with no native SDK.
Complete example apps: Swift · Kotlin · React Native
How it works
- Load the plugin URL (
https://plugin.pulpoar.com/vto/<project-key>) in a WebView. - Inject the SDK after the page loads. It loads
@pulpoar/plugin-sdkand registers the events you need. - Receive events: each event handler posts a JSON message (
{ event, payload }) to native code through the platform's JavaScript bridge. - Send actions: native code runs JavaScript in the WebView, for example
pulpoar.setPath("choose-model").
┌──────────────────────┐ evaluate JS: pulpoar.applyVariants([...]) ┌─────────────────────────┐
│ Native app │ ──────────────────────────────────────────▶ │ WebView │
│ (Swift / Kotlin / │ │ plugin.pulpoar.com │
│ RN / Flutter) │ ◀────────────────────────────────────────── │ + @pulpoar/plugin-sdk │
└──────────────────────┘ postMessage({ event, payload }) └─────────────────────────┘
The injected script looks like this on every platform. Only the bridge call (postToNative) changes:
const script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js';
script.onload = function () {
['onReady', 'onAddToCart', 'onGoToProduct', 'onPathChange'].forEach(function (event) {
pulpoar[event](function (payload) {
postToNative(JSON.stringify({ event: event, payload: payload }));
});
});
};
document.body.appendChild(script);
| Platform | postToNative | Run an action |
|---|---|---|
| iOS (WKWebView) | window.webkit.messageHandlers.<name>.postMessage(...) | webView.evaluateJavaScript(...) |
| Android (WebView) | window.<InterfaceName>.<method>(...) | webView.evaluateJavaScript(...) |
| React Native | window.ReactNativeWebView.postMessage(...) | webViewRef.current.injectJavaScript(...) |
| Flutter | <ChannelName>.postMessage(...) | controller.runJavaScript(...) |
Platform setup
- iOS (Swift)
- Android (Kotlin)
- React Native
- Flutter
1. Camera permission: add this to Info.plist:
<key>NSCameraUsageDescription</key>
<string>The camera shows you wearing the products.</string>
2. Configure the WebView: allow inline camera playback and register a message handler:
import WebKit
let contentController = WKUserContentController()
contentController.add(self, name: "eventHandler") // self: WKScriptMessageHandler
let config = WKWebViewConfiguration()
config.userContentController = contentController
config.allowsInlineMediaPlayback = true
config.mediaTypesRequiringUserActionForPlayback = []
let webView = WKWebView(frame: .zero, configuration: config)
webView.navigationDelegate = self
webView.load(URLRequest(url: URL(string: "https://plugin.pulpoar.com/vto/<project-key>")!))
3. Inject the SDK when the page loads:
func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
let events = ["onReady", "onAddToCart", "onGoToProduct", "onPathChange"]
let handlers = events.map { name in
"""
pulpoar['\(name)'](function (payload) {
window.webkit.messageHandlers.eventHandler.postMessage({ event: '\(name)', data: payload });
});
"""
}.joined(separator: "\n")
let script = """
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js';
s.onload = function () { \(handlers) };
document.body.appendChild(s);
"""
webView.evaluateJavaScript(script)
}
4. Receive events and send actions:
func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
guard let body = message.body as? [String: Any], let event = body["event"] as? String else { return }
switch event {
case "onAddToCart": print("Add to cart:", body["data"] ?? "")
case "onGoToProduct": print("Open product:", body["data"] ?? "") // route inside your app
default: break
}
}
// Actions
webView.evaluateJavaScript("pulpoar.setPath(\"choose-model\")")
webView.evaluateJavaScript("pulpoar.applyVariants([\"lipstick-red\"])")
1. Permissions: add these to AndroidManifest.xml:
<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
2. Configure the WebView: enable JavaScript and media playback, add a JavaScript interface, and grant camera requests once the user allows the permission:
webView.settings.apply {
javaScriptEnabled = true
domStorageEnabled = true
mediaPlaybackRequiresUserGesture = false
}
webView.addJavascriptInterface(SDKInterface(), "AndroidInterface")
webView.webChromeClient = object : WebChromeClient() {
override fun onPermissionRequest(request: PermissionRequest) {
// Request android.permission.CAMERA at runtime first, then:
request.grant(request.resources)
}
}
webView.webViewClient = object : WebViewClient() {
override fun onPageFinished(view: WebView?, url: String?) {
webView.evaluateJavascript(initialSdkScript(listOf("onReady", "onAddToCart", "onGoToProduct")), null)
}
}
webView.loadUrl("https://plugin.pulpoar.com/vto/<project-key>")
3. Build the injected script:
fun initialSdkScript(events: List<String>): String {
val handlers = events.joinToString("\n") { name ->
"pulpoar['$name'](function (payload) { window.AndroidInterface.$name(JSON.stringify(payload ?? null)); });"
}
return """
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js';
s.onload = function () { $handlers };
document.body.appendChild(s);
""".trimIndent()
}
4. Receive events and send actions:
class SDKInterface {
@JavascriptInterface
fun onReady(payload: String) { Log.d("PulpoAR", "Ready: $payload") }
@JavascriptInterface
fun onAddToCart(payload: String) { Log.d("PulpoAR", "Add to cart: $payload") }
@JavascriptInterface
fun onGoToProduct(payload: String) { /* route to the product screen */ }
}
// Actions
webView.evaluateJavascript("pulpoar.setPath(\"choose-model\")", null)
webView.evaluateJavascript("pulpoar.applyVariants([\"lipstick-red\"])", null)
@JavascriptInterface methods run on a background thread. Switch to the main thread before updating the UI.
1. Install react-native-webview and add camera permissions:
- iOS
Info.plist:NSCameraUsageDescription - Android
AndroidManifest.xml:<uses-permission android:name="android.permission.CAMERA" />
2. Use the WebView with an injected script:
import React, { useRef } from 'react';
import { WebView } from 'react-native-webview';
const EVENTS = ['onReady', 'onAddToCart', 'onGoToProduct', 'onPathChange'];
const injectedSdk = `
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js';
s.onload = function () {
${EVENTS.map(
(name) => `pulpoar['${name}'](function (payload) {
window.ReactNativeWebView.postMessage(JSON.stringify({ event: '${name}', payload: payload }));
});`
).join('\n')}
};
document.body.appendChild(s);
true;
`;
export function PulpoAR() {
const webViewRef = useRef<WebView>(null);
const setPath = (path: string) =>
webViewRef.current?.injectJavaScript(`pulpoar.setPath("${path}"); true;`);
return (
<WebView
ref={webViewRef}
source={{ uri: 'https://plugin.pulpoar.com/vto/<project-key>' }}
allowsInlineMediaPlayback
mediaPlaybackRequiresUserAction={false}
injectedJavaScript={injectedSdk}
onMessage={(e) => {
const { event, payload } = JSON.parse(e.nativeEvent.data);
if (event === 'onAddToCart') console.log('Add to cart', payload);
if (event === 'onGoToProduct') console.log('Open product', payload);
}}
/>
);
}
The React Native example includes a ready-to-copy PulpoAR component with typed events and an actionsRef.
1. Add packages: webview_flutter, webview_flutter_android, webview_flutter_wkwebview and permission_handler. Then add camera permissions:
- iOS
Info.plist:NSCameraUsageDescription - Android
AndroidManifest.xml:INTERNETandCAMERA
2. Create the controller:
late final WebViewController controller;
PlatformWebViewControllerCreationParams params = const PlatformWebViewControllerCreationParams();
if (WebViewPlatform.instance is WebKitWebViewPlatform) {
params = WebKitWebViewControllerCreationParams(
allowsInlineMediaPlayback: true,
mediaTypesRequiringUserAction: const <PlaybackMediaTypes>{},
);
}
controller = WebViewController.fromPlatformCreationParams(params)
..setJavaScriptMode(JavaScriptMode.unrestricted)
..addJavaScriptChannel('PulpoAR', onMessageReceived: (message) {
final data = jsonDecode(message.message);
debugPrint('Event ${data['event']}: ${data['payload']}');
})
..setNavigationDelegate(NavigationDelegate(
onPageFinished: (_) => controller.runJavaScript(injectedSdk),
));
// Android: grant the WebView camera request after the native permission
final platform = controller.platform;
if (platform is AndroidWebViewController) {
platform.setMediaPlaybackRequiresUserGesture(false);
platform.setOnPlatformPermissionRequest((request) async {
final status = await Permission.camera.request();
status.isGranted ? request.grant() : request.deny();
});
}
await controller.loadRequest(Uri.parse('https://plugin.pulpoar.com/vto/<project-key>'));
3. Injected script and actions:
const injectedSdk = '''
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js';
s.onload = function () {
['onReady', 'onAddToCart', 'onGoToProduct'].forEach(function (name) {
pulpoar[name](function (payload) {
PulpoAR.postMessage(JSON.stringify({ event: name, payload: payload }));
});
});
};
document.body.appendChild(s);
''';
// Actions
controller.runJavaScript('pulpoar.setPath("choose-model")');
Things to handle in your app
- Go to Product: the plugin can't route inside your app. Listen to
onGoToProductand open the product screen yourself. - Add to Cart: listen to
onAddToCartand add the variants to your native cart. - Size: show the WebView full screen, or in a full-height sheet, so the plugin gets enough space. See Layout and dimensions.
- Camera on a real device: simulators and emulators have limited or no camera support.
- Physical back button (Android): decide whether it should close the try-on or navigate back inside the WebView.
Available actions and events
All SDK actions and events work through the bridge. To call an action, run pulpoar.<action>(...) in the WebView. To receive an event, register it in the injected script.