Risk iOS package

The package helps collect device data for merchants with direct integration (standalone) with the package and those using Checkout's Frames iOS package.

Table of contents

• Risk iOS package
  • Table of contents
  • Requirements
  • Documentation
    • Usage guide
    • Public API
    • Device collectors
    • Additional Resources
  • Demo projects
  • Changelog
  • Contributing
  • License

Requirements

• iOS 13.0+
• Xcode 12.4+
• Swift 5.3+

Documentation

Usage guide

1. Add Risk as a package dependency - see Installation guide on how to add our SDK in your iOS app via SPM or Cocoapods.

2. Obtain a public API key from Checkout Dashboard.

3. Initialise the package Risk with the public API key and environment Risk.init(config: yourConfig) early-on.

   Type definitions

   public struct RiskConfig {
       let publicKey: String
       let environment: RiskEnvironment
       let framesMode: Bool
       
       public init(publicKey: String, environment: RiskEnvironment, framesMode: Bool = false) {
           self.publicKey = publicKey
           self.environment = environment
           self.framesMode = framesMode
       }
   }
   
   public enum RiskEnvironment {
       case qa
       case sandbox
       case production
   }

4. Use the configure to complete your setup, then publish the device data within the closure with the publishData method.

   Type definitions

   public struct PublishRiskData {
       public let deviceSessionId: String
   }
   
   public enum RiskError: LocalizedError, Equatable {
       case configuration(Configuration)
       case publish(Publish)
   }
   
   public enum RiskError {
       case configuration(Configuration)
       case publish(Publish)
   }
   
   public extension RiskError {
       enum Configuration: LocalizedError {
           case integrationDisabled
           case couldNotRetrieveConfiguration
           
           public var errorDescription: String? {
               switch self {
               case .integrationDisabled:
                   return "Integration disabled"
                   
               case .couldNotRetrieveConfiguration:
                   return "Error retrieving configuration"
               }
           }
       }
       
       enum Publish: LocalizedError {
           case couldNotPublishRiskData
           case couldNotPersisRiskData
           case fingerprintServiceIsNotConfigured
           
           public var errorDescription: String? {
               switch self {
               case .couldNotPublishRiskData:
                   return "Error publishing risk data"
                   
               case .couldNotPersisRiskData:
                   return "Error persisting risk data"
                   
               case .fingerprintServiceIsNotConfigured:
                   return "Fingerprint service is not configured. Please call configure() method first."
               }
           }
       }
   }

See example below:

import RiskSDK

// Example usage of package
let yourConfig = RiskConfig(publicKey: "pk_qa_xxx", environment: RiskEnvironment.qa)

// Optionally pass an mssd to send device data to your dedicated endpoint
let yourConfigWithMssd = RiskConfig(publicKey: "pk_qa_xxx", mssd: "xxxxxxxx", environment: RiskEnvironment.qa)

self.riskSDK = Risk.init(config: yourConfig)  

self.riskSDK.configure { configurationResult in

	switch configurationResult {
	case .failure(let errorResponse):
		print(errorResponse.localizedDescription)
	case .success():
		self.riskSDK.publishData { result in
			
			switch result {
			case .success(let response):
				print(response.deviceSessionId)
			case .failure(let errorResponse):
				print(errorResponse.localizedDescription)
			}
		}
	}
	
}   

Public API

Aside the instantiation via the init method, the package exposes two methods:

1. configure - This method completes your setup after initialisation. When the method is called, preliminary checks are made to Checkout's internal API(s) that retrieves other configurations required for collecting device data, if the checks fail or the merchant is disabled, the error is returned and logged, you can also see more information on your Xcode console while in development mode.

   Type definitions

   public func configure(completion: @escaping (Result<Void, RiskError.Configuration>) -> Void) {
       ...
   }

2. publishData - This is used to publish and persist the device data.

   Type definitions

   public func publishData (cardToken: String? = nil, completion: @escaping (Result<PublishRiskData, RiskError.Publish>) -> Void) {
           ...
   }

Device collectors

The SDK collects device data through one or more collectors. Which collectors run is controlled server-side per merchant via the configurations endpoint (data_collectors); no integration changes are required to enable or disable a collector.

Collector	Provider (device_collector_provider)	Description
FingerprintPRO	fingerprint	Highly accurate device id resolved server-side. Requires a fingerprint public key.
FingerprintJS (OSS)	simple	Open-source, on-device device id with no backend call. Runs in parallel with PRO when both are enabled.

When enabled, each collector's payload is sent on publishData in the fingerprint/v2 collectors array, tagged with its provider. A single collector failing does not prevent the others from publishing.

License: the open-source fingerprintjs-ios collector is MIT licensed with no restrictions on production usage. It operates entirely on-device (no data is sent to a third party).

Additional Resources

• Frames iOS SDK documentation

Demo projects

Our sample application showcases our prebuilt UIs and how our SDK works. You can run this locally once you clone the repository (whether directly via git or with suggested integration methods).

Our demo apps also test the supported integration methods (SPM, Cocoapods), so if you're having any problems there, they should offer a working example. You will find them in the root of the repository, inside respective folders:

• iOSExampleRiskCocoapods - (Cocoapods distribution)
• iOSExampleRiskSPM - (SPM distribution)  

Changelog

Find our CHANGELOG.md here.

Contributing

Find our guide to start contributing here.

License

Risk iOS is released under the MIT license. See LICENSE for details.