---
title: Setup
slug: vjh--setup
docTags: 
createdAt: 2025-05-09T08:06:53.314Z
---

# Installation

To be able to add the Toro SDK to your project, you will need access to our GitHub repository, for which we will provide you with an access token.

:::hint{type="success"}
**Recommendation:** For new projects, we highly recommend using Swift Package Manager for the simplest integration experience. For existing CocoaPods projects with potential dependency conflicts, consider using the Core subspec.
:::

## Swift Package Manager

::::WorkflowBlock
:::WorkflowBlockItem
In Xcode, select File -> Add Packages...
:::

:::WorkflowBlockItem
Enter the repository URL in the top right search bar (we will confirm this to you when you begin your integration).
:::

:::WorkflowBlockItem
When prompted, authenticate with the username and access token we provided.
:::

:::WorkflowBlockItem
Select your desired version.
:::

:::WorkflowBlockItem
Click "Add Package"
:::
::::

SPM will automatically include all necessary dependencies.

## CocoaPods

::::WorkflowBlock
:::WorkflowBlockItem
Create or update your `Podfile`:

```ruby
platform :ios, '12.0'

toro_repo = 'REPOSITORY_URL' # Replace with provided URL
toro_version = 'VERSION' # Replace with desired version

target 'YourApp' do
  use_frameworks!
  
  # Option 1: Complete integration (recommended)
  # Includes all dependencies as XCFrameworks
  pod 'ToroSDK', :git => toro_repo, :tag => toro_version
  
  # Option 2: Core integration
  # For projects needing to manage dependencies separately
  # pod 'ToroSDK/Core', :git => toro_repo, :tag => toro_version
  # pod 'CryptoSwift', '~> 1.3.0'
  # pod 'XMLCoder', '~> 0.14.0'
  # pod 'Alamofire', '~> 5.0'
end
```
:::

:::WorkflowBlockItem
When using the Core integration option, you may need to add this post-install hook to your Podfile:

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
```

This ensures proper Swift module interfaces are generated. Without this, you may encounter unresolved symbol errors at run time due to binary compatibility issues.
:::

:::WorkflowBlockItem
To authenticate with GitHub, you can create a `.netrc` in your home directory.

```none
machine github.com
login YOUR_GITHUB_USERNAME
password YOUR_GITHUB_ACCESS_TOKEN
```

Alternatively, you can add the credentials directly to macOS Keychain or by cloning the repository, which will prompt you to enter the credentials.
:::

:::WorkflowBlockItem
Run `pod install` from your project directory.
:::
::::

## Manual

::::WorkflowBlock
:::WorkflowBlockItem
Download the XCFrameworks from the GitHub repository.
:::

:::WorkflowBlockItem
In Xcode, select your project -> target -> General tab.
:::

:::WorkflowBlockItem
Drag the XCFrameworks into the "Frameworks, Libraries, and Embedded Content" section.
:::

:::WorkflowBlockItem
Ensure "Embed & Sign" is selected for each framework.
:::
::::

# Info.plist Configuration

To use the SDK, you need to define the following in your application's `Info.plist` file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<!-- Location permissions - optional -->
	<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
	<string>We need your location to process secure payments.</string>
	<key>NSLocationWhenInUseUsageDescription</key>
	<string>We need your location to process secure payments.</string>
	
	<!-- Bluetooth background modes - required to maintain connection with payment terminals -->
	<key>UIBackgroundModes</key>
	<array>
		<string>bluetooth-central</string>
		<string>external-accessory</string>
	</array>
	
	<!-- Miura device protocols - required to communicate with Miura payment terminals -->
	<key>UISupportedExternalAccessoryProtocols</key>
	<array>
		<string>com.miura.shuttle</string>
		<string>com.miura.rpi</string>
	</array>
	
	<!-- Bluetooth usage descriptions - required for iOS to request Bluetooth permission -->
	<key>NSBluetoothAlwaysUsageDescription</key>
	<string>Bluetooth is used to connect to payment terminals.</string>
	<key>NSBluetoothPeripheralUsageDescription</key>
	<string>Bluetooth is used to connect to payment terminals.</string>
</dict>
</plist>
```

:::hint{type="info"}
Note that if you would like to collect geolocation for transactions, the permissions must be requested in code at runtime. See [Runtime Permissions](docId\:gfQiw_eHWK1GfRIs6n6ul) for more information.
:::

# Initialisation

In the sample application, we initialise the `ToroClient` instance in our `AppDelegate` and inject it into our `MainViewModel`:

```swift
import UIKit
import SwiftUI
import ToroSDK

@main
class AppDelegate: NSObject, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        let config = AppSettings.shared.getToroConfig()
        let toro = ToroClient(config: config)
        let mainViewModel = MainViewModel(toro: toro)

        window = UIWindow(frame: UIScreen.main.bounds)
        window?.rootViewController = UIHostingController(
            rootView: MainView(viewModel: mainViewModel)
        )
        window?.makeKeyAndVisible()
        return true
    }
}
```

You can feel free to manage your `ToroClient` instance in any way you wish, as long as it is only initialised once during the lifecycle of your application, e.g., wrapping it in a singleton so it is accessible globally.