WebView

Add the Trustly UI to multi-platform apps with WebView

WebView

Add the Trustly UI to multi-platform apps with WebView

Trustly recommends using the Trustly iOS and Android SDKs to integrate the Trustly UI within mobile applications rather than WebView.

You can use a WebView to integrate the Lightbox in applications built with a multiplatform architecture and a web-based checkout flow.

For testing and learning, see the Trustly WebView Example application in GitHub.

If you need help with your integration, contact your Trustly representative or send your request to us.integrations@trustly.com.

Note: The Swift and Kotlin languages are shown as examples. For iOS and Android, see the example app repository.

Prerequisites

The mobile application rendering the WebView must have at least one universal or deep link configured to return customers from the OAuth login to the mobile application. To learn more about universal and deep links, see Defining a custom URL scheme for your app (iOS) and Create Deep Links to App Content (Android).

Use JavaScript to initialize and display the Trustly Lightbox in the web content loaded by your WebView.

If your web page containing the Lightbox serves both web browser users and mobile app users, the default Lightbox web browser behavior does not function when the integrationContext="InAppBrowser" property is included. Trustly recommends adding the metadata properties dynamically. See the Trustly WebView Example app for an example implementation.

To load the Trustly JavaScript library, add a script tag to the <head> section of the web page that will be loaded in the WebView. For example:

1 <html>
2   <head>
3     ...
4     <script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=%REACT_APP_TRUSTLY_ACCESS_ID%"></script>
5     <title>Trustly Starter App</title>
6   </head>
7     ...
8 </html>

Optional. In production environments, replace sandbox.trustly.one with trustly.one.
Replace REACT_APP_TRUSTLY_ACCESS_ID with your Trustly Access ID.

To initialize and launch the Lightbox, add a metadata object with the following properties to the establishData variable:

urlScheme - the URL you expect the user to return to after completing an OAuth or “App-to-App” user flow. For example,my_app://checkout/bank/oauth_success
integrationContext - one of InAppBrowser, InAppBrowserNotify, or ExternalBrowser. In order for OAuth to work in the manner described in this guide, the string InAppBrowser must be provided.

For example:

1 let establishData = {
2   accessId: 'YOUR_ACCESS_ID',
3   merchantId: 'YOUR_MERCHANT_ID',
4   ...
5   metadata: {
6     urlScheme: "YOUR_APP://SOME_RESOURCE",
7     integrationContext: "InAppBrowser",
8   }
9 };
10 
11 // define options if needed
12 let trustlyOptions = {};
13 
14 window.Trustly.establish(establishData, trustlyOptions)

Launch the WebView in your mobile app

Configure your app to to enable interaction between the WebView and the Lightbox web page. For example:

1 import Foundation
2 import UIKit
3 import WebKit
4 
5 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
6 
7   override func viewDidLoad() {
8    	super.viewDidLoad()
9         
10 		// replace this URL with the web page that is rendering the Trustly Lightbox (can be localhost for testing purposes)
11     let url = URL(string: "https://myapp.com/pay-with-Trustly")!
12     let reqApp = URLRequest(url: url);
13 
14     self.WebView = WKWebView(
15       frame: self.view.bounds,
16       configuration: self.getWKWebViewConfiguration()
17     )
18 
19     // allow navigation events in the WebView
20     WebView.navigationDelegate = self
21     WebView.uiDelegate = self
22 
23     // load and render the URL request defined above
24     WebView.load(reqApp)
25     self.view.addSubview(self.WebView)
26   }
27 
28 	// this function returns all the necessary configurations for Lightbox behavior
29 	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
30     let userController = WKUserContentController()
31     let configuration = WKWebViewConfiguration()
32     let wkPreferences = WKPreferences()
33     wkPreferences.javaScriptCanOpenWindowsAutomatically = true
34     configuration.preferences = wkPreferences
35     configuration.userContentController = userController
36     return configuration
37 	}
38 }

Kotlin

class WebViewClientActivity : AppCompatActivity() {
  
    lateinit var WebView: WebView
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_WebViewclient)
        WebView = findViewById(R.id.WebView)
        WebView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            javaScriptCanOpenWindowsAutomatically = true
        }
      
        WebView.loadUrl("https://myapp.com/pay-with-Trustly")
    }
  
}

