# Risk iOS SDK

`Version 6.0.1`

The `checkout-risk-sdk-iOS` supports the [Fraud Detection](https://www.checkout.com/docs/business-operations/prevent-fraud.md) solution by capturing advanced fraud signals that are leveraged in Checkout.com's machine learning model for risk scores.

> **Information**
>
> To enable access to the Risk SDK, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
>
> For more information, see [Integrate with Risk SDK](https://www.checkout.com/docs/business-operations/prevent-fraud/integrate-with-risk-sdk.md).

---

## Before you start

Generate a [public API key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md#Public_API_keys) from your [Dashboard](https://dashboard.checkout.com).

---

## Step 1: Add the SDK as a project dependency

### Minimum requirements

The minimum requirements to use the iOS SDK are:

- iOS 12.0 or later as a deployment target
- Xcode 12.4 or later
- Swift 5.3 or later

### Add the SDK dependency

We recommend using Swift Package Manager to add our SDK due to its ease of use, but we also support integration via the CocoaPods dependency manager.

**Swift Package Manager**

Add our GitHub repository's URL (`https://github.com/checkout/checkout-risk-sdk-ios`) as a package dependency in your app.

For detailed steps, follow the [guide on Apple's documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

**CocoaPods**

> **Note**
>
> You must have the latest CocoaPods 1.10 or later installed.

Add the SDK to your app's `Podfile`:

```rb
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'Risk', '~> <latest_version>' 
end
```

Then, run the following command in the terminal:

```bash
$ pod install
```

To update your existing Cocoapod dependencies, use:

```bash
$ pod update
```

---

## Step 2: Initialize the SDK

Initialize the package by passing the:

- Public API key
- MSSD, which you can find in [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md)
- Environment

```swift
let yourConfig = RiskConfig(publicKey: "pk_xxx", mssd: "xxxxxxxx", environment: RiskEnvironment.sandbox)

// Initialize early-on in your app
self.riskSDK = Risk.init(config: yourConfig)
```

---

## Step 3: Publish and persist device data

Use the `configure` method to complete your setup after initialization. When the method is called, preliminary checks are made to Checkout. com's internal APIs. These APIs retrieve other configurations required for collecting device data.

If the checks fail or the merchant is disabled, an error is returned and logged.  You can also see more information on your Xcode console while in development mode.

If the checks are successful, the method returns an instance of `Risk`. You can then call the `publishData` method on the instance to publish the data.

---

## Sample configuration

```swift
import RiskSDK

// Example usage of package
let yourConfig = RiskConfig(publicKey: "pk_xxx", mssd: "xxxxxxxx", environment: RiskEnvironment.sandbox)

// Initialize in your app
self.riskSDK = Risk.init(config: yourConfig)  

// Complete your setup and publish data
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)
			}
		}
	}
	
}   
```
---

## Type definition

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

public func publishData(cardToken: String? = nil, completion: @escaping (Result<PublishRiskData, RiskError>) -> Void) {
        ...
}
public struct RiskConfig {
    let publicKey: String
    let mssd: String
    let environment: RiskEnvironment
    let framesMode: Bool
    
    public init(publicKey: String, mssd: String, environment: RiskEnvironment, framesMode: Bool = false) {
        self.publicKey = publicKey
        self.mssd = mssd
        self.environment = environment
        self.framesMode = framesMode
    }
}

public enum RiskEnvironment {
    case qa
    case sandbox
    case production
}

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."
            }
        }
    }
}

```