Skip to main content

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​

  1. Load the plugin URL (https://plugin.pulpoar.com/vto/<project-key>) in a WebView.
  2. Inject the SDK after the page loads. It loads @pulpoar/plugin-sdk and registers the events you need.
  3. Receive events: each event handler posts a JSON message ({ event, payload }) to native code through the platform's JavaScript bridge.
  4. 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);
PlatformpostToNativeRun an action
iOS (WKWebView)window.webkit.messageHandlers.<name>.postMessage(...)webView.evaluateJavaScript(...)
Android (WebView)window.<InterfaceName>.<method>(...)webView.evaluateJavaScript(...)
React Nativewindow.ReactNativeWebView.postMessage(...)webViewRef.current.injectJavaScript(...)
Flutter<ChannelName>.postMessage(...)controller.runJavaScript(...)

Platform setup​

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\"])")

Things to handle in your app​

  • Go to Product: the plugin can't route inside your app. Listen to onGoToProduct and open the product screen yourself.
  • Add to Cart: listen to onAddToCart and 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.