Enable web checkout with the JS Bridge

Web checkout on your app is enabled by the Poq JS Bridge. This is a JavaScript snippet that, when added to your web-based checkout, opens up communication between your web page and the Poq app on your customer’s device.

The bridge allows data about your customer’s order to flow seamlessly and securely between the payment screens of your website and your app.

To complete this process you should also refer to the Poq Web Checkout API documentation for details on the transfer of data between your app and your website.

Outline of requirements

To enable web checkout, you need to complete the following steps:

1. Set up your checkout pages to support mobile view.
2. Ensure your website can identify requests from your Poq app.
3. Add a 'Continue Shopping' button to your web checkout screen that enables your customers to return to the app native screens once they have completed checkout.
4. Add the Poq JavaScript snippet to your web checkout pages. This includes setting up the API call to return transaction data to your app.
5. Test your implementation in debug mode.

Set up your checkout pages to support a mobile webview

To ensure your customers get a clean checkout experience, you need to ensure that the checkout screens:

• Can be displayed on mobile screen sizes
• Can display an 'Out of stock' warning if products in the customer's cart become unavailable during the checkout process.
• Do not display a header with your brand, logo, or navigation to other parts of your website.
• Do not display any other material that is not relevant to the checkout process.

Identify requests from your Poq app

To ensure your web checkout page opens and displays correctly, your Poq app will construct the request to the checkout page with an additional product identifier in the User-Agent header in the following format:

{App Name}-{Environment}/{App Version}

So the full User Agent header for the app PoqDemoApp-UAT/2.3 would look like this:

Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) PoqDemoApp-UAT/2.3

We recommend detecting this change on the server-side and changing the template or view used to render the web payment screens. You can also use JavaScript once the page has been loaded to hide elements if you are restricted.

if (Request.UserAgent.IndexOf("PoqDemoApp") > -1)
{
  // Use mobile webview template
}

Create a continue shopping button

Add a button allowing your customer to return to the native screens in your app, once they have completed checked out.

Integrate the Poq Web Checkout JavaScript into your website

To integrate the JS bridge into your checkout pages:

1. Add the following script before the </body> tag on your website’s checkout pages. This snippet must be loaded only once per page:

   <script>
       !function(p,o,q){var n=p.PoqWebCheckout={q:[]},i=["options","send","on","destroy"];function r(e,a){var n=o.createElement(q);q=o.getElementsByTagName(q)[0],n.src=["https://assets.poq.io/web-checkout",e,"min.js"].filter(function(e){return!!e}).join("."),n.async=1,n.crossOrigin="anonymous",a&&(n.integrity=a),q.parentNode.insertBefore(n,q)}function a(e){var a;return(null===(a=document.cookie.match("(^|;)\\s*".concat("poq.webcheckout."+e,"\\s*=\\s*([^;]+)")))||void 0===a?void 0:a.pop())||""}i.forEach(function(e){n[e]=function(){n.q.push([e,arguments])},n[i[0]]=function(e){e.debug&&r("",""),n.q.push([i[0],[e]])}}),p.poqWebCheckout={postMessage:function(e,a){"bridgesettings"===e&&(a=JSON.parse(a),n.q.push([i[0],[a]]),r(a.version,a.integrity))}};var c="{\"name\":\"ping\"}";p.android?p.android.postMessage(c):"ios"===a("platform")?r(a("version"),a("integrity")):p.webkit&&p.webkit.messageHandlers.poqWebCheckout.postMessage(c)}(window,document,"script")
   </script>

2. When the checkout has been completed and the order has been placed, send the order to your Poq app in the following format:

   PoqWebCheckout.send('paymentcompleted', {
     order: {
       total: 13.0,
       orderId: '0776620100',
       subTotal: 10.0,
       delivery: 5.0,
       discount: 2.0,
       currency: 'GBP'
     }
   });

In this request, total is required, other fields are optional. See the Order schema in Poq Web Checkout API documentation for full details.

When the user wants to continue shopping, for example by tapping a button, close the WebView using:

PoqWebCheckout.send('closewebview');

Test your implementation

Poq will provide you with a development build of your app before you start implementing these changes. This will allow you to inspect the webview in web browser developer tools and debug the calls made between your web payment screens and the app.

Once you have the build and you are making the necessary changes to your website, you can test them by enabling debug mode and checking the console in Google Chrome for Android builds or Safari for iOS builds.

To set up and test using debuggable mode:

1. Talk to your contact at Poq to request a development version of your iOS or Android app.
2. Ensure you are working in the latest version of your browser, with developer tools enabled, when testing the debuggable app.
3. Enable the Poq JS bridge debug mode in your web view by adding this line of code below your Poq checkout bridge JS snippet: PoqWebCheckout.options({ debug: true });
4. Make sure your device with the debuggable version of your app is connected to your computer.
5. Open your browser’s developer console.
6. Go through the stages of checking out on the connected debuggable app.
7. Check the JavaScript console for log messages.

A typical JavaScript console log during the checkout process looks like this:

[PoqWebCheckout] Running in debug mode
[PoqWebCheckout] Setting order object: { ... }
[PoqWebCheckout] Sending event: paymentcompleted { order: { ... } }