JavaScript

The Rownd SDK for JavaScript enables seamless user authentication and profile management directly in the browser. This client-side SDK allows you to:

Authenticate users without requiring a backend server
Securely store and manage user profile information
Customize the authentication flow to match your needs
Handle user sessions and access tokens automatically
Do it all with a simple, easy-to-implement code snippet

Getting started

Get the Rownd Javascript code-snippet from the Rownd dashboard.

Copy
// EXAMPLE ONLY--THIS WON'T WORK IN A REAL APP
<script type="text/javascript">
!function(){var e=window._rphConfig=window._rphConfig||[];let t=window.localStorage.getItem("rph_base_url_override")||"https://hub.rownd.io";e.push(["setBaseUrl",t]);var r=document,s=r.createElement("script")=r.getElementsByTagName("script")[0];s.type="text/javascript",s.async=!0,s.src=t+"/static/scripts/rph.js",a&amp;&amp;a.parentNode?a.parentNode.insertBefore(s,a):r.body.appendChild(s)}();
</script>

Add the snippet to your website. If you’re using a CMS (e.g., WordPress, Webflow, Wix, etc.), you can typically add the snippet through the “settings” portion of their editors.

If you’re testing locally or want to add the snippet directly to your site code, add the snippet to your main layout or template HTML file. Ideally, add the snippet just before the closing </body> tag.

Deploying the Snippet to hosted websites

After copying the code snippet, you’ll need to add it to your website(s). Most website builder software or content management systems (CMS) have an option to embed “custom HTML” or “custom code” in your site’s pages. We usually recommend placing the snippet just before the closing </body> tag.

Here are links to instructions for a few popular hosting providers. See our JavaScript SDK reference for more details.

Netlify
Squarespace
Webflow
Weebly (see the section on “footer code”)
Wix
WordPress

At this point, if you load your site in a browser after saving or publishing, you should see the Rownd Hub appear in the lower left-hand corner of the site.

If you’re building a single-page app in React, Vue, etc, then use our framework-specific SDKs instead of these instructions.

If your single-page app is separate from your website, then you’ll want to use the instructions on this page for the website and the framework SDK instructions for the single-page app.

If you find any of this unclear, get in touch with us and we can help you figure out which pieces you’ll need.

Advanced

The following sections require some level of development knowledge

Configuring Rownd Behavior

The behavior of Rownd and Rownd’s UI components is configurable by appending configuration parameters to the global _rphConfig object.

To set a config parameter, add an additional script block after the main Rownd snippet. The important thing to see here is the call to _rphConfig.push().

Copy
<script type="text/javascript">
  _rphConfig.push(["set<config_variable_name>", "<value>"]);
</script>

Configuration Parameters

setAppKey

The publishable key for your Rownd application. See App Credentials

This is usually part of the snippet obtained from the Rownd dashboard, so you don’t need to set it here.

Example
Copy
_rphConfig.push(["setAppKey", "82f7fa9a-8110-416c-8cc8-e3c0506fbf93"]);

setPostLoginRedirect

Sets the URL to redirect to after a user signs in. This can be an absolute or relative URL. If not provided, the user will simply remain on the current page.

Example
Copy
_rphConfig.push(["setPostLoginRedirect", "https://app.rownd.io"]);

setPostRegistrationRedirect

Sets the URL to redirect to after a user signs in for the first time. This can be an absolute or relative URL. If not provided, the user will simply remain on the current page.

Example
Copy
_rphConfig.push(["setPostRegistrationRedirect", "https://app.rownd.io/post-registration"]);

setPostAuthenticationApi

Rownd will call this API after an authenticated session is established. This can happen directly after a sign-in, or when the page is reloaded with a currently authenticated user.

url

string

The URL that Rownd will call

method

string

The HTTP method that Rownd will use. Can be either "post", "put", or "get".

extra_headers

object

A map of key-value pairs that Rownd will include in the HTTP headers

If you specify a "put" or "post" method, the access token will be included in the request body as a field named access_token. For an HTTP "get", it is included in the Authorization header.

There are two properties that Rownd looks for in the response body that drive behavior when thhe API call completes.

return_to

A relative path or URL to which Rownd will redirect

should_refresh_page

If true, Rownd will refresh the current page

Example
Copy
_rphConfig.push(["setPostAuthenticationApi",
  {
    method: "post",
    url: "https://api.acme.com/authenticate",
    extra_headers: {
      extra: "value"
    },
    timeout: 3000 // 3s
  }
]);

setPostSignOutApi

Rownd will call this API after an authenticated session is terminated by calling rownd.signOut().

url

string

The URL that Rownd will call

method

string

The HTTP method that Rownd will use. Can be either "post" or "put".

extra_headers

object

A map of key-value pairs that Rownd will include in the HTTP headers

There are two properties that Rownd looks for in the response body that drive behavior when thhe API call completes.

return_to

A relative path or URL to which Rownd will redirect

should_refresh_page

If true, Rownd will refresh the current page

Example
Copy
_rphConfig.push(["setPostSignOutApi",
  {
    method: "post",
    url: "https://api.acme.com/sign-out",
    extra_headers: {
      extra: "value"
    },
  }
]);

