Getting Started

Breaking changes for 11.0.0, please read.

Breaking changes for iOS 11.0.0

There are several updates with the iOS 11.0.0 release that are considered breaking. Read the following for an overview of the changes, and follow the linked pages for the current API.

SdkConfig

  • Redirect URL fields (redirectUri, mfaUri, accountRecoveryUri, emailVerificationUri) are now URL instead of String.

  • The scheme alias for redirectUri is removed.

  • baseScheme is renamed to customScheme.

  • The initializer stops the app with a preconditionFailure when the scheme, domain, redirect URLs, or originWebAuthn fail validation, instead of failing later during a network call.

Passkey originWebAuthn

A passkey request’s originWebAuthn is validated and normalized the same way as the SdkConfig value. The call can throw ReachFiveError.TechnicalError if validation fails.

App-lifecycle callbacks return false

application(:open:options:) and application(:continue:restorationHandler:) now return false when neither the SDK nor a registered provider consumed the URL or activity. Previously they always returned true.

If your app also routes universal links or custom-scheme URLs, do so only when the call returns false.

ProviderCreator and Presentation

The ProviderCreator factory receives the ReachFive instance instead of sub-components, so it can reuse helpers such as buildAuthorizeURL, authWithCode, webviewLogin, and login(withProvider:).

Provider.login and native passkey requests take a Presentation instead of a UIViewController? or an anchor: ASPresentationAnchor.

See getProvider and login(withRequest) respectively.

CocoaPods is dropped

The core SDK and the Facebook and Google providers are only distributed with Swift Package Manager. import Reach5 no longer brings UIKit or Foundation into scope. Add those imports where your files need them.

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 schemes 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 available with Swift Package Manager as independent modules. Only WeChat Connect still uses Cocoapods.

If you are migrating from CocoaPods, import Reach5 no longer brings UIKit or Foundation into scope. Add an explicit import UIKit and import Foundation in each file that uses those types.
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, interfaces, and methods related to standard authentication by identifier and password, passkey, passwordless, and so on.

Installation

Add the package dependency with XCode using this package URL:

https://github.com/ReachFive/reachfive-ios.git

Or directly add this to the dependencies in Package.swift

dependencies: [
    .package(url: "https://github.com/ReachFive/reachfive-ios.git", .upToNextMajor(from: "11.0.0"))
]

Configuration

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>
See Info.plist reference for a comprehensive look at the file.

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.

Installation

Add the package dependency with XCode using this package URL:

https://github.com/ReachFive/reachfive-ios-facebook.git

Or directly add this to the dependencies in Package.swift

dependencies: [
    .package(url: "https://github.com/ReachFive/reachfive-ios-facebook.git", .upToNextMajor(from: "9.0.0"))
]

Configuration

If you’re using the latest version of the Facebook API, remove the user_gender scope from the ReachFive client configuration to prevent any issues.
  1. 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>
  2. 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>fbauth2</string> (1)
        <string>fbapi</string>
        <string>fb-messenger-share-api</string>
    </array>
    1 Required for Fast App Switch, which Reach5Facebook supports from 9.0.0.
See Info.plist reference for a comprehensive look at the file.

Fast App Switch

Fast App Switch sends the user to the native Facebook app to sign in instead of to a Safari view controller, so a user already signed in to the Facebook app does not have to sign in again. The fbauth2 scheme lets the SDK open the Facebook app, and fbapi lets it detect that the app is installed.

The appSwitch parameter is .enabled by default. Pass appSwitch: .disabled to FacebookProvider to always use the browser flow.

Your login still completes through the browser flow in these cases:

  • The Facebook app is not installed, in which case the Facebook SDK falls back on its own.

  • Meta has not enabled Fast App Switch for your Facebook application, as the feature is controlled remotely, and classic and limited logins are gated separately.

You get a classic login only when you build the provider with prefersLoginTracking: .enabled, the default being .limited, and App Tracking Transparency is authorized on the device. Otherwise the SDK asks Facebook for a limited login.

An app switch returns to your application through the fb$(YOUR_FACEBOOK_APPLICATION_ID) scheme you declared above. Forward application(_:open:options) to ReachFive, and scene(_:openURLContexts:) too if your application uses scenes, otherwise the login never completes after the user approves in the Facebook app.

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.

Installation

Add the package dependency with XCode using this package URL:

https://github.com/ReachFive/reachfive-ios-google.git

Or directly add this to the dependencies in Package.swift

dependencies: [
    .package(url: "https://github.com/ReachFive/reachfive-ios-google.git", .upToNextMajor(from: "9.0.0"))
]

Configuration

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

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

    <!-- Info.plist -->
    
    <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 at 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 at the file.

WeChat Connect

As of 2026-09-01, WeChat is not yet available for our iOS SDK version 11.0.0. We will update this page accordingly when it is available.

This module uses the WeChat native SDK to be able to interact with the WeChat app.

