Skip to main content

Integrating Privy on mobile

Native mobile support is a key part of our roadmap. Privy is already built to work in mobile web. We do not currently offer native mobile SDKs.

Supporting native mobile frameworks is a key part of our roadmap. This includes support for:

  • React Native & Expo
  • Native iOS (Swift) & Android (Kotlin)
  • Flutter

Here are some best practices below for integrating Privy into your mobile app.

Integrating Privy with a mobile website​

tip

This is the recommended approach for integrating Privy with a mobile experience.

Privy works out-of-the-box for mobile web. Put simply, there is no additional work required to configure Privy to work in the mobile browser. Privy’s SDK and UI components are mobile-friendly and responsive. As long as your site works in the mobile browser, you can leverage the full capabilities of Privy, including:

  • authenticating your users
  • prompting your users to link additional accounts
  • requesting signatures and transactions from your user’s external wallets
  • creating and using embedded wallets
note

Wallet providers are generally less supportive of mobile environments, and can be more unreliable. We are constantly working to ensure reliability on mobile. If you run into any issues, please reach out at [email protected].

Integrating Privy with a mobile app​

info

Native mobile SDKs and a fully configurable (headless) JavaScript SDK are coming. These will be the preferred method for integrating Privy into your mobile app.

The below is a way to support limited Privy functionality in your mobile app today.

Depending on your needs, it may also possible to use Privy to authenticate your users with a mobile app, instead of in a website in the mobile browser.

There are some known limitations to this integration; namely, you will not be able to use the @privy-io/react-auth SDK, and will instead need to consume our APIs directly. This means that the following Privy features will not be available in your app today:

  • automatic management of a user’s authentication state and user object
  • linking additional accounts (email, SMS, wallet, socials)
  • using embedded wallets
  • requesting signatures and transactions from external wallets

At a high-level, to integrate Privy with a mobile app, you must:

  • set up a separate website where users can login with Privy in their mobile browser
  • when a user attempts to login to your mobile app, redirect them to your website in the mobile browser
  • once a user has successfully logged in in the mobile browser, redirect them back to your mobile app, and pass the user’s authentication details along with them.

Below is a sketch of what this integration might look like. If you are actively planning to integrate Privy with a mobile app, please reach out to our team so we can tailor the integration to work best for your app.

1. Set up a mobile website for login and onboarding​

  • Separately from your mobile app, set up a simple website page that integrates Privy to guide your user through an onboarding flow on mobile. You will use this to log your user in via mobile web and use the tokens in your mobile app. In particular, this page should prompt your user to login, link- any additional accounts you need from them, and connect any external wallets or create an embedded wallet if needed.
  • Once a user has successfully logged in through your website page on their mobile device, get the user’s Privy auth tokens. Privy issues each user two tokens (an access token and a refresh token), and stores them in the browser’s local storage. You can:
    • get the access token via localStorage.get('privy:token')
    • get the refresh token via localStorage.get('privy:refresh_token').
  • Once a user has successfully logged in to your website page, and you are able to access their Privy auth tokens, show them a deeplink back to your mobile app.
    • Within this deeplink, append the user’s access token and refresh token as URL params.
    • For example, if your app’s deeplink protocol is myapp:// and you want to send them to your app’s home page, your deeplink might look like myapp://home?accessToken=<insert-access-token>&refreshToken=<insert-refresh-token>

2. Configure your app to authenticate users through your mobile website​

  • Configure your mobile app such that when a user attempts to log in (e.g. by clicking a login button), you deeplink the user to the website you set up in step (1) in their mobile browser.

3. Manage the user's authentication state within your app​

Once your user completes the login flow in your mobile website, they will be deeplinked back to your app. Parse the URL params to retrieve the user’s access token and refresh token, and then store these tokens in your app storage.

To keep your user authenticated within your app, you must recurrently refresh their auth tokens.

  • Privy issues each user two tokens: an access token (valid for 1h) and a refresh token (valid for 30d)
  • You can consider a user authenticated if they have a valid, unexpired access token.
  • If a user’s access token is expired, you can refresh it as long as the user still has a valid refresh token.
    • You can do so by querying Privy’s API with the user’s refresh token and expired access token.
    • Once queried, the API will return a new pair of valid tokens for the user. You should save these in your app storage and overwrite the old tokens.
    • Note that:
      • If the user’s access token is still valid, the API will return the same (not a refreshed) pair of access token & refresh token.
      • If the user’s refresh token is invalid (after 30 days or after it’s been used to refresh), the API will return an error, and the user must log in again to get a new pair of valid tokens.
curl --location 'https://auth.privy.io/api/v1/sessions' \
--header 'privy-app-id: <insert-your-privy-app-id>' \
--header 'Authorization: Bearer <insert-the-expired-access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "refresh_token": "<insert-the-refresh-token>"
}'

You can choose to refresh a user’s auth tokens either:

  • On a schedule. Privy’s access tokens expire every hour, so you can set up a background job in your app that requests Privy’s API on a less-than-hourly basis to refresh their auth tokens.
  • Just in time. When you detect that a user’s access token is expired (e.g. when authorizing a request to your backend), you can then trigger a request to Privy’s API to refresh their auth tokens.