Getting Started

IdentitySdkCore

Requirements

The minimal iOS version of an application using the ReachFive iOS SDKs has to be 13.

To initialize the ReachFive client:

  • You need a Domain URL and Client ID.

  • You must whitelist all available domains where the ReachFive SDK will be used.

    This is done in the Allowed Origins (CORS) field of your ReachFive console, in the Settings menu.

iOS specific prerequisites

  • The client must be a First-party client with Token Endpoint Authentication Method set to None.

  • You must have the scheme registered in Allowed Callback URLs.

  • You should enforce PKCE for security purposes and enable Refresh Tokens for convenience.

For more on configuring a client, see Set up a client.

Installation

ReachFive SDKs are published on Cocoapods as independent modules. The latest version is 6.3.0.

You can also find releases directly on the ReachFive repo at ReachFive iOS SDK.

Below, you’ll find a description and instructions for installation for each module.


SDK Core

The core SDK contains all the main tools and interfaces, and methods related to standard authentication by identifier and password. It contains all common tools and interfaces and enables users to authenticate with their passwords.

  1. Add these lines to your Podfile file, replacing x.y.z with the latest version:

    pod 'IdentitySdkCore', '~> x.y.z'
  2. Then run:

    pod install
  3. Configure your application’s Info.plist file with the following XML snippet:

    <!-- Info.plist -->
    
    <key>CFBundleURLTypes</key>
    
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>reachfive-${clientId}</string>
            </array>
        </dict>
    </array>

Facebook native provider

This module uses the Facebook native SDK to provide a better user experience.

Refer to the Meta Connect (Facebook Login) guide to create your Facebook application.
  1. Add these lines to your Podfile file, replacing x.y.z with the latest version:

    pod 'IdentitySdkFacebook', '~> x.y.z'
  2. Then run:

    pod install
    If you’re using the latest version of the Facebook API, please remove the user_gender scope from the ReachFive client configuration to prevent any issues.
  3. Configure the Info.plist file with the following XML snippet that contains data about your application:

    <!-- Info.plist -->
    
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>fb$(YOUR_FACEBOOK_APPLICATION_ID)</string>
            </array>
        </dict>
    </array>
    <key>FacebookAppID</key>
    <string>$(YOUR_FACEBOOK_APPLICATION_ID)</string>
    <key>FacebookClientToken</key>
    <string>$(YOUR_FACEBOOK_CLIENT_TOKEN)</string>
    <key>FacebookDisplayName</key>
    <string>$(YOUR_APPLICATION_NAME)</string>
  4. Then to use any of the Facebook dialogs (e.g., Login, Share, App Invites, etc.) that can perform an app switch to Facebook apps, include the following lines:

    <!-- Info.plist -->
    
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>fbapi</string>
        <string>fb-messenger-share-api</string>
    </array>
See Info.plist reference for a comprehensive look at the file.

Google native provider

This module uses the Google native SDK to provide a better user experience.

Refer to the Google Connect guide to create your Google application.
  1. Add these lines to your Podfile file, replacing x.y.z with the latest version:

    pod 'IdentitySdkGoogle', '~> x.y.z'
  2. Then run:

    pod install
  3. Update your Info.plist file.

    • 6.0.0 and higher

    • 5.8.0 and lower

    1. Add your Google Client ID to the Info.plist file:

      ...
      <key>GIDClientID</key>
      <string>GOOGLE_CLIENT_ID</string> (1)
      ...
      1 This is your Google Client ID in standard format. For example, 1234567890-abcdefg.apps.googleusercontent.com.
      See Info.plist reference for a comprehensive look a the file.
    2. Add your reversed Google Client ID to the URL Scheme.

      <key>CFBundleURLTypes</key>
      <array>
      <dict>
          <key>CFBundleTypeRole</key>
          <string>Editor</string>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>YOUR_REVERSED_GOOGLE_CLIENT_ID</string> (1)
          </array>
      </dict>
      </array>
      1 The URL Scheme is the reversed Google Client ID (not ReachFive’s clientID), which is your Google Client ID with the order of the dot-delimited fields reversed. For example, com.googleusercontent.apps.abcdefg-1234567890.
      See Info.plist reference for a comprehensive look a the file.
    1. Add your reversed Google Client ID to the URL Scheme.

      <key>CFBundleURLTypes</key>
      <array>
      <dict>
          <key>CFBundleTypeRole</key>
          <string>Editor</string>
          <key>CFBundleURLSchemes</key>
          <array>
              <string>YOUR_REVERSED_GOOGLE_CLIENT_ID</string> (1)
          </array>
      </dict>
      </array>
      1 The URL Scheme is the reversed Google Client ID (not ReachFive’s clientID), which is your Google Client ID with the order of the dot-delimited fields reversed. For example, com.googleusercontent.apps.abcdefg-1234567890.
      See Info.plist reference for a comprehensive look a the file.

