Rownd SDK for iOS

The Rownd SDK for iOS provides authentication, account and user profile management, deep linking, and more for native iPhone, iPad, and even macOS applications.

Using the Rownd platform, you can easily bring the same authentication that's on your website to your mobile apps. Or if you only authenticate users on your mobile apps, you can streamline the authentication process using Rownd's passwordless sign-in links, enabling you to seamlessly authenticate users from an app link sent to their email or phone number.

Once a user is authenticated, you can retrieve and update their profile information on the fly using native APIs. Leverage Rownd's pre-built mobile app components to give users profile management tools.

Installation

In Xcode, select your project file, select the main target, then scroll down to the "frameworks" section to add a package dependency to your project. See the official documentation for specific steps.

Enter this as the package repository url:

https://github.com/rownd/ios.git

Usage

Initializing the Rownd SDK

In your AppDelegate file, call the Rownd.configure() method during application launch:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {

    Task {
        await Rownd.configure(launchOptions: launchOptions, appKey: "YOUR_API_KEY")
    }

    return true
}

After initialization, your app will typically call Rownd.requestSignIn() at some point, if the user is not already authenticated. This will display the Rownd interface for authenticating the user. Once they complete the sign-in process, an access token and the user's profile information will be available to your app.

Handling authentication

Rownd leverages an observeable architecture to expose data to your app. This means that as the Rownd state changes, an app can dynamically update without complicated logic. For example, a view can display different information based on the user's authentication status.

Here's an example SwiftUI view that displays different messages depending on the user's authenticated status:

import SwiftUI
import Rownd

struct MyView: View {
    @StateObject var authState = Rownd.getInstance().state().subscribe { $0.auth }
    @StateObject var user = Rownd.getInstance().state().subscribe { $0.user.data }

    var body: some View {
        VStack {
            HStack {
                Button(action: {
                    if authState.current.isAuthenticated {
                        Rownd.signOut()
                    } else {
                        Rownd.requestSignIn()
                    }
                },
                       label: {
                    Text(!authState.current.isAuthenticated ? "Sign in" : "Sign out")
                })
                Spacer()
                if authState.current.isAuthenticated {
                    Button(action: {

                    }, label: {
                        Text(user.current?["first_name"]?.value as? String)
                    })
                }
            }
            .padding(.horizontal)
        }
    }
}

struct MyView_Previews: PreviewProvider {
    static var previews: some View {
        MyView()
    }
}

Example usage outside of SwiftUI

class Auth {
    private var authState = Rownd.getInstance().state().subscribe { $0.auth }
    private var cancellables = Set<AnyCancellable>()
    init() {
        self.authState.$current
            .sink { [weak self] state in
                // Called whenever the auth state changes
                guard !state.isLoading else { return }

                guard state.auth.isAuthenticated else {
                    return
                }

                // User is authenticated. Change app state accordingly.
                // This is also a good time to get the latest access token.
                let accessToken = await Rownd.getAccessToken()
            }
            .store(in: &cancellables)
    }
}

You can subscribe to any state object that Rownd supports. Here's a list of available states and their structures:

.auth

public struct AuthState {
    public var accessToken: String?     // Current, valid access token for the user (valid for one hour)
    public var isAuthenticated: Bool    // Whether the user is currently authenticated
    public var isAccessTokenValid: Bool // Whether the current access token is valid
    public var isVerifiedUser: Bool?    // Whether the current user has verified at least one identifier (e.g., email)
    public var hasPreviouslySignedIn: Bool    // Whether the app has been previously signed in before
}

.user

public struct UserState {
    public var id: String?                           // The user's ID as known to Rownd
    public var data: Dictionary<String, AnyCodable>  // Contains key/value pairs for the current user based on your Rownd's app config
}

Getting an access token

Whenever your app needs to make an authenticated request to your backend, you'll need to get an access token. You can do this by calling await Rownd.getAccessToken(throwIfMissing: true). If the user is not authenticated, this function will throw an AuthenticationError.noAccessTokenPresent error.

If there is an issue fetching the access token (e.g., during a token refresh), an AuthenticationError.serverError or AuthenticationError.networkConnectionFailure error will be thrown. Server and network failures are automatically retried before throwing an error.

If the user is signed in, but the refresh token is expired, invalidated, or has been used previously, the user will be signed out and the function will throw an AuthenticationError.invalidRefreshToken error.