When a user selects a bank requiring OAuth, the Trustly Lightbox uses window.open() to navigate to a Trustly-hosted URL. Since WebView cannot open new windows like a regular browser, your app must handle this navigation.

Within your WebView, add a function to check for window navigation events to the Trustly URL.

1 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
2 
3 	private var WebView: WKWebView!
4 
5 	override func viewDidLoad() {
6   	super.viewDidLoad()
7 		...
8     WebView.load(reqApp)
9     self.view.addSubview(self.WebView)
10   }
11 
12 	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
13     ...
14 	}
15 
16 	// this function will run on any navigation event that happens inside the WebView
17 	func WebView(_ WebView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
18     // Check that URL is external and expected	
19     if navigationAction.targetFrame == nil, let url = navigationAction.request.url {
20       if url.description.lowercased().range(of: "/step/oauth/login") != nil {
21         // this is where we will open the secure browser session
22       }
23     }
24     return nil
25 	}
26 }

Kotlin

class WebViewClientActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        
        WebView.WebViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                view: WebView,
                request: WebResourceRequest
            ): Boolean {
                val url = request.url.toString()
                if (url.contains("/step/oauth/login"))
                    launchUrl(this@WebViewClientActivity, url)
                return true
            }
        }
      
        WebView.loadUrl("https://myapp.com/pay-with-Trustly")
    }
  
}

Something went wrong!

Open the external link

Many banks consider WebViews an insecure method for accepting and authenticating user credentials. Following the completion of this step, when a customer opens the Trustly Lightbox and selects an OAuth-required bank, a secure in-app-browser layer opens over the Lightbox. This layer contains information about the selected bank and a button that a customer can select to authenticate with their bank’s mobile app or through the bank’s OAuth login web page. After a customer is successfully authenticated, they are directed back to your app.

For iOS, the secure in-app browser class ASWebAuthenticationSession is preferred. If you’re using iOS 12 or earlier, your app might need to support SFAuthenticationSession.

For Android, use Chrome Custom Tabs.

Add a function to open a secure in-app browser. For example:

1 import AuthenticationServices
2 
3 ...
4 
5 private var webSession: ASWebAuthenticationSession!
6 
7 ...
8 
9 private func buildASWebAuthenticationSession(url: URL, callbackURL: String){
10   webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL)
11   // add basic configurations
12   webSession.prefersEphemeralWebBrowserSession = true
13   // assign the ASWebAuthentication 
14   webSession.presentationContextProvider = self
15   webSession.start()
16 }

Kotlin

fun launchUrl(context: Context, url: String) {
    val customTabsIntent = CustomTabsIntent.Builder().build()
    customTabsIntent.intent.setPackage("com.android.chrome")
    customTabsIntent.launchUrl(context, Uri.parse(url))
}

The parameter callbackURL provides the destination to redirect the user to when the authentication session is complete. The value of this parameter must be identical to the urlScheme parameter that is passed into the establishData.metadata object when the Lightbox is launched.

Import the WebKit framework and display a web page for authentication. For example:

1 import WebKit
2 
3 ...
4 
5 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
6 
7   private var WebView: WKWebView!
8 
9   override func viewDidLoad() {
10     ...
11     WebView.load(URLRequest(url: URL(string: "YOUR_WEB_PAGE_WITH_TRUSTLY_JS")))
12   }
13 
14   func WebView(_ WebView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
15     // Check that URL is external and expected	
16     if navigationAction.targetFrame == nil, let url = navigationAction.request.url {
17       if url.description.lowercased().range(of: "http") != nil {
18         // OPEN THE EXTERNAL URL
19         if #available(iOS 13, *) {
20           self.buildASWebAuthenticationSession(url: url, callbackURL: "YOUR_APP://checkout/trustly/oauth_return")
21         } else {
22           // handle iOS <12 with SFAuthenticationSession
23         }
24       }
25     }
26     return nil
27   }
28 }