WeChat Connect

This module uses the WeChat native SDK to provide an optimal user experience. Add the following to your Info.plist file.

  1. Add these lines to your Podfile file, replacing x.y.z with the latest version:

    pod 'IdentityWeChat', '~> x.y.z'
  2. Then run:

    pod install
  3. Configure the Info.plist file with the following XML snippet that contains data about your application:

    Info.plist
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>weixin</string>
        <string>weixinULAPI</string>
        <string>weixinURLParamsAPI</string>
    </array>

Configure the iOS SDK

You must configure the iOS SDK to use it. This is where you provide the values for your domain and client ID, and define which native library you want to integrate with for Social Login.

By default, the URL scheme follows this pattern: reachfive-${clientId}://callback.

There are multiple schemes. All must be whitelisted in Allowed Callback URLs on your ReachFive Console.

Allowed URL Notes

reachfive-${clientId}://callback

This callback URL is used to open the app from another app such as an email client or the web for passwordless.

Other uses:

  • Switching from web context to app context in webviewLogin.

  • OAuth flow

reachfive-${clientId}://mfa

This callback URL is used for MFA verification.

Available from version 6.3.0.

reachfive-${clientId}://account-recovery

This callback URL is used for account recovery code verification.

Available from version 7.0.0.

Configuration

    let reachfive = ReachFive(
        // The configuration parameters required to initialize the ReachFive client
        sdkConfig: SdkConfig( (1)
            domain: DOMAIN,
            clientId: CLIENT_ID
            ),
        // The list of the social providers needed by the application
        providersCreators: [GoogleProvider(), FacebookProvider(), WeChatProvider()] (2)
    )
1 Sets the required parameters such as domain, ReachFive clientId, and the scheme.
2 Lists the social providers you need for your iOS application.

Customise scheme

You can also specify a scheme manually and customise schemes as shown here.

let ReachFive = ReachFive(
    sdkConfig: SdkConfig(
        domain: DOMAIN,
        clientId: CLIENT_ID,
        scheme: "reachfive-${clientId}://toto", (1)
        mfaUri: "reachfive-${clientId}://tata", (2)
        accountRecoveryUri: "reachfive-${clientId}://tutu" (3)
    )
)
1 Where the callback scheme ends with toto.
2 Where the callback mfaUri scheme ends with tata.
3 Where the callback accountRecoveryUri scheme ends with tutu.

Customise storage

Storage is used by the iOS SDK to store the PKCE code during passwordless and MFA flows.

By default it uses the UserDefaults storage, but it can be customised to be any object that implements our Storage protocol.

let ReachFive = ReachFive(
    sdkConfig: SdkConfig(
        domain: DOMAIN,
        clientId: CLIENT_ID
    ),
    storage: UserDefaultsStorage()
)
1 This value can be any object that implements our Storage protocol.

Initialize iOS SDK

You must initialize the iOS SDK to use it. Initializing the iOS SDK ensures the client configuration is properly fetched (which contains default scope) and native social providers are properly initialised.

You initialize your iOS client with:

   reachfive.application(application, didFinishLaunchingWithOptions: launchOptions)

Full examples

The full file examples below show you were to initialize the client as well as providing context for the overall configuration and initialization.

  • Minimum configuration

  • Full configuration

import UIKit (1)
import IdentitySdkCore

class AppDelegate: UIResponder, UIApplicationDelegate {
    let DOMAIN    = "Here paste your ReachFive domain" (2)
    let CLIENT_ID = "Here paste your ReachFive client ID" (3)

    let reachfive = ReachFive(
        // The configuration parameters required to initialize the ReachFive client
        sdkConfig: SdkConfig(domain: DOMAIN, clientId: CLIENT_ID)
    )

