Native bridge (web ⇄ app)

Wait for the bridge

The app installs the client (window.WebToApp.call, .on, …) on every page and then fires a WebToAppBridgeReady event on window. In a regular browser none of this exists: window.WebToApp and window.FlutterWebView are undefined and the event never fires, so use a short timeout to decide that you are not in the app.

function whenBridgeReady(timeoutMs) {
  return new Promise(function (resolve) {
    if (window.WebToApp && typeof window.WebToApp.call === 'function') {
      resolve(true);                       // already installed
      return;
    }
    var timer = setTimeout(function () { resolve(false); }, timeoutMs || 1500);
    window.addEventListener('WebToAppBridgeReady', function () {
      clearTimeout(timer);
      resolve(true);
    }, { once: true });
  });
}

async function main() {
  if (!(await whenBridgeReady())) return;  // regular browser

  const info = await WebToApp.call('app.getInfo');
  // → { bridgeVersion: 2, platform: 'ios', capabilities: { purchases: true, paywalls: true, push: 'fcm', ads: false } }
}
main();

The WebToApp API

window.WebToApp already carries platform, isMobileApp(), getPlatform() and Compliance (see App Detection); the bridge adds the members above.

// Call with a custom timeout
const state = await WebToApp.call('app.getState', {}, { timeoutMs: 5000 });

// Subscribe, unsubscribe, one-shot, and read the last value
const off = WebToApp.on('app.background', function () { saveDraft(); });
off();                                                  // stop listening
WebToApp.once('app.foreground', function () { refreshSession(); });
const lastNetwork = WebToApp.last('network.changed');   // { online, connection } or undefined

// Debug: log everything the app sends
WebToApp.on('*', function (data, meta) { console.log(meta.name, data, meta.ts); });

How it travels

You normally never touch this: the injected client takes care of ids and timeouts. It is documented so you can debug what goes over the wire.

Methods

app.* methods always exist. purchases.* methods need the RevenueCat add-on enabled for that platform; otherwise they reject with not_enabled.

Offerings and CustomerInfo are described in the RevenueCat guide.

Events

Events are fire-and-forget and are not replayed. A handler added after an event fired will not see it. WebToApp.last(name) only covers events since the current page loaded, so on a fresh page ask for the state instead: app.getState or purchases.getCustomerInfo.

Errors

Every rejection carries a code (a snake_case string) and a message.

try {
  const info = await WebToApp.call('purchases.getCustomerInfo');
} catch (e) {
  if (e.code === 'not_enabled' || e.code === 'unsupported_method') {
    // RevenueCat is not set up for this build: hide the purchase UI
  } else if (e.code === 'timeout') {
    // the app did not answer in time
  } else {
    console.error(e.code, e.message);
  }
}

Worked example: a two-way flow

Your page asks the app for its state, then keeps itself in sync with what happens natively: refresh the session when the user comes back, react to a notification tap, reward a finished ad and show an offline banner. refreshSession, showOfflineBanner, trackEvent and grantCredits stand for your own code.

async function setupNativeBridge() {
  // 0. Inside the app? (a regular browser never gets the bridge)
  if (!(await whenBridgeReady(1500))) return;

  // 1. Web asks the app for its state
  const state = await WebToApp.call('app.getState');
  // → { lifecycle: 'foreground', online: true, connection: 'wifi' }
  showOfflineBanner(!state.online);

  // 2. App tells the web it is back in the foreground: refresh the session
  WebToApp.on('app.foreground', function () {
    refreshSession();
  });

  // 3. Connectivity changes while the app is open
  WebToApp.on('network.changed', function (data) {
    showOfflineBanner(!data.online);       // data = { online, connection }
  });

  // 4. The user tapped a notification. The app opens openUrl itself;
  //    use the event for analytics or to update the page you are on.
  WebToApp.on('push.opened', function (data) {
    // data = { provider, title, body, data, openUrl }
    trackEvent('push_opened', { provider: data.provider, title: data.title });
  });

  // 5. A rewarded ad finished: the web starts it, the app reports the reward
  WebToApp.on('ads.rewardEarned', function (reward) {
    grantCredits(reward.amount);           // reward = { amount, type }
  });
  document.getElementById('watch-ad').addEventListener('click', function () {
    window.FlutterWebView.postMessage(JSON.stringify({ type: 'showRewardedAd' }));
  });
}

setupNativeBridge();

This example uses whenBridgeReady from above. showRewardedAd needs the AdMob add-on with a rewarded ad unit, see the AdMob guide.