iOS
Quickstart guide for adding Trustly UI to native iOS apps
The Trustly Lightbox SDK for iOS allows you to quickly build a bank authorization workflow in your iOS app. Integrating the Select Bank Widget and/or the Trustly Lightbox provides a powerful user experience that results in bank authorization data which can be used with other Trustly APIs.
Example App
Prefer running an example project? Checkout our SwiftUI iOS Example App on Github.
Set Up
Requirements
Installation
Legacy Versions
v3 SDKs deprecated
PayWithMyBankreferences. If your app previously used version 2, take note and update these references toTrustlywhen upgrading to a v3 SDK.
CocoaPods
Add the Trustly package to your Podfile
pod 'TrustlySDK'
Swift Package Manager
With your project open in Xcode, choose File > Add Package Dependencies...
Search for "trustly-ios" or paste the package URL below into the search bar.
https://github.com/TrustlyInc/trustly-ios.git
Choose "Add Package"
Manual
Download the latest version from the Trustly iOS Github repository
Unzip the files
With your project open in Xcode, choose "File" > "Add files to..."
Select the TrustlySDK.xcframework file from the unzipped package and make sure that "copy items if needed" is checked.
OAuth Configuration
In order to support OAuth login flows, the Trustly Lightbox interacts with the ASWebAuthenticationSession class and in some cases it hands off to the user's mobile banking app directly. In order to support this functionality, you must have at least one url scheme configured in your Info.plist file.
Deep Link Required
If your app does not already have a defined deep link or URL scheme, you must define one. Without it, users will not be automatically redirected to your app after logging in on a mobile banking app.
More on this later, but the next steps will reference "your app's deep link".
Lightbox Integration
With the configurations above in place, you are ready to integrate the Trustly Lightbox into your iOS app.
Checklist
- Define Establish data with a
requestSignature- Display the Select Bank Widget
- Launch the Lightbox
- Handle Callback Events
Note: The examples provided in this guide are based on UIKit. A complete example app built on SwiftUI can be found on the Trustly Github.
Define Establish Data with a Request Signature
As the Trustly Lightbox SDK runs on the client, requests between it and the Trustly API must be secured. Calculate a requestSignature using your Access Key from your server and fetch it from your iOS app prior to rendering the Select Bank Widget or Trustly Lightbox.
See Securing Requests for more details on generating a requestSignature.
In addition to the requestSignature much of the other information in the establishData properties should be fetched or calculated dynamically, for example customer information or unique order identifiers to be included in the merchantReference field. For simplicity in this example it is primarily hardcoded into the view:
import UIKit
import TrustlySDK
@IBOutlet weak var trustly: TrustlyView!
var establishData:Dictionary<AnyHashable,Any>?
override func viewDidLoad() {
super.viewDidLoad()
self.establishData = [
"accessId": YOUR_ACCESS_ID,
"merchantId": YOUR_MERCHANT_ID,
"requestSignature": GENERATED_HASH,
"description": "transaction description",
"merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
"amount": "0.00",
"paymentType":"Deferred",
"currency":"USD",
"metadata.urlScheme":"yourapp://", // your app's deep link
// "env": "sandbox",
]
}
NOTE: When developing against the sandbox environment, set the
envproperty tosandbox. When publishing your production application, remove theenvproperty altogether.
See Establish Data for more details on required properties, accepted values and their behaviors.
Display the Select Bank Widget
While it is possible to launch the Trustly Lightbox without use of the Select Bank Widget, Trustly recommends rendering the Select Bank Widget for an optimal user experience. For information on the Select Bank Widget as it relates to the Trustly Lightbox visit Displaying the Bank Widget.
In your application, on the parent view implementation of viewDidLoad call the SDK’s selectBankWidget function to initiate the Select Bank Widget view.
@IBOutlet weak var trustly: TrustlyView!
var establishData:Dictionary<AnyHashable,Any>?
override func viewDidLoad() {
super.viewDidLoad()
self.establishData = [
"accessId": YOUR_ACCESS_ID,
"merchantId": YOUR_MERCHANT_ID,
"requestSignature": GENERATED_HASH,
"description": "transaction description",
"merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
"amount": "0.00",
"paymentType":"Deferred",
"currency":"USD",
"metadata.urlScheme":"yourapp://", // your app's deep link
"metadata.lang":"en_US",
// "env": "sandbox",
]
self.trustly.selectBankWidget(establishData) { (view, data) in
if let data = data {
print("returnParameters:\(data)")
self.establishData = data
}
}
}
Now your app will render the Select Bank Widget, allowing a user to select their bank from the widget before proceeding. No transaction data will be created until implementing the establish function in the next step.
Launch the Lightbox
The Lightbox is launched by calling the establish function with the establishData defined above. This function can be called by any button in your app such as a "Checkout" or "Continue" button. For this example we will:
class TrustlyLightboxViewController: UIViewController {
var establishData:Dictionary<AnyHashable,Any>?
var delegate: TrustlyLightboxViewProtocol?
override func viewDidLoad() {
super.viewDidLoad()
let trustlyLightboxPanel = TrustlyView()
self.view = trustlyLightboxPanel.establish(self.establishData, onReturn: {}, onCancel: {})
}
}
At this point, a user can select a bank from the Select Bank Widget and launch the Lightbox with the provided Establish data.
OAuth Setup and Redirects
In the case Next, add extensions to handle this deep link and trigger a notification to communicate to the Lightbox SDK that a user has returned to your application. This can be done in your AppDelegate or SceneDelegate, or in an extensions file. For example:
extension AppDelegate {
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
if url.absoluteString.contains("yourapp:") {
NotificationCenter.default.post(name: .trustlyCloseWebview, object: nil)
}
return true
}
}
extension Notification.Name{
static let trustlyCloseWebview = Notification.Name(TrustlyView.trustlyCloseWebview)
}
For a more comprehensive example of this logic, check out the Trustly iOS example app. Now that your app will support OAuth bank redirects, the Lightbox integration is nearly complete. In the next section we'll add handler functions to the onReturn and onCancel callback functions to complete our basic Lightbox implementation and direct users to the success or failure cases in your app.
Handle Lightbox Callback Events
The Trustly Lightbox provides two callback functions to handle terminal user behaviors. When a user successfully creates a bank authorization, the onReturn function will be called. If the user exits the process at any time or the authorization is otherwise unsuccessful, the onCancel function will be called. Find more details regarding these functions at Handling the Redirect.
Define two functions to handle these callbacks and pass them into the onReturn and onCancel parameters of the establish method. Handling the user experience of a cancellation or a successful authorization can be done in many ways. When the authorization is successful, your app can direct the user to the next step on their journey. In the background, your server will also receive an event from Trustly with corresponding data. To simulate a failure scenario and test various error codes, see the testing guide.
Example:
var establishData:Dictionary<AnyHashable,Any>?
var amount: String?
var delegate: TrustlyLightboxViewProtocol?
override func viewDidLoad() {
super.viewDidLoad()
let trustlyLightboxPanel = TrustlyView()
guard let amountText = amount else { return }
self.establishData = [
"accessId": YOUR_ACCESS_ID,
"merchantId": YOUR_MERCHANT_ID,
"requestSignature": GENERATED_HASH,
"description": "transaction description",
"merchantReference": YOUR_UNIQUE_TRANSACTION_REF,
"amount": "0.00",
"paymentType":"Deferred",
"currency":"USD",
"metadata.lang":"en_US"
]
self.view = trustlyLightboxPanel.establish(self.establishData , onReturn: {(trustly, returnParameters)->Void in
let response = returnParameters as! [String:String]
self.delegate?.onReturnWithTransactionId(transactionId: response["transactionId"]!, controller: self)
}, onCancel: {(trustly, returnParameters)->Void in
let response = returnParameters as! [String:String]
self.delegate?.onCancelWithTransactionId(transactionId: response["transactionId"]!, controller: self)
})
}
Next Steps
Test your mobile app by running the Trustly UI from the sandbox environment and selecting a demo bank to create test transactions. See more on testing and demo banks and additional items:
- Testing and demo banks
- Handling Errors in the Lightbox
- Customizing content strings in the Lightbox
- Branding & Experience guidance
If you'd like more help with your integration, reach out to your Trustly representative or send your request to [email protected].
Updated 11 months ago