    // Return the ReachFive client
    static func reachfive() -> ReachFive {
        let app = UIApplication.shared.delegate as! AppDelegate
        return app.reachfive
    }

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize the ReachFive client
        return reachfive.application(application, didFinishLaunchingWithOptions: launchOptions) (4)
    }
}
1 Import the UIKit if using it. If using another UI framework, you may not initialize provider configuration.
2 Your ReachFive domain such as integ-sandbox.reach5.dev.
3 The ReachFive client such as zhU43…​51nvOM;
4 Initializing the ReachFive client.
import UIKit
import IdentitySdkCore
import IdentitySdkFacebook
import IdentitySdkGoogle
import IdentitySdkWeChat

class AppDelegate: UIResponder, UIApplicationDelegate {
    let DOMAIN    = "Here paste your ReachFive domain" // e.g. integ-sandbox-squad2.reach5.dev
    let CLIENT_ID = "Here paste your ReachFive client ID" // e.g. zhU43aRKZtzps551nvOM

    let reachfive = ReachFive(
        // The configuration parameters required to initialize the ReachFive client
        sdkConfig: SdkConfig(domain: DOMAIN, clientId: CLIENT_ID),
        // The list of the social providers needed by the application
        providersCreators: [GoogleProvider(), FacebookProvider(), WeChatProvider()]
    )

    // Return the ReachFive client
    static func reachfive() → ReachFive { (1)
        let app = UIApplication.shared.delegate as! AppDelegate
        return app.reachfive
    }

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) → Bool {
        reachfive.addPasswordlessCallback { result in
            // Add the callback that will be executed when the magic link is intercepted
        }

        // Initialize the ReachFive client
        return reachfive.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) → Void) → Bool {
        reachfive.application(application, continue: userActivity, restorationHandler: restorationHandler) (2)
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) → Bool {
        reachfive.application(app, open: url, options: options) (3)
    }

    func applicationDidBecomeActive(_ application: UIApplication) {
        reachfive.applicationDidBecomeActive(application) (4)
    }
}
1 An example of how to access of the ReachFive object from within the app.
2 This method is used to handle universal links which are used by providers.
3 This method is used to handle callback schemes which are used by passwordless and MFA as well as for account recovery, and providers.
4 This method is used to provide functionality to the providers.

iOS methods

The sidebar contains are all the functions/methods accessible via the iOS SDK.

In all the code examples, the ReachFive client is instantiated and stored in your AppDelegate class. You can access it through the AppDelegate.reachfive() method as shown here and in Configuration.

    // Return the ReachFive client
    static func reachfive() -> ReachFive {
        let app = UIApplication.shared.delegate as! AppDelegate
        return app.reachfive
    }

Info.plist reference

If you configure all four SDKs, your Info.plist file should contain the following XML Snippet.

  • 6.0.0 and higher

  • 5.8.0 and lower

<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>fb1634029666893228</string>
      </array>
   </dict>
   <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>com.googleusercontent.apps.abcdefg-1234567890</string>
      </array>
   </dict>
   <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>reachfive-TYAIHFRJ2a1FGJ1T8pKD</string>
      </array>
   </dict>
</array>
<key>GIDClientID</key>
<string>1234567890-abcdefg.apps.googleusercontent.com</string>
<key>FacebookAppID</key>
<string>1634029666893228</string>
<key>FacebookClientToken</key>
<string>ec97b21afcd93ce699091a774a90e2e5</string>
<key>FacebookDisplayName</key>
<string>Reach5 SDK Mobile</string>
<key>GIDClientID</key>
<string>abcdefg-1234567890.apps.googleusercontent.com</string>
<key>LSApplicationQueriesSchemes</key>
<array>
   <string>weixin</string>
   <string>weixinULAPI</string>
   <string>weixinURLParamsAPI</string>
   <string>fbapi</string>
   <string>fb-messenger-share-api</string>
</array>
<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>fb1634029666893228</string>
      </array>
   </dict>
   <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>com.googleusercontent.apps.abcdefg-1234567890</string>
      </array>
   </dict>
   <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>tyaihfrj2a1fgj1t8pkd</string>
      </array>
   </dict>
   <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>reachfive-TYAIHFRJ2a1FGJ1T8pKD</string>
      </array>
   </dict>
</array>
<key>FacebookAppID</key>
<string>1634029666893228</string>
<key>FacebookDisplayName</key>
<string>Reach5 SDK Mobile</string>
<key>LSApplicationQueriesSchemes</key>
<array>
   <string>fbapi</string>
   <string>fb-messenger-share-api</string>
   <string>fbauth2</string>
   <string>fbshareextension</string>
</array>