iOS Integration

Synaps integrates its workflow easily on iOS devices without extra packages or SDK. Thanks to ASWebAuthenticationSession component, iOS lets you access our iframe integration easily. Here is a guided tour of how integrating Synaps on native iOS.

1. Create a Synaps app

To start, you need to create an app. After logged in to your Synaps Manager interface, just click on New app. Go to integration tab and copy your Synaps API Key

2. Integrate Synaps Sessions with your Private API

As you are dealing with a mobile app, no sensitive information should appear on it. You should store no credentials, passwords, API Keys directly in your mobile codebase as it can easily be accessed by anyone.

The most common way to deal with sensitive information is to call your Private API and set a authorization mechanism using access token for instance. This mechanism will lets you call the API with a time-based token and will keep every sensitive data in your backend.

Synaps API Key is a sensitive information. This key will lets you generate new verification sessions and access sessions information.

Synaps Session ID is not a sensitive information. This Session ID has been built for front-end. It can be exposed publicly without any problem because it exposes no user information. It has been designed to only upload information.

As you are designing an iOS app and as it is considered as a front-end (publicly accessible), your goal is to call your private API that will generates a Synaps Session ID for you.

3. Integrate Synaps Flow with ASWebAuthenticationSession to your app

ASWebAuthenticationSession has been introduced by Apple to lets you open a Safari Modal easily on your app. As Safari is the most easiest way to get access to devices capabilities such as camera, Synaps integrates very well with it. It is compatible with iOS 13+.

We are going to design a simple view of an app where we will be able to open up the Synaps Flow in a SFSafariViewController modal.

  1. Create a Single View App using Xcode

Once your app is created, go to the Main.storyboard and add a Verify with Synaps button. We are going to trigger its action to open up our modal.

2. Integrate ASWebAuthenticationSession in your View Controller

Go to your ViewController.swift and add the following code to your controller

//
// ViewController.swift
// sample-demo-kyc
//
// Created by Riwan on 01/07/2020.
// Copyright © 2020 Synaps. All rights reserved.
//
import UIKit
import SafariServices
import AuthenticationServices
class ViewController: UIViewController, SFSafariViewControllerDelegate {
override func viewDidLoad() {
super.viewDidLoad()
}
@IBAction func openSynaps(_ sender: Any) {
// Allowed scheme in your info.plist that can be called by the ASWebAuthenticationSession
let callbackScheme = "com.synaps.verify://back"
// Encode URL to avoid conflict with Session URL
let callbackSchemeEncoded = callbackScheme.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)
// Session Id previously initialized using your private API
let sessionId = "aca98307-9ace-b7b5-7afe-9e8b2f8f"
// Primary Color
let primaryColor = "00707F"
// Secondary Color
let secondaryColor = "FFFFFF"
// Default lang (available: en, fr)
let lang = "en"
// Session URL
guard let sessionURL = URL(string: String(format: "https://verify.synaps.io/?session_id=%1$@&service=workflow&lang=%2$@&deeplink_redirection=%3$@&mobile=ios&primary_color=%4$@&secondary_color=%5$@", sessionId, lang, callbackScheme, primaryColor, secondaryColor)) else { return }
// Initialize the session
let session = ASWebAuthenticationSession(url: sessionURL, callbackURLScheme: callbackSchemeEncoded) { callbackURL, error in
/* Replace this alert with your business logic */
let alert = UIAlertController(title: "Synaps", message: "Pull data from Synaps API using your Private API", preferredStyle: UIAlertController.Style.alert)
alert.addAction(UIAlertAction(title: "OK", style: UIAlertAction.Style.default, handler: nil))
self.present(alert, animated: true, completion: nil)
}
session.prefersEphemeralWebBrowserSession = true
session.presentationContextProvider = self
session.start()
}
}
extension ViewController: ASWebAuthenticationPresentationContextProviding {
func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
return view.window!
}
}

openSynaps - Triggers the "Verify with Synaps" button and start the ASWebAuthenticationSession session