Installation

  • Cocoapods

  • Swift Package Manager

  1. Add this line to your Podfile file.

    pod 'IdentitySdkWeChat', '~> 7.0.0' (1)
    1 7.0.0 is the latest version of SDK.
  2. Then run:

    pod install

Swift Package Manager is not yet supported.

Configuration

  • 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>
See Info.plist reference for a comprehensive look at the file.

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 or some providers.

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

reachfive-${clientId}://email-verification

This callback URL is used to return to the app after email verification.

Available from version 8.2.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 customScheme.
2 Lists the social providers you need for your iOS application. For more details, see providerCreator.

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,
        customScheme: "myOwnScheme", (1)
        redirectUri: URL(string: "myOwnScheme://myOwnRedirectPath")!, (2)
        mfaUri: URL(string: "myOwnScheme://myOwnMfaPath")!, (3)
        accountRecoveryUri: URL(string: "myOwnScheme://myOwnRecoveryPath")!, (4)
        emailVerificationUri: URL(string: "myOwnScheme://myOwnEmailVerificationPath")! (5)
    )
)
1 The custom URL scheme. Pass the scheme only (no ://); it replaces the default reachfive-${clientId}. Every callback URI that you don’t override explicitly is then derived from it (myOwnScheme://callback, myOwnScheme://mfa, and so on).
2 Overrides the full default callback URI.
3 Overrides the full MFA callback URI.
4 Overrides the full account recovery callback URI.
5 Overrides the full email verification callback URI.

Associated Domains

Passkeys and WebProvider .universalLink need an Associated Domain and a matching apple-app-site-association file.
Associated domains also link your app to your website, so that credential managers can autofill passwords your users already saved for that website.
See apple-app-site-association.

Customise the WebAuthn origin

Passkey requests carry an origin, which defaults to https://${domain}. Set originWebAuthn when your passkeys are bound to another domain, such as a custom domain or one shared by several of your apps. Pass a full URL such as https://auth.example.com, not a bare host.

A value with no scheme, such as auth.example.com, is not a valid origin. SdkConfig stops the app at initialisation instead of falling back to your domain.

You never set the Relying Party ID yourself. ReachFive derives it from the origin’s host (auth.example.com) and returns it with each passkey request. Declare that same host in your Associated Domains and apple-app-site-association file, as described in apple-app-site-association.

Set the origin once in the SdkConfig rather than on every passkey request. A request that carries its own originWebAuthn still takes precedence over this value.

The origin you send must be allowed in the ReachFive Console under Settings  WebAuthn, or the server rejects the passkey request. See Allowed origins.
let reachFive = ReachFive(
    sdkConfig: SdkConfig(
        domain: DOMAIN,
        clientId: CLIENT_ID,
        originWebAuthn: URL(string: "https://auth.example.com")! (1)
    )
)
1 Only the scheme, the host and a non-default port are sent: a path or a trailing slash is ignored.

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.

For an example of a custom implementation, see ReachFive-ios: Secure storage using the keychain.

let reachFive = ReachFive(
    sdkConfig: SdkConfig(
        domain: DOMAIN,
        clientId: CLIENT_ID
    ),
    storage: UserDefaultsStorage() (1)
)
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 initialized.

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 Reach5

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

    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, as a bare host such as integ-sandbox.reach5.dev — no https:// prefix, no port and no trailing slash.
3 The ReachFive client such as zhU43…​51nvOM;
4 Initializes the iOS SDK by fetching information from the server about the client. For more details, see application(_:didFinishLaunchingWithOptions:).
import UIKit
import Reach5
import Reach5Facebook
import Reach5Google
import Reach5WeChat

class AppDelegate: UIResponder, UIApplicationDelegate {
    let DOMAIN    = "Here paste your ReachFive domain" // e.g. integ-sandbox-squad2.reach5.dev, as a bare host — no https:// prefix, no port and no trailing slash
    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 { (2)
        reachfive.addPasswordlessCallback { result in
            // Check result and extract the authToken if the callback was successful, then continue your flow (for example redirect to the profile page)
        }

        // 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) (3)
    }

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

    func applicationDidBecomeActive(_ application: UIApplication) {
        reachfive.applicationDidBecomeActive(application) (5)
    }
}
1 An example of how to access the ReachFive object from within the app.
2 Initializes the iOS SDK by fetching information from the server about the client. For more details, see application(_:didFinishLaunchingWithOptions:).
3 Forwards universal links to ReachFive. Required by WeChat and by custom providers whose callback is a universal link; not by WebProvider .universalLink. For more details, see application(_:continue:restorationHandler:).
4 Forwards custom-scheme callbacks used by passwordless, MFA, account recovery, and provider native apps. For more details, see application(_:open:options).
5 This method is used to provide functionality to the providers. For more details, see applicationDidBecomeActive(_:).

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.

<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>fbauth2</string>
   <string>fbapi</string>
   <string>fb-messenger-share-api</string>
</array>
R5 AI Assistant

Confirm Deletion