React
React SDK reference
Installation
Simply run npm install @rownd/react
or yarn add @rownd/react
.
Usage
The library provides a React provider and hook for the Rownd browser API.
In your app’s main entrypoint, add the Rownd provider, likely before other providers:
The Rownd React SDK automatically injects the Rownd Hub snippet into your React application, so you should not manually include the Hub snippet in your HTML page. Doing so will produce unexpected results.
Provider props
-
appKey
(required): This is the key generated by the Rownd dashboard. -
postLoginRedirect
(optional): Where the browser should redirect the user after a successful sign-in. If not supplied, the user will remain on the same page. -
rootOrigin
(optional): If you’re using Rownd across multiple domains (e.g.,rownd.io
andapp.rownd.io
), set this to the “root” origin (e.g., https://rownd.io).
Later on within your app’s components, you can use the Rownd hook to access the Rownd browser API:
Usage with redux, etc
Often, sending and receiving data from your server will rely on the Rownd access token as a means of authenticating the user within your back-end (see our Node.js SDK as an example of this). Many React apps leverage Redux or similar technologies to manage an app’s global state.
The key here is to call Rownd’s getAccessToken({ waitForToken: true })
method
when calling your own authenticated APIs. For example, if you’re using
axios, you’d likely set up an interceptor
that looks something like this:
Here’s another example, this time using ky:
In both of the cases above, our async actions would use these instances of axios or ky to make requests back to the server, but before any of those fire, we need to set the access token helper from our React app like this:
That’s one way to solve this problem. Another might be to wrap the redux
provider in your own component and simply pass the getAccessToken
function
down into the store during initialization. If you come up with a better
mousetrap here, let us know!
API reference
Most API methods are made available via the Rownd Provider and its associated
useRownd
React hook. Unless otherwise noted, we’re assuming that you’re using
hooks.
requestSignIn()
Trigger the Rownd sign in dialog
-
auto_sign_in: boolean
- whentrue
, automatically trigger a sign-in attempt ifidentifier
is included or an email address or phone number has already been set in the user data. -
identifier: string
- an email address or phone number (in E164 format) to which a verification message may be sent. If the Rownd app is configured to allow unverified users, then sign-in will complete without verification if the user has not signed in previously.
signOut()
Sign out the user and clear their profile, returning them to a completely unauthenticated state.
getAccessToken()
Retrieves the active, valid access token for the current user.
waitForToken: boolean
- whentrue
, if no access token is present or if it’s expired, the promise will not resolve until a valid token is available. While unlikely, this could result in waiting forever.
is_initializing
is_initializing
will be true
until the Hub has fully loaded, recalled its
state, and resolved the current user’s authentication status. This usually takes
only a few milliseconds, but if you make decisions that depend on the
is_authenticated
flag while is_initializing
is still true
, your code/logic
may not work as you expect.
is_authenticated
access_token
Represents the current access token for the user.
user
Represents information about the current user, specifically their profile
information. In the example below, we use the existing data to display the
current value of first_name
in a form field, update a local copy of that data
as the user changes it, and then save the changes to Rownd once the user submits
the form.
setUser
The setUser
function allows you to update a user’s profile information within the Rownd platform. You can modify user attributes such as first_name
, last_name
, and other properties by passing an object with the relevant fields.
setUserValue
The setUserValue
function allows you to update a specific attribute of the user’s profile within the Rownd platform. Instead of passing an entire user object, you can update individual fields by specifying the key (attribute name) and value.
manageAccount()
The manageAccount()
function allows users to view and update their profile information within the Rownd platform. This function opens the user’s account management interface, where they can review and modify personal details such as their name, email, and other profile attributes.
passkeys
Rownd offers passkey-based authentication, allowing users to create and authenticate using a secure passkey. The register
function starts the process of creating a new passkey for the user, while the authenticate
function validates an existing passkey to authenticate the user.
RequireSignIn
The RequireSignIn
component is a wrapper that triggers the sign-in process when the component it wraps is rendered. It ensures that the user is signed in before accessing the content of the wrapped component. If the user is not authenticated, the sign-in process will automatically begin when the component mounts.
SignedIn
The SignedIn
component is used to conditionally render its children only when the user is authenticated. If the user is not signed in, the wrapped content will not be displayed.
SignedOut
The SignedOut
component is the counterpart to SignedIn
. It renders its children only when the user is not authenticated. If the user is signed in, the wrapped content will not be displayed.