Ramp iOS SDK

Ramp iOS SDK is a library that allows you to easily integrate Ramp into your iOS app and communicate with it.

Integration

There are two ways to integrate Ramp Instant into your project: Swift Package Manager and Cocoapods.

Swift Package Manager

Show/Hide Swift Package Manager integration details

  1. Find your project in Xcode Navigator.

  2. Select your project from projects and targets list.

  3. In project details, switch to Swift Packages tab.

  4. Click on a plus sign in the bottom left corner.

  5. In Choose Package Repository window, paste Ramp Instant iOS SDK Github reference into the text field.

    git@github.com:RampNetwork/ramp-sdk-ios.git

  6. Click Next. Swift Package Manager will now verify the package.

  7. Swift Package Manager will choose the most up-to-date version of the package. You can change it, by providing version, branch or commit you need.

  8. Click Next. Swift Package Manager will now resolve the package with all its dependencies.

  9. After resolving, Swift Package Manager will let you choose all the targets to add the package to.

  10. Click Finish. Now you should see Ramp package listed under Swift Packages and be able to use it in your code.

Swift Package Manager issues

Sometimes Swift Package Manager may fail to resolve the package and/or its dependencies. If this happens, close Xcode, delete the DerivedData folder to clear Swift Package Manager's cache, and add the package again.

If you don't know how to do it, there is a very useful app called DevCleaner to help you with this exact task.

Cocoapods

Show Cocoapods integration details

  1. Make sure you have Cocoapods installed. To install Cocoapods, refer to Cocoapods Documentation.

  2. If your project doesn't have a Podfile, create it in the root directory of your project and paste the following code into it. Remember to change target name to the one you are using.

  3. If you already use Cocoapods in your project, add the following sources and the Ramp pod reference to proper target sections.

    platform :ios, '11.0'
    inhibit_all_warnings!
    source 'https://github.com/CocoaPods/Specs.git'
    source 'https://github.com/passbase/zoomauthentication-cocoapods-specs.git'
    source 'https://github.com/passbase/cocoapods-specs.git'
    source 'https://github.com/passbase/microblink-cocoapods-specs.git'
    target 'ExampleCocoapods' do
    use_frameworks!
    pod 'Ramp', :git => 'git@github.com:RampNetwork/ramp-sdk-ios.git', :tag => 'v0.9.0'
    end

  4. Open the Terminal app, go to root directory, and type pod install. Cocoapods will download Ramp library and all its dependencies and then create a .xcworkspace file, which from now on you should use to open your project (if you're not doing it already).

    $ pod install
    Analyzing dependencies
    Pre-downloading: `Ramp` from `git@github.com:RampNetwork/ramp-sdk-ios.git`, tag `v0.9.0`
    Downloading dependencies
    Installing Microblink (5.11.1)
    Installing Passbase (2.4.0)
    Installing Ramp (0.0.1)
    Installing ZoomAuthentication (8.7.1)
    Generating Pods project
    Integrating client project
    [!] Please close any current Xcode sessions and use `ExampleCocoapods.xcworkspace` for this project from now on.
    Pod installation complete! There is 1 dependency from the Podfile and 4 total pods installed.

  5. Now you should see Ramp directory in project navigator and be able to use Ramp in your code.

Project setup

After integrating Ramp iOS SDK, you need to adjust your app's permissions.

Ramp uses the Passbase library for Know Your Customer process. In order for Passbase to work, you have to add app permissions for Camera Usage and Photo Library Usage. You can find out how to do it via Passbase documentation.

Usage

After successful integration and setup, you are ready to add Ramp into your app!

Let's go through all the building blocks of the library and then we will look into a simple example.

struct Configuration

This configuration structure contains all the information you can customize before opening Ramp. All the parameters are optional. Name of each of them should be self-describing, but if you have any doubts, refer to the Ramp configuration documentation. You can create it using a memberwise initializer or modify any of the parameters later on.

struct Configuration {
var swapAsset: String? = nil
var swapAmount: String? = nil
var fiatCurrency: String? = nil
var fiatValue: String? = nil
var userAddress: String? = nil
var hostLogoUrl: String? = nil
var hostAppName: String? = nil
var userEmailAddress: String? = nil
var selectedCountryCode: String? = nil
var defaultAsset: String? = nil
var url: String? = nil
var webhookStatusUrl: String? = nil
var finalUrl: String? = nil
var containerNode: String? = nil
var hostApiKey: String? = nil
}

class RampViewController

This is the main view that you present to your user. You should initialize it using RampViewController.init(configuration: Configuration). This method will throw an error if Configuration is invalid. To receive callbacks from Ramp, set the delegate variable of Ramp view controller to a class that conforms to RampDelegate protocol.

To present the Ramp view controller, use UIViewController.present(_:animated:completion:) method. This is the only supported method - if you use any other, some aspects of Ramp may not work.

protocol RampDelegate

There are three required methods to implement in RampDelegate:

func ramp(_ rampViewController: RampViewController, didCreatePurchase purchase: PurchaseCreatedPayload)
func rampPurchaseDidFail(_ rampViewController: RampViewController)
func rampDidClose(_ rampViewController: RampViewController)

ramp(_:didCreatePurchase:) is called when a purchase is created, and returns a RampPurchase struct, containing all the information about it. All fields of the RampPurchase structure are described in the documentation

rampPurchaseDidFail(_) is called when Ramp fails in any aspect. You will see the reason of failure on the screen.

rampDidClose(_) is called when Ramp finishes the flow and can be closed. If you used one of the recommended methods for presenting the Ramp view controller, it will close itself. Otherwise, you are responsible for closing the view.

Moreover, an additional, optional method was added to monitor any errors that might occur when using Ramp. This method is for debugging purposes only.

func ramp(_ rampViewController: RampViewController, didRaiseError error: Error)

Integration example

Let's look at a simple example. This view controller code is fully functional - just connect @IBOutlet and @IBAction to corresponding UI elements. You can build on top of that, customizing configuration and reacting to events however you like.

Some payment methods redirect user to an external app - Safari or, if available, a payment provider's app (Revolut, Monzo, etc.). To redirect the user back to your app after the payment, you can set a custom URL scheme for your app and then, pass the scheme to Configuration struct’s deepLinkScheme property.

import UIKit
import Ramp
class ViewController: UIViewController {
@IBOutlet weak var emailTextField: UITextField!
@IBAction func showRamp(_ sender: UIButton) {
var configuration = Configuration()
configuration.userEmailAddress = emailTextField.text
configuration.selectedCountryCode = "pl"
let ramp = try! RampViewController(configuration: configuration)
ramp.delegate = self
present(ramp, animated: true)
}
}
extension ViewController: RampDelegate {
func ramp(_ rampViewController: RampViewController, didCreatePurchase purchase: RampPurchase) {}
func rampPurchaseDidFail(_ rampViewController: RampViewController) {}
func rampDidClose(_ rampViewController: RampViewController) {}
}

This code will allow you to get a user's email address from a text field and pass it to Ramp during initialization along with their country code. At this stage, your integration is almost ready - all that's left to do now is to get an API key and add it to your configuration. You can read more about Ramp API keys and learn how to get them here.