To complete the authentication process, you need to modify the buildASWebAuthenticationSession so that when the session is complete, the WebView calls the proceedToChooseAccount() method which is built in to the Trustly Lightbox. For example:

1 private func buildASWebAuthenticationSession(url: URL, callbackURL: String) {
2 	webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL, completionHandler: { (url, error) in
3 		// upon completion execute JavaScript function for Lightbox to proceed
4 	  self.WebView.evaluateJavaScript("window.Trustly.proceedToChooseAccount();", completionHandler: nil)
5                                                                                                        })
6  	webSession.prefersEphemeralWebBrowserSession = true
7   webSession.presentationContextProvider = self
8   webSession.start()
9 }

Kotlin

override fun onResume() {
  	super.onResume()
  	WebView.loadUrl("javascript:window.Trustly.proceedToChooseAccount();")
}

Trustly recommends using the Trustly iOS and Android SDKs to integrate the Trustly UI within mobile applications rather than WebView.

You can use a WebView to integrate the Lightbox in applications built with a multiplatform architecture and a web-based checkout flow.

For testing and learning, see the Trustly WebView Example application in GitHub.

If you need help with your integration, contact your Trustly representative or send your request to us.integrations@trustly.com.

Note: The Swift and Kotlin languages are shown as examples. For iOS and Android, see the example app repository.

Prerequisites

The mobile application rendering the WebView must have at least one universal or deep link configured to return customers from the OAuth login to the mobile application. To learn more about universal and deep links, see Defining a custom URL scheme for your app (iOS) and Create Deep Links to App Content (Android).

Use JavaScript to initialize and display the Trustly Lightbox in the web content loaded by your WebView.

To load the Trustly JavaScript library, add a script tag to the <head> section of the web page that will be loaded in the WebView. For example:

1 <html>
2   <head>
3     ...
4     <script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=%REACT_APP_TRUSTLY_ACCESS_ID%"></script>
5     <title>Trustly Starter App</title>
6   </head>
7     ...
8 </html>

Optional. In production environments, replace sandbox.trustly.one with trustly.one.
Replace REACT_APP_TRUSTLY_ACCESS_ID with your Trustly Access ID.

To initialize and launch the Lightbox, add a metadata object with the following properties to the establishData variable:

urlScheme - the URL you expect the user to return to after completing an OAuth or “App-to-App” user flow. For example,my_app://checkout/bank/oauth_success
integrationContext - one of InAppBrowser, InAppBrowserNotify, or ExternalBrowser. In order for OAuth to work in the manner described in this guide, the string InAppBrowser must be provided.

For example:

1 let establishData = {
2   accessId: 'YOUR_ACCESS_ID',
3   merchantId: 'YOUR_MERCHANT_ID',
4   ...
5   metadata: {
6     urlScheme: "YOUR_APP://SOME_RESOURCE",
7     integrationContext: "InAppBrowser",
8   }
9 };
10 
11 // define options if needed
12 let trustlyOptions = {};
13 
14 window.Trustly.establish(establishData, trustlyOptions)

Launch the WebView in your mobile app

Configure your app to to enable interaction between the WebView and the Lightbox web page. For example:

1 import Foundation
2 import UIKit
3 import WebKit
4 
5 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
6 
7   override func viewDidLoad() {
8    	super.viewDidLoad()
9         
10 		// replace this URL with the web page that is rendering the Trustly Lightbox (can be localhost for testing purposes)
11     let url = URL(string: "https://myapp.com/pay-with-Trustly")!
12     let reqApp = URLRequest(url: url);
13 
14     self.WebView = WKWebView(
15       frame: self.view.bounds,
16       configuration: self.getWKWebViewConfiguration()
17     )
18 
19     // allow navigation events in the WebView
20     WebView.navigationDelegate = self
21     WebView.uiDelegate = self
22 
23     // load and render the URL request defined above
24     WebView.load(reqApp)
25     self.view.addSubview(self.WebView)
26   }
27 
28 	// this function returns all the necessary configurations for Lightbox behavior
29 	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
30     let userController = WKUserContentController()
31     let configuration = WKWebViewConfiguration()
32     let wkPreferences = WKPreferences()
33     wkPreferences.javaScriptCanOpenWindowsAutomatically = true
34     configuration.preferences = wkPreferences
35     configuration.userContentController = userController
36     return configuration
37 	}
38 }