@IBAction func openSynaps(_ sender: Any) {
// Allowed scheme in your info.plist that can be called by the ASWebAuthenticationSession
let callbackScheme = "com.synaps.verify://back"
// Encode URL to avoid conflict with Session URL
let callbackSchemeEncoded = callbackScheme.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)
// Session Id previously initialized using your private API
let sessionId = "aca98307-9ace-b7b5-7afe-9e8b2f8f"
// Primary Color
let primaryColor = "00707F"
// Secondary Color
let secondaryColor = "FFFFFF"
// Default lang (available: en, fr)
let lang = "en"
// Session URL
guard let sessionURL = URL(string: String(format: "https://verify.synaps.io/?session_id=%1$@&service=workflow&lang=%2$@&deeplink_redirection=%3$@&mobile=ios&primary_color=%4$@&secondary_color=%5$@", sessionId, lang, callbackScheme, primaryColor, secondaryColor)) else { return }
// Initialize the session
let session = ASWebAuthenticationSession(url: sessionURL, callbackURLScheme: callbackSchemeEncoded) { callbackURL, error in
/* Replace this alert with your business logic */
let alert = UIAlertController(title: "Synaps", message: "Pull data from Synaps API using your Private API", preferredStyle: UIAlertController.Style.alert)
alert.addAction(UIAlertAction(title: "OK", style: UIAlertAction.Style.default, handler: nil))
self.present(alert, animated: true, completion: nil)
}
session.prefersEphemeralWebBrowserSession = true
session.presentationContextProvider = self
session.start()
}

Build your Synaps Session Link

You can see in the following code block that the Synaps Session Link is static. Let's see how to build it dynamically.

// Allowed scheme in your info.plist that can be called by the ASWebAuthenticationSession
let callbackScheme = "com.synaps.verify://back"
// Encode URL to avoid conflict with Session URL
let callbackSchemeEncoded = callbackScheme.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)
// Session Id previously initialized using your private API
let sessionId = "aca98307-9ace-b7b5-7afe-9e8b2f8f"
// Primary Color
let primaryColor = "00707F"
// Secondary Color
let secondaryColor = "FFFFFF"
// Default lang (available: en, fr)
let lang = "en"

callbackScheme is the scheme that you previously added in your info.plist to authorized web browser to be redirected to your app using this scheme. In other words, you authorized anyone to go to your app simply by typing in safari com.synaps.verify://back. As ASWebAuthenticationSession is an instance of Safari, it work the same way. Once the user will click "back to app", Synaps will trigger this callbackScheme and you will be able to handle the callback.

Add custom scheme to your info.plist

As said earlier, you need to add to your info.plist the custom scheme you want to let us redirect your users to your app.

  1. Go to info.plist

  2. Right Click Add row

  3. Add URL Types

  4. Click on the "+"

  5. Set your URL identifier

  6. Set your URL schemes

Handling callback

The above chunk of the code is triggered when the user come back to your app. At this moment, you have to handle your business logic. The most common way is to call your Private API to pull data from Synaps about the current authenticated user.

// Initialize the session
let session = ASWebAuthenticationSession(url: sessionURL, callbackURLScheme: callbackSchemeEncoded) { callbackURL, error in
/* Replace this alert with your business logic */
let alert = UIAlertController(title: "Synaps", message: "Pull data from Synaps API using your Private API", preferredStyle: UIAlertController.Style.alert)
alert.addAction(UIAlertAction(title: "OK", style: UIAlertAction.Style.default, handler: nil))
self.present(alert, animated: true, completion: nil)
}
https://verify.synaps.io
Request
Response
Request
Path Parameters
optional
string
Query Parameters
secondary_color
optional
string
Secondary Color of your theme in HEX w
primary_color
optional
string
Primary Color of your theme in HEX without "#"
deeplink_redirection
required
string
custom scheme to redirect your user to your app at the end of the onboarding process
mobile
required
string
As your are on iOS platform simply add ios as query parameter
service
required
string
The service name based on your app workflow
session_id
required
string
Session ID previously pulled using your Private API and associated to your current user
Response
200: OK

The Synaps Session Link will remains approximately always the same only session_id and service parameters will change for iOS integration.

https://verify.synaps.io/?session_id={SESSION_ID}&service={SESSION_SERVICE}&deeplink_redirection={DEEPLINK_REDIRECTION}&mobile=ios

If you have any technical question, don't hesitate to reach riwan@synaps.io