The webview contract

A page opened inside an Appbrew app is a normal web page with two differences: the app injects a bridge into it before it runs, and the app intercepts some of its navigation. This page describes both, so you can predict what your page will do in-app without guessing.

If you only want to call the app, use the Web SDK. What follows is the layer underneath it, worth reading when something does not behave the way the SDK docs suggest.

The bridge

The app defines one global on your page:

window.appbrew = {
  postMessage: function (data) {
    /* hands `data` to the app */
  },
}

That is the entire surface. There is no callback, no promise, no version field, and no way to ask the app what it supports. The Web SDK builds everything else on top of this one method.

Its presence is the only reliable signal that your page is running in-app:

if (typeof window.appbrew !== 'undefined') {
  // in-app
}

The envelope

Every message you send takes the same shape:

{
  action: string                        // what you want the app to do
  payload: Record<string, any> | any[]  // arguments for that action
  actionId?: string                     // your correlation id, echoed back on replies
}

The app parses it, switches on action, and ignores anything it does not recognise. An unknown action produces no error and no reply.

How replies come back

Two actions reply. The app answers by broadcasting a message event on your page, not by calling you back:

window.addEventListener('message', (event) => {
  if (event.data.action === 'GET_USER_DETAILS_SUCCESS' && event.data.actionId === myId) {
    // event.data.payload
  }
})

Three consequences follow, and each of them explains a class of bug:

• You must match on actionId yourself. Replies are broadcast, not routed. Two concurrent calls to the same action are told apart only by the id you sent.
• Any script on the page can read the reply. A message listener installed by a third-party script sees the payload too. This matters most for the customer access token.
• Failure is silence. The app never sends an error. When something goes wrong it simply does not reply, and your only signal is a timeout you implement yourself. The Web SDK waits five seconds and then resolves with { status: 'error' }.

Actions the app accepts

The Web SDK wraps the first five. To use the last three, post to the bridge directly:

window.appbrew.postMessage({
  action: 'SHOW_TOAST',
  payload: { kind: 'success', message: 'Saved', duration: 2000 },
  actionId: 'toast-1',
})

ADD_TO_CART_SUCCESS is weaker than its name. The app replies once it has finished handling the request, so an error thrown on the app side still comes back as a success. A rejected or out-of-stock variant produces no reply at all. Neither outcome tells you what is in the cart, so read the cart back.

The user agent

The app sets a user agent containing Appbrew/<appname>/<ios|android>/<build>, where <appname> is lowercased with spaces removed and <build> is the build number, for example Appbrew/acmestore/android/412.

The user agent reaches your server on the first request, which makes it the only in-app signal available before any JavaScript runs.

Navigation the app takes over

Some paths never load in your page. The app matches them and pushes a native screen instead:

So a product link in your page usually opens the native product detail screen, not your PDP. That is usually what you want. When it is not, route around it: link somewhere that does not match these patterns, or take over the click and call gotoLink yourself.

Links to other hosts open according to how the app is configured, which may be the in-app browser or the device browser. A page opened in the device browser has no bridge.

Settings that change your page

A web-view block carries a few settings that affect what your page sees. Merchants set them in Studio or through app config, not from the page.

Version gates

The bridge grows by adding actions, and older apps drop actions they do not know. A page calling a newer action against an older app gets a five-second hang and then a timeout, with nothing in the console.

• GET_USER_DETAILS is available on 0.26.0 and later. On 0.25 and earlier the action is dropped.
• On 0.26 and earlier, an iOS page in an app running the Appbrew native webview, inside a block that sets hideElements, may find window.appbrew missing altogether: applying the selectors tore the bridge down. Fixed on 0.27.0. Apps on the other webview were never affected. If you support older builds and your block hides elements, check for the bridge on every call rather than once at load.

There is no capability handshake, so a page cannot ask the app what it supports. Write for the oldest app version you still serve, and treat a timeout as "this app is too old" rather than as an error worth showing the shopper.

Calling the bridge without the SDK

The Web SDK is a convenience, not a requirement. This is a complete getUserDetails in about twenty lines, if you would rather not add the script tag:

function getUserDetails(timeoutMs = 5000) {
  if (!window.appbrew) return Promise.resolve(null)

  return new Promise((resolve) => {
    const actionId = String(Date.now()) + Math.random()

    const onMessage = (event) => {
      if (
        event.data?.action === 'GET_USER_DETAILS_SUCCESS' &&
        event.data.actionId === actionId
      ) {
        clearTimeout(timer)
        window.removeEventListener('message', onMessage)
        resolve(event.data.payload)
      }
    }

    const timer = setTimeout(() => {
      window.removeEventListener('message', onMessage)
      resolve({ status: 'error', message: 'Timed out' })
    }, timeoutMs)

    window.addEventListener('message', onMessage)
    window.appbrew.postMessage({ action: 'GET_USER_DETAILS', payload: {}, actionId })
  })
}

Remove the listener on both paths. A listener left behind after a timeout fires on the next reply and resolves nothing.