Kotlin

class WebViewClientActivity : AppCompatActivity() {
  
    lateinit var WebView: WebView
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_WebViewclient)
        WebView = findViewById(R.id.WebView)
        WebView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            javaScriptCanOpenWindowsAutomatically = true
        }
      
        WebView.loadUrl("https://myapp.com/pay-with-Trustly")
    }
  
}

Within your WebView, add a function to check for window navigation events to the Trustly URL.

1 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
2 
3 	private var WebView: WKWebView!
4 
5 	override func viewDidLoad() {
6   	super.viewDidLoad()
7 		...
8     WebView.load(reqApp)
9     self.view.addSubview(self.WebView)
10   }
11 
12 	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
13     ...
14 	}
15 
16 	// this function will run on any navigation event that happens inside the WebView
17 	func WebView(_ WebView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
18     // Check that URL is external and expected	
19     if navigationAction.targetFrame == nil, let url = navigationAction.request.url {
20       if url.description.lowercased().range(of: "/step/oauth/login") != nil {
21         // this is where we will open the secure browser session
22       }
23     }
24     return nil
25 	}
26 }

Kotlin

class WebViewClientActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        
        WebView.WebViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                view: WebView,
                request: WebResourceRequest
            ): Boolean {
                val url = request.url.toString()
                if (url.contains("/step/oauth/login"))
                    launchUrl(this@WebViewClientActivity, url)
                return true
            }
        }
      
        WebView.loadUrl("https://myapp.com/pay-with-Trustly")
    }
  
}

Something went wrong!

Open the external link

For iOS, the secure in-app browser class ASWebAuthenticationSession is preferred. If you’re using iOS 12 or earlier, your app might need to support SFAuthenticationSession.

For Android, use Chrome Custom Tabs.

Add a function to open a secure in-app browser. For example:

1 import AuthenticationServices
2 
3 ...
4 
5 private var webSession: ASWebAuthenticationSession!
6 
7 ...
8 
9 private func buildASWebAuthenticationSession(url: URL, callbackURL: String){
10   webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL)
11   // add basic configurations
12   webSession.prefersEphemeralWebBrowserSession = true
13   // assign the ASWebAuthentication 
14   webSession.presentationContextProvider = self
15   webSession.start()
16 }

Kotlin

fun launchUrl(context: Context, url: String) {
    val customTabsIntent = CustomTabsIntent.Builder().build()
    customTabsIntent.intent.setPackage("com.android.chrome")
    customTabsIntent.launchUrl(context, Uri.parse(url))
}

Import the WebKit framework and display a web page for authentication. For example:

1 import WebKit
2 
3 ...
4 
5 class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
6 
7   private var WebView: WKWebView!
8 
9   override func viewDidLoad() {
10     ...
11     WebView.load(URLRequest(url: URL(string: "YOUR_WEB_PAGE_WITH_TRUSTLY_JS")))
12   }
13 
14   func WebView(_ WebView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
15     // Check that URL is external and expected	
16     if navigationAction.targetFrame == nil, let url = navigationAction.request.url {
17       if url.description.lowercased().range(of: "http") != nil {
18         // OPEN THE EXTERNAL URL
19         if #available(iOS 13, *) {
20           self.buildASWebAuthenticationSession(url: url, callbackURL: "YOUR_APP://checkout/trustly/oauth_return")
21         } else {
22           // handle iOS <12 with SFAuthenticationSession
23         }
24       }
25     }
26     return nil
27   }
28 }

1 private func buildASWebAuthenticationSession(url: URL, callbackURL: String) {
2 	webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL, completionHandler: { (url, error) in
3 		// upon completion execute JavaScript function for Lightbox to proceed
4 	  self.WebView.evaluateJavaScript("window.Trustly.proceedToChooseAccount();", completionHandler: nil)
5                                                                                                        })
6  	webSession.prefersEphemeralWebBrowserSession = true
7   webSession.presentationContextProvider = self
8   webSession.start()
9 }

