Upgrading to our new iOS Objective-C SDK (4.7.2)
We have come a long way from the 4.1 iOS Objective-C SDK. Since the release, we have introduced our new collection of Swift SDKs, judoSwift, which simplified the communications with judo’s REST API, and paved the way for the feature rich judoKit. Our kit contains out-of-the-box functionalities like Address Verification System (AVS), 3D Secure, and other input verifications necessary for submitting card information for payments and other transactions. Together with our mobile-specific fraud prevention judoShield module, we provide the perfect basis that makes accepting transactions easier, simpler, and more secure.
In our pursuit to make payments in apps even more secure, and due to changes in PCI’s security standards, we are phasing out some older versions of our tech. This means you might need to upgrade to our latest SDKs by the 20th October 2016.
This guide will walk you through the steps needed to upgrade your app to the latest SDK.
Where to find the SDK
Previously, our SDK was only available to download from our website, but we have improved this by making our SDK available on CocoaPods:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '7.0' pod 'JudoSDK', '~> 4.7.1'
After executing ‘pod update’, the pod will be added to your project and you can use it in your project.
Using the SDK
The `Judo` class replaces the `JudoSDKManager` found in versions 4.1 to 4.6 of the judoNative Obj-C SDK.
The first step you must do when calling the SDK is to initialize it with your API token and secret, allowing judo to identify the account you’re using.
Then, you need to import the main header containing all the public header files in your `AppDelegate.m` file.
Finally, in your `applicationDidFinishLaunchingWithOptions:` method execute the following command using your own token and secret from your judo Dashboard:
[[Judo sharedSession] setToken:@"TOKEN" andSecret:@"SECRET"];
Modules (using the Obj-C SDK in Swift projects)
Version 4.7.2 of the Obj-C SDK now supports modules. This means you no longer need to provide an Obj-C bridging header for Swift projects. You can simply import the module itself by adding the following statement to the top of your `.swift` file:
The `Judo` class also includes methods for changing some configuration options for the SDK.Address verification system
Address Verification System (AVS)
Judo.isAVSEnabled ... Judo.AVSEnabled = YES
This brings up address verification fields when performing a transaction.accepting maestro cards
Accepting Maestro cards
Judo.isMaestroAccepted ... Judo.maestroAccepted = YES
Configures if Maestro cards should be accepted.
**Be aware that accepting Maestro cards is a feature that needs to be configured on your judo Dashboard, please contact us for more information on how to enable Maestro card acceptance.
Accepting American Express cards
Judo.isAMEXAccepted ... Judo.AMEXAccepted = YES
Configures if American Express cards should be accepted.
**Be aware that accepting Amex cards is also a feature that needs to be configured on your judo Dashboard, please contact judo for more information on how to enable Amex card acceptance.
Previously there was a top level configuration to set the currency in the `JudoSDKManager` class as follows:
The new method requires the currency to be set along every single transaction to avoid confusion in an international environment.
- (nonnull instancetype)initWithAmount:(nonnull NSDecimalNumber *)amount currency:(nonnull NSString *)currency;
+ (nonnull instancetype)amount:(nonnull NSDecimalNumber *)amount currency:(nonnull NSString *)currency;
You can use either of the following methods:
NSDecimalNumber *amountNumber = ...; [[JPAmount alloc] initWithAmount:amountNumber currency:@"GBP"]; NSDecimalNumber *amountNumber = ...; [JPAmount amount:amountNumber currency:@"GBP"];
**Be aware that you should never use floating point primitive types with monetary values due to the possibility of rounding errors.
In earlier versions of the SDK you needed to enable fraud signals by passing a unique ID number for a given consumer. We have implemented a new solution that uses device fingerprinting methods, which give us a much better understanding of fraudulent behaviour. The following method was removed entirely:
User Agent forwarding
To match security with handling 3D Secure (3DS) requests, in previous versions, we had to match the User Agent with the default User Agent that is accessing the 3DS authentication page. Due to this being an extremely complicated system that brings no apparent benefit, we have scrapped this functionality in the newer versions of the SDK. Our experience showed that it didn’t give any additional benefit, and 3DS still works in our tests without the following methods to be used:
+ (void)setUserAgent; + (BOOL)shouldCheckUserAgent; + (void)handleApplicationOpenURL:(NSURL *)url;
Location is now fetched in a smarter way – via our JudoShield module. The following method was scrapped:
@property (nonatomic, assign, getter=isLocationEnabled) BOOL locationEnabled;
From a modelling perspective, it never made sense to have the possibility of enabling or disabling 3DS inside the SDK. The 3DS request has to come from our judo API, and as the setting is made within your judo Dashboard, the SDK should act according to its responses.
@property (nonatomic, assign, getter=isThreeDSEnabled) BOOL threeDSEnabled;
the `JudoSDKManager` class was using static methods to set and retrieve the above mentioned settings. This was scrapped in favour of using a Singleton that contains properties. Previously you would use `[JudoSDKManager setAVSEnabled:true]`, you will now use `[Judo sharedSession].AVSEnabled = true`, or in a better use case for MVC, create your own Session by doing:
Judo *mySession = [[Judo alloc] init]; mySession.AVSEnabled = true
This is the case for most of the settings.Networking methods
In the previous versions, we were using Networking calls right from the session. This was bad encapsulation. The methods for GET, POST and PUT have been moved to a private API, since those APIs should not be accessible through the judo SDK.
Custom UI Transactions
Custom UI Transactions have been moved to the `TransactionProcessingApiService` class:
+ (void)makeAPaymentWithAmountFromCustomUI:(JPAmount)amount toJudoID:(nonnull NSString *)judoID withPayRef:(nonnull NSString *)ref withConsumerRef:(nonnull NSString *)consumerRef withMetaData:(nullable NSDictionary *)metaData inViewController:(nullable id)dvc withCard:(nonnull Card *)card andParentViewController:(nullable id)viewController withSuccess:(nullable void(^)(id __nullable JSON))successBlock withFailure:(nullable void(^)(NSError * __nullable error))failureBlock
Massive one line calling blocks have been removed in favour of creating a single `Transaction` object to pass it to the `TransactionProcessingApiService`.
For our transactions, we have renamed all the methods to make it more readable, which is why this:
+ (void)makeAPaymentWithAmount:(JPAmount)amount toJudoID:(nonnull NSString *)judoID withPayRef:(nonnull NSString *)ref withConsumerRef:(nonnull NSString *)consumerRef withMetaData:(nullable NSDictionary *)metaData andParentViewController:(nonnull id)viewController withSuccess:(nullable void(^)(id __nullable JSON))successBlock withFailure:(nullable void(^)(NSError * __nullable error))failureBlock
has now become:
- (void)judoPaymentWithAmount:(nonnull JPAmount *)amount cardDetails:(nonnull NSDictionary *)cardDetails judoID:(nonnull NSString *)judoID consumerRef:(nonnull NSString *)consumerRef metaData:(nullable NSDictionary *)metaData parentViewController:(nonnull id)viewController success:(nullable void (^)(id __nullable JSON))successBlock failure:(nullable void (^)(NSError * __nullable error))failureBlock;
Payment reference is now done automatically to reduce duplications when sending transactions.
We hope you have found this guide helpful. If you have any questions or need clarifications, please do contact us by emailing email@example.com, or by calling 0203 503 0600.
About Judopay · Judopay simplifies in-app payments, enable frictionless checkouts and intelligently prevents fraud for leading companies globally. Our payments and mobile experts help guide businesses and their development partners to create best in class apps to make paying faster, easier and more secure. Founded by serial financial technology entrepreneurs in 2012, Judopay is backed by leading venture investors and supported by banking and card scheme partners to offer in-app payments that are simple, frictionless and protected.