This document provides the best practice guidelines for VCO SDK integration in iOS. The scenarios included in this document have been extracted from real world integration issues which merchants have faced.
iOS Best Practices
1. Recommended Integration
There are two recommended ways by which we can integrate VCO SDK in iOS:
- Via Cocoapods: use, pod 'VisaCheckoutSDK', '7.0.0' and run command, pod install.
- Manual Integration: Drag the VisaCheckoutSDK.framework file into the Framework, Libraries and Embedded Content section.
Please note, to update the value of Embed as Embed & Sign. Also don’t forget to checkmark copy items if needed, when you integrate the SDK manually.
2. Recommended Native Integration
It is always recommended to use the SDK with required class methods and parameters defined in VisaCheckoutSDK.framework. The mandatory step is to configure the SDK in AppDelegate class inside your didFinishLaunchingWithOptions method.
There are two ways to integrate the Visa Checkout Button in your class. One as Regular checkout button and another as Custom checkout button.
Make sure to import VisaCheckoutSDK in all those classes which uses its functionality.
The following code snippet is showing the one of the way out to integrate using the profile and purchase information:
class ViewController: UIViewController {
@IBOutlet weak var checkoutButton: VisaCheckoutButton!
var launchCheckoutHandle: LaunchHandle?
override func viewDidLoad() {
super.viewDidLoad()
initVisaCheckout()
}
func initVisaCheckout() {
let profile = Profile(environment: .sandbox, apiKey: <#String#>, profileName: nil)
let amount = CurrencyAmount(double: 23.09)
let purchaseInfo = PurchaseInfo(total: amount, currency: .usd)
checkoutButton.onCheckout(
profile: profile,
purchaseInfo: purchaseInfo,
presenting: self,
onReady: { [weak self] launchHandle in
self?.launchCheckoutHandle = launchHandle
}, onButtonTapped: { [weak self] in
self?.launchVisaCheckout()
}, completion: resultHandler())
}
func resultHandler() -> VisaCheckoutResultHandler {
return { result in
switch (result.statusCode) {
case .statusInternalError:
print("ERROR");
case .statusNotConfigured:
print("NOT CONFIGURED");
case .statusDuplicateCheckoutAttempt:
print("DUPLICATE CHECKOUT ATTEMPT");
case .statusUserCancelled:
print("USER CANCELLED");
case .statusSuccess:
print("SUCCESS");
case .default:
fallthrough
@unknown default:
print("Default Result")
}
}
}
func launchVisaCheckout() {
guard let launchCheckout = self.launchCheckoutHandle else {
return
}
launchCheckout()
}
}
3. Face ID Integration
To enable Face ID it’s is highly recommended to include the “Privacy – Face ID Usage Description” key in your app’s Info.plist since a main feature of the Visa Checkout Plugin is easier authentication.
4. Recommended Hybrid Integration
VCO SDK provides a plugin that enables the biometric authentication for hybrid mobile app.
An Important step is to import VisaCheckoutSDK in AppDelegate and configure it in didFinishLaunchingWithOptions method.
Please note, its mandatory to adapt to WKUIDelegate in your view controller and also to set the value of javaScriptCanOpenWindowsAutomatically to true, and do this before loading your website (use of UIWebview is not recommended by Visa and Apple in developing the apps, only use WKWebview for hybrid integrations).
5. Avoid Some Common Mistakes
We have listed down few commonly adapted wrong integration patterns by developers, please avoid integrating Visa Checkout SDK as listed below:
Please avoid to initialize the SDK multiple times, only initialize it once when your view is loaded. Having initialized it multiple times can lead to stuck the VCO process in loading screen by showing the endless spinner.
- Call LaunchHandle() in onReady:
Its recommended to hold the local reference of callback of launchhandle which comes in onReady, and call this callback method reference inside the onButtonTapped. If not done as recommended then it can cause a VCO lightbox to appear on the screen immediately when you initialize the SDK which can lead to some anonymous problems related to user interface, because we are wrongly populating the SDK without user consent or interaction on VCO button.
- Call LaunchHandle by it’s Name rather as a method:
It’s always recommended to call the reference of launchHandle as a method launchHandle () not as it’s reference name, launchHandle, inside the onButtonTapped method, because if done as a name then the user will not be able to launch the lightbox when tapping on the VCO button on screen, as it will not perform any action on tap.
- Deinitialize Launchhandle onButtonTapped:
It has been seen that users sometimes deinitialize or make the reference of launchHandle nil inside the onButtonTapped method, by which their app starts crashing when user tap on the VCO button. It’s recommended not to do that inside the onButtonTapped, rather if you want to make it nil or deinitialize, then do that when the complete VCO process is completed and a response callback came inside VisaCheckoutResultHandler.
It is also to be noted that we highly recommend the scope of the launcHandle should persist in complete Visa Checkout process.
When you create the instance of Profile Class, to pass it to VCO SDK, we have an option to set the name of Profile used by merchant. If you do not pass anything to this parameter or you pass nil to it, then in this case the SDK will auto select the Default profile created for user.
If user want to put some restrictions related to Billing Information, Shipping Information, locale or accepted Card Brands, etc. then user create some profiles under their account, which when loaded inside SDK can configure the SDK and show the related lightbox.
It’s highly recommended, if user has some defined Profiles and they are not seeing the SDK behaving as they set the fields in their custom profile, then please include the Profile Name, when you create an instance of Profile to pass to SDK.
We hope this helps as you integrate the Visa Checkout iOS SDK. Any questions? Comment below, we're here to help.