Kotlin

override fun onResume() {
  	super.onResume()
  	WebView.loadUrl("javascript:window.Trustly.proceedToChooseAccount();")
}

WebView

WebView

Prerequisites

Launch the WebView in your mobile app

Listen for navigation events

Open the external link

Prerequisites

Launch the WebView in your mobile app

Listen for navigation events

Open the external link

1	<html>
2	<head>
3	...
4	<script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=%REACT_APP_TRUSTLY_ACCESS_ID%"></script>
5	<title>Trustly Starter App</title>
6	</head>
7	...
8	</html>

1	let establishData = {
2	accessId: 'YOUR_ACCESS_ID',
3	merchantId: 'YOUR_MERCHANT_ID',
4	...
5	metadata: {
6	urlScheme: "YOUR_APP://SOME_RESOURCE",
7	integrationContext: "InAppBrowser",
8	}
9	};
10
11	// define options if needed
12	let trustlyOptions = {};
13
14	window.Trustly.establish(establishData, trustlyOptions)

1	import Foundation
2	import UIKit
3	import WebKit
4
5	class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
6
7	override func viewDidLoad() {
8	super.viewDidLoad()
9
10	// replace this URL with the web page that is rendering the Trustly Lightbox (can be localhost for testing purposes)
11	let url = URL(string: "https://myapp.com/pay-with-Trustly")!
12	let reqApp = URLRequest(url: url);
13
14	self.WebView = WKWebView(
15	frame: self.view.bounds,
16	configuration: self.getWKWebViewConfiguration()
17	)
18
19	// allow navigation events in the WebView
20	WebView.navigationDelegate = self
21	WebView.uiDelegate = self
22
23	// load and render the URL request defined above
24	WebView.load(reqApp)
25	self.view.addSubview(self.WebView)
26	}
27
28	// this function returns all the necessary configurations for Lightbox behavior
29	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
30	let userController = WKUserContentController()
31	let configuration = WKWebViewConfiguration()
32	let wkPreferences = WKPreferences()
33	wkPreferences.javaScriptCanOpenWindowsAutomatically = true
34	configuration.preferences = wkPreferences
35	configuration.userContentController = userController
36	return configuration
37	}
38	}

1	class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
2
3	private var WebView: WKWebView!
4
5	override func viewDidLoad() {
6	super.viewDidLoad()
7	...
8	WebView.load(reqApp)
9	self.view.addSubview(self.WebView)
10	}
11
12	private func getWKWebViewConfiguration() -> WKWebViewConfiguration {
13	...
14	}
15
16	// this function will run on any navigation event that happens inside the WebView
17	func WebView(_ WebView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
18	// Check that URL is external and expected
19	if navigationAction.targetFrame == nil, let url = navigationAction.request.url {
20	if url.description.lowercased().range(of: "/step/oauth/login") != nil {
21	// this is where we will open the secure browser session
22	}
23	}
24	return nil
25	}
26	}

1	import AuthenticationServices
2
3	...
4
5	private var webSession: ASWebAuthenticationSession!
6
7	...
8
9	private func buildASWebAuthenticationSession(url: URL, callbackURL: String){
10	webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL)
11	// add basic configurations
12	webSession.prefersEphemeralWebBrowserSession = true
13	// assign the ASWebAuthentication
14	webSession.presentationContextProvider = self
15	webSession.start()
16	}

1	private func buildASWebAuthenticationSession(url: URL, callbackURL: String) {
2	webSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURL, completionHandler: { (url, error) in
3	// upon completion execute JavaScript function for Lightbox to proceed
4	self.WebView.evaluateJavaScript("window.Trustly.proceedToChooseAccount();", completionHandler: nil)
5	})
6	webSession.prefersEphemeralWebBrowserSession = true
7	webSession.presentationContextProvider = self
8	webSession.start()
9	}

Prerequisites

Launch the Lightbox in a WebView

Launch the WebView in your mobile app

Listen for navigation events

Open the external link

Return to the Lightbox

Prerequisites

Launch the Lightbox in a WebView

Launch the WebView in your mobile app

Listen for navigation events

Open the external link

Return to the Lightbox