Rownd bindings for native iOS apps
AppDelegate
file, call the Rownd.configure()
method during application launch:
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.
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.
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) - Replace Rownd’s use of the system default loading spinner (i.e., UIActivityIndicatorView
or ProgressView
) with a custom animation. 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
)
RowndCustomizations
class. Here’s an example:
<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.
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"
)
Rownd.configure()
prior to accessing authentication state. Here’s an example:
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:Rownd.configure()
. These options are available via the Rownd.config
object.
enableSmartLinkPasteBehavior: Bool
(default: true
) - Attempts to access the clipboard for smart link pasting behavior if it contains a URL. This will trigger a system alert asking for permission to access the clipboard. If you don’t want this behavior, set this to false
.RowndEventHandlerDelegate
protocol. It looks something like this:
RowndEvent
object contains the event type and any associated data. The event types are defined in the RowndEventType
enum.
Event | Type | Payload |
---|---|---|
User started signing in | .signInStarted | |
User signed in successfully | .signInCompleted | |
User sign in failed | .signInFailed |
Rownd.requestSignIn() -> Void
Rownd.requestSignIn(RowndSignInOptions(postSignInRedirect: "https://my-domain.com")) -> Void
Rownd.requestSignIn(RowndSignInOptions(postSignInRedirect: "https://my-domain.com", intent: .signIn)) -> Void
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
.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
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. If you don’t set this value, the user will be presented with the unified sign-in/sign-up flow.
Rownd.signOut() -> Void
Rownd.signOut(scope: RowndSignoutScope) -> Void
.all
- All devicesRownd.getAccessToken(throwIfMissing: Bool = false) async throws -> String?
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 laternil
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:
user_id
to obtain the user’s unique ID, which is always a string.
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.
AnyCodable.init(value)
to conform your values to the required type.
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.