This guide provides comprehensive instructions for integrating Sovendus Voucher Network and Checkout Benefits into native mobile applications using WebView components.
🏗️ Architecture
The Sovendus integration consists of:
Data Models - Customer and order data structures
HTML Generation - Dynamic HTML content with embedded JavaScript
WebView Integration - Displaying the HTML content in a WebView
JavaScript Bridge - Communication between WebView and native code
URL Handling - Opening external URLs in native browser
Error Handling - Logging errors to your application's logging system
Data Flow
Order Data → HTML Generation → WebView → JavaScript Bridge → Native Actions
Replace the placeholder values (integration data, order data and customer data) in the script with actual data from your order form, database, etc.
Consent Management
In particular, the hasConsent parameter is critical for GDPR and privacy compliance. This parameter allows the user's provided level of consent to easily be transferred to the Sovendus integration. Sovendus will then tailor functionality accordingly, as below
Please Note
This hasConsent parameter is only relevant for partners who have signed a Data Processing Agreement with Sovendus - if you are unsure, or have any queries, please reach out to your Customer Success Manager
Scenario
Value
Description
✔ Consent has been explicitly provided
hasConsent
=
true
The Sovendus integration loads successfully with full functionality, such as additional analytics, user recognition and personalisation of offers
✘ Consent has not been explicitly provided
hasConsent
=
false
The Sovendus integration loads successfully, but with minimal usage data (anonymised)
The exact method you use to determine/pass this value will depend on your particular Consent Management Platform and processes. In any case, please ensure this is passed as a Boolean (true or false).
Parameter Documentation
For detailed information on all parameters, examples, and requirements, visit: Parameter Documentation
3. Navigation Suppression and URL Handling
All navigation requests within the WebView MUST be suppressed
to prevent external links from opening within the WebView. Instead, use the post message bridge to handle URL opening in the native browser.
Required Implementation:
Suppress Navigation: Configure your WebView to prevent all navigation requests
Post Message Bridge: Implement JavaScript message handling to catch URL opening requests
window.sovApi="v1";// Post Message Bridge: Handle URL opening requests from Sovendus content// This prevents navigation within the WebView and opens URLs in native browserwindow.addEventListener("message",(event)=>{if(event.
Platform-Specific Navigation Suppression:
iOS (WKWebView): Return .cancel in decidePolicyFor navigationAction
Android (WebView): Return true in shouldOverrideUrlLoading()
Other platforms: Use equivalent navigation prevention methods
4. Implement Dynamic Height Adjustment
Dynamic Height Management Required:
The WebView height must dynamically adjust based on content size to provide optimal user experience.
Standard Implementation:
// Height Management: Monitor content size changes and notify native codenewResizeObserver(()=>{const height =document.body.scrollHeight;// Send height to native code for component resizing// Implementation depends on your platform's JavaScript bridgeconsole.log
Implementation Notes:
Only apply height updates > 100px to avoid layout issues
Ensure your JavaScript bridge properly handles height update messages
5. Add Input Sanitization
Security Requirement
Always sanitize user input data before inserting it into the HTML template to prevent XSS attacks. Use JSON encoding for all string values.
6. Implement Error Handling
Add comprehensive error handling for:
WebView loading failures
JavaScript execution errors
Network connectivity issues
Invalid parameter values
🔧 Key Implementation Requirements
Navigation Suppression
All navigation requests within the WebView MUST be suppressed
to prevent external links from opening within the WebView. Configure your WebView to cancel/prevent all navigation attempts and handle URLs via the post message bridge instead.
Post Message Bridge for URL Handling
URL Opening Pattern:
The integration uses a post message bridge to handle URL opening:
Sovendus content sends messages via window.postMessage() with channel "sovendus:integration"
JavaScript listener catches these messages and forwards them to native code
Native code receives the message and opens the URL in the default browser
Dynamic Height Management
Height Adjustment Pattern:
The WebView height must dynamically adjust based on content:
ResizeObserver monitors changes to document.body.scrollHeight
Height changes are sent to native code via your platform's JavaScript bridge
Native code updates the component height and triggers layout update
Only heights > 100px should be applied to avoid layout issues
🔧 Implementation Features
Security
XSS Prevention: All user input must be properly sanitized
Content Security: Restrict WebView navigation and file access
Error Handling: Implement proper error logging to your application's logging system
Performance
Memory Management: Properly dispose of WebView resources
