Setup

7 min

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.

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

In Xcode, select File -> Add Packages...

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

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

Select your desired version.

Click "Add Package"

SPM will automatically include all necessary dependencies.

CocoaPods

Create or update your Podfile:

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

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

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.

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

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.

Run pod install from your project directory.

Manual

Download the XCFrameworks from the GitHub repository.

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

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

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 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>

Note that if you would like to collect geolocation for transactions, the permissions must be requested in code at runtime. See Runtime Permissions for more information.

Initialisation

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

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.