setPostSignOutCallback

Rownd will invoke this function after an authenticated session is terminated by calling rownd.signOut().

Example
Copy
_rphConfig.push(["setPostSignOutCallback", function () {
  console.log('User signed out')
}]);

setPostUserDataUpdateApi

Rownd will call this API after an event happens that causes the user's profile data to change. Examples of these events include a call to rownd.user.set(), rownd.user.setValue(), and sign-in completions where data is saved. The new user data will be included in the request body property named user_data.

url

string

The URL that Rownd will call

method

string

The HTTP method that Rownd will use. Can be either "post" or "put".

extra_headers

object

A map of key-value pairs that Rownd will include in the HTTP headers

There are two properties that Rownd looks for in the response body that drive behavior when thhe API call completes.

return_to

A relative path or URL to which Rownd will redirect

should_refresh_page

If true, Rownd will refresh the current page

Example
Copy
_rphConfig.push(["setPostUserDataUpdateApi",
  {
    method: "post",
    url: "https://api.acme.com/user_data_update",
    extra_headers: {
      extra: "value"
    },
  }
]);

setRootOrigin

If you're using the same Rownd application across multiple domains (e.g., rownd.io and app.rownd.io), set this to the "root" origin (e.g., https://rownd.io).

Example
Copy
_rphConfig.push(["setRootOrigin",  "https://acme.com"]);

setLogLevel

Sets the log level for the Rownd Hub. Valid values are "error", "warn", "info", "debug", and "trace".

Example
Copy
_rphConfig.push(["setRootOrigin",  "trace"]);

Programmatic API

In addition to the declarative markup described above, you can use the Rownd Hub’s programmatic API to create more advanced functionality.

The `rownd` object

Once the Rownd Hub initializes, it will place a rownd property on the global Window object. All JS APIs are available on this object. Check out the JavaScript API reference documentation for a comprehensive view of the API.

Before calling methods or accessing data on the Rownd API, you’ll need to wait for the API to be ready. Start by adding a function to the configuration’s onLoaded event, like this:

You can interact with the Rownd JS Api

Copy
<script type="text/javascript">
_rphConfig.push(['onLoaded', () => {
  // window.rownd should be available now!
  console.log(window.rownd);
}]);
</script>

Events

The Rownd Hub emits various events when state changes occur. For example, initial authentication, updates to user data, etc. You can listen for these event changes and react to them.

This event fires when a user has completed the sign in process.

method

string

required

The method used to sign in. Can be one of "google", "apple", "phone", "email", "passkey", or "anonymous".

user_type

string

required

The type of user that signed in. Can be either "new_user" or "existing_user".

app_variant_user_type

string

The type of user that signed in for the current app variant. Can be either "new_user" or "existing_user".

app_variant_user_type will be released in early 2025

This event fires when a user’s sign in attempt fails.

reason

string

required

The reason the sign in failed.

`auth`

This event fires any time the user moves from an unauthenticated state to an authenticated state. It will also fire any time the access token is refreshed.

access_token

string

required

The user’s access token that can be used to authenticate API requests.

user_id

string

required

The unique identifier for the authenticated user.

app_id

string

required

The ID of the Rownd application.

`sign_out`

This event fires whenever a user is signed out.

`user_data`

This event fires any time a user’s profile data changes. This could fire due to calls to rownd.user.set(), rowns.user.setValue(), changes to profile data in the Rownd Hub UI, or due to data changes when authenticating.

data

object

required

The user’s updated profile data.

Hooks

With the JavaScript SDK installed, you can use all of the HTML hooks described in the HTML Hooks documentation.

Get Started

Mobile

Web

Backend / Server

Getting started

Deploying the Snippet to hosted websites

Advanced

Configuring Rownd Behavior

setAppKey

setPostLoginRedirect

setPostRegistrationRedirect

setPostAuthenticationApi

setPostSignOutApi

setPostSignOutCallback

setPostUserDataUpdateApi

setRootOrigin

setLogLevel

Programmatic API

The `rownd` object

Events

`auth`

`sign_out`

`user_data`

Hooks

Get Started

Mobile

Web

Backend / Server

​Getting started

​Deploying the Snippet to hosted websites

​Advanced

​Configuring Rownd Behavior

​setAppKey

​setPostLoginRedirect

​setPostRegistrationRedirect

​setPostAuthenticationApi

​setPostSignOutApi

​setPostSignOutCallback

​setPostUserDataUpdateApi

​setRootOrigin

​setLogLevel

​Programmatic API

​The `rownd` object

​Events

​sign_in_completed

​sign_in_failed

​auth

​sign_out

​user_data

​Hooks

Getting started

Deploying the Snippet to hosted websites

Advanced

Configuring Rownd Behavior

setAppKey

setPostLoginRedirect

setPostRegistrationRedirect

setPostAuthenticationApi

setPostSignOutApi

setPostSignOutCallback

setPostUserDataUpdateApi

setRootOrigin

setLogLevel

Programmatic API

The `rownd` object

Events

`sign_in_completed`

`sign_in_failed`

`auth`

`sign_out`

`user_data`

Hooks