See the API reference for more information.

Customizing the UI

While most customizations are handled via the Rownd dashboard, there are a few things that have to be customized directly in the SDK.

The RowndCustomizations class exists to facilitate these customizations. It provides the following properties that may be subclassed or overridden.

• sheetBackgroundColor: UIColor (default: light: .white, dark: .systemGray6; requires subclassing) - Allows changing the background color underlaying the bottom sheet that appears when signing in, managing the user account, etc.
• sheetCornerBorderRadius: CGFloat (default: 25.0) - Modifies the curvature radius of the bottom sheet corners.
• loadingAnimation: Lottie.Animation? (default: nil) - Use this animation instead of the system default loading spinner (i.e., UIActivityIndicatorView or ProgressView). Any animation compatible with Lottie should work, but will be scaled to fit a 1:1 aspect ratio (usually with a CGRect frame width/height of 100)
• loadingAnimationUiView: UiView? (default: nil) - Display this UIView instead of the system default loading spinner. When using this option, you are responsible for starting the animation and ensuring that the view displays the animation vertically and horizontally centered in the view. Rownd will add and remove the view to a parent view as needed. Here's an example implementation.

To apply customizations, we recommend subclassing the RowndCustomizations class. Here's an example:

class AppCustomizations : RowndCustomizations {
    override var sheetBackgroundColor: UIColor {
        return UIColor(red: 31/255, green: 37/255, blue: 80/255, alpha: 1.0)
    }
}

// AppDelegate.swift
import Rownd

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {

        Rownd.config.customizations = AppCustomizations()   // Apply the customizations

        Task {
            await Rownd.configure(launchOptions: launchOptions, appKey: "YOUR_API_KEY")
        }

        return true
    }
}

Usage within app extensions

It's possible to access the Rownd state from within an app extension, like a widget. You'll need to include the Rownd package in the extension's dependencies and set up an app group for data sharing between the app and the extension. Without the app group, extensions will not be able to sync with your app's authentication state.

Follow these steps to configure your app and extension to work with Rownd:

1. Add an app group entitlement to both your app and any extensions that will use Rownd. This app group must be named like this: <prefix>.io.rownd.sdk. For example, if you work at a company with the acme.com domain, your app group might look like this: com.acme.app.io.rownd.sdk. Rownd will store its data in this app group. Your app should store data in a separate app group to prevent any collisions.

2. In your app's AppDelegate file as well as your extension's entry point, set the app group prefix you defined above via Rownd.config.appGroupPrefix = "<prefix>" (e.g., Rownd.config.appGroupPrefix = "com.acme.app")

3. In your extension, call Rownd.configure() prior to accessing authentication state. Here's an example:

    Task {
        Rownd.config.appGroupPrefix = "group.rowndexample"
        let rowndState = await Rownd.configure(appKey: "key_pko8eul59xz33hr21jgxvx6s")
   
        var authStatus: String = "You are not authenticated. ☹️"
        if rowndState.auth.isAuthenticated == true {
            authStatus = "You are authenticated! 😁"
        }
    }

If you're building widgets that need access to Rownd auth state, you should listen for Rownd auth events and notify `WidgetCenter` that widgets may need updating any time the state changes. That way, they'll re-render while your app is in the foreground and will show an accurate state. Here's a simple example: ```swift import Foundation import Combine import WidgetKit import Rownd

class SomeClass { private var authState = Rownd.getInstance().state().subscribe { $0.auth } private var cancellables = Set()

init() {
    self.authState
        .$current
        .sink { [weak self] state in
            WidgetCenter.shared.reloadAllTimelines()
        }
        .store(in: &cancellables)
}

}

</Note>

### Events

The Rownd SDK emits lifecycle events that you can listen to within your app. These events are primarily useful for detecting more granular aspects of a user's session (e.g., starting to sign in, completing sign-in, updated profile, etc.).

To listen to events, first create a class that conforms to the `RowndEventHandlerDelegate` protocol. It looks something like this:

```swift
import Foundation
import Rownd

class RowndEventHandler: RowndEventHandlerDelegate {
    func handleRowndEvent(_ event: RowndEvent) {
        switch event.event {
        case .signInCompleted:
            let userType = event.data?["user_type"]
            let appVariantUserType = event.data?["app_variant_user_type"]
            break

        default:
            break
        }
    }
}

Next, register the event handler delegate with the Rownd SDK:

Rownd.addEventHandler(RowndEventHandler())

Once the event handler is registered, it will receive events as they occur. The RowndEvent object contains the event type and any associated data. The event types are defined in the RowndEventType enum.

List of events

Here's a list of events that the Rownd SDK emits and the corresponding data that should be present in the event data dictionary. Remember to write your code defensively, as the data dictionary may be missing keys in some cases.

Event	Type	Payload
User started signing in	`.signInStarted`	```javascript { method: "google" | "apple" | "phone" | "email" | "passkey" | etc; } ``` </td> </tr> <tr> <td>User signed in successfully</td> <td>`.signInCompleted`</td> <td> ```javascript { method: "google" | "apple" | "phone" | "email" | "passkey" | etc, user_type: "new_user" | "existing_user", app_variant_user_type: "new_user" | "existing_user" | optional } ``` </td> </tr> <tr> <td>User sign in failed</td> <td>`.signInFailed`</td> <td> ```javascript { reason: String; } ``` </td> </tr>

API reference

In addition to the state observable APIs, Rownd provides imperative APIs that you can call to request sign in, get and retrieve user profile information, retrieve a current access token, or encrypt user data with the user's local key.

Rownd.requestSignIn() -> Void

Opens the Rownd sign-in dialog for authentication.

Rownd.requestSignIn(RowndSignInOptions(postSignInRedirect: "https://my-domain.com")) -> Void

Rownd.requestSignIn(RowndSignInOptions(postSignInRedirect: "https://my-domain.com", intent: .signIn)) -> Void

Opens the Rownd sign-in dialog for authentication, as above. When the user completes the authentication challenge via email or SMS, they'll be redirected to the URL set for postSignInRedirect. If this is a Universal Link, it will redirect the user back to your app.

Rownd.requestSignIn(with: RowndSignInHint) -> Void

Rownd.requestSignIn(with: RowndSignInHint, signInOptions: RowndSignInOptions?) -> Void

Requests a sign-in, but with a specific authentication provider (e.g., Sign in with Apple). Rownd treats this information as a hint. If the specified authentication provider is enabled within your Rownd app configuration, it will be honored. If not, Rownd will fall back to the default flow.

Supported values:

• .appleId - Prompt user to sign in with their Apple ID
• .google - Prompt user to sign in with their Google account
• .passkey - Prompt user to sign in with a passkey if they've previously set one up
• .guest - Sign in the user anonymously as a guest.

RowndSignInOptions

Some of the requestSignIn() methods accept an optional RowndSignInOptions parameter. This class contains the following properties:

• postSignInRedirect: String? (not recommended) - When the user completes the authentication challenge via email or SMS, they'll be redirected to the URL set for postSignInRedirect. If this is a Universal Link, it will redirect the user back to your app. If you don't set this value, the user will be redirected to your app's subdomain as configured in the Rownd dashboard.
• intent: RowndSignInIntent? - This option applies only when you have opted to split the sign-up/sign-in flow via the Rownd dashboard. Valid values are .signIn or .signUp. If you don't set this value, the user will be presented with the unified sign-in/sign-up flow.

Rownd.signOut() -> Void

Clears the user's access token, removes the user's profile data, and returns the user to a completely unauthenticated state.

Rownd.signOut(scope: RowndSignoutScope) -> Void

Revokes all tokens for the specified user causing them to be signed out on all devices.

Supported values:

• .all - All devices

Rownd.getAccessToken(throwIfMissing: Bool = false) async throws -> String?

Assuming a user is signed-in, returns a valid access token, refreshing the current one if needed.

By default, this function will return nil if an access token cannot be returned, either because the user is not signed in or because the refresh token is invalid.

If an access token cannot be returned due to a temporary condition (e.g., inaccessible network), this function will throw an AuthenticationError indicating the failure reason (e.g., server or network error).

You may also set throwIfMissing to true to force an error to be thrown if an access token cannot be returned. This will provide more granular reasons for the failure. The possible error cases for AuthenticationError are:

• .noAccessTokenPresent - the user is not signed in
• .invalidRefreshToken(details: String) - the refresh token was invalid (e.g., the token was expired, revoked, or a previous exchange failed to complete successfully). The user will be signed out.
• .networkConnectionFailure(details: String) - a network condition prevented the token from being refreshed, even after several retries and should be re-attempted later
• .serverError(details: String) - an error occurred on the server and you should try again later

Example:

    do {
        let accessToken = try await Rownd.getAccessToken(throwIfMissing: true)
    } catch {
        switch error {
        case AuthenticationError.noAccessTokenPresent:
            // The user is not signed in
        case AuthenticationError.invalidRefreshToken(let details):
            // The refresh token was invalid. Request that the user sign in again.
        case AuthenticationError.networkConnectionFailure(let details),
             AuthenticationError.serverError(let details):
            // Alert the user that they should try again due to some recoverable error
            print("Server error occurred: \(details)")
        }
    }

Rownd.getAccessToken(_ token: String) async -> String?

When possible, exchanges a non-Rownd access token for a Rownd access token. This is primarily used in scenarios where an app is migrating from some other authentication mechanism to Rownd. Using Rownd integrations, the system will accept a third-party token. If it successfully validates, Rownd will sign-in the user and return a fresh Rownd access token to the caller.

This API returns nil if the token could not be validated and exchanged. If that occurs, it's likely that the user should sign-in normally via Rownd.requestSignIn().

NOTE: This API is typically used once. After a Rownd token is available, other tokens should be discarded. Example:

    // Assume `oldToken` was retrieved from some prior authenticator.
    let accessToken = await Rownd.getAccessToken(oldToken)
    if (accessToken != nil) {
        // Navigate to the UI that a user should typically see
    } else {
        Rownd.requestSignIn()
    }

Rownd.user.get() -> Dictionary<String, AnyCodable>

Returns the entire user profile as a dictionary object

Rownd.user.get<T>(field: String) -> T?

Returns the value of a specific field in the user's data dictionary. "id" is a special case that will return the user's ID, even though it's technically not in the dictionary itself.

Your application code is responsible for knowing which type the value should cast to. If the cast fails or the entry doesn't exist, a nil value will be returned.

Rownd.user.set(data: Dictionary<String, AnyCodable>) -> void

Replaces the user's data with that contained in the dictionary. This may overwrite existing values, but must match the schema you defined within your Rownd application dashboard. Any fields that are flagged as encrypted will be encrypted on-device prior to storing in Rownd's platform.

Hint: use AnyCodable.init(value) to conform your values to the required type.

Rownd.user.set(field: String, value: AnyCodable) -> void

Sets a specific user profile field to the provided value, overwriting if a value already exists. If the field is flagged as encrypted, it will be encrypted on-device prior to storing in Rownd's platform.

Hint: use AnyCodable.init(value) to conform your values to the required type.

Using Rownd with WKWebView

Registering a WKWebView with Rownd

The registerWebView method enables communication between the Rownd JavaScript SDK and native Rownd iOS SDK.

Why Use registerWebView?

You should call registerWebView() with any web view that loads content containing the Rownd JavaScript SDK. This binding is required for certain operations like signing in with Google, where Google prohibits OAuth2 sign-in from within a web view. Once registered, the web view JavaScript SDK can send messages to the Swift code to perform sign-in with Google natively.

Method Signature

public static func registerWebView(_ webView: WKWebView) -> () -> Void

• Parameter: webView - The WKWebView instance you want to register with Rownd.
• Returns: A closure that can be called to deregister the web view when it's no longer needed.

Example Usage

Here's an example of how you might use registerWebView in your app:

import UIKit
import WebKit
import Rownd

class WebViewController: UIViewController {
    var webView: WKWebView!
    var deregisterWebView: (() -> Void)?

    override func viewDidLoad() {
        super.viewDidLoad()

        webView = WKWebView(frame: self.view.bounds)
        self.view.addSubview(webView)

        // Register the web view with Rownd
        deregisterWebView = Rownd.registerWebView(webView)

        // Load a URL that uses the Rownd JavaScript SDK
        if let url = URL(string: "https://your-web-app.com") {
            webView.load(URLRequest(url: url))
        }
    }

    deinit {
        // Deregister the web view when the view controller is deallocated
        deregisterWebView?()
    }
}

The example creates a WKWebView and registers it with Rownd. The web view loads a URL containing the Rownd JavaScript SDK. When the view controller deallocates, it calls the deregisterWebView closure to clean up the registration.