You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**💡 Major Refactor**: Version 5.0 features a complete architectural overhaul for improved performance, maintainability, and multi-platform extensibility. Check the [Migration Guide](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md) for detailed upgrade instructions.
8
+
9
+
**⚠️ BREAKING CHANGES**
10
+
11
+
- feat: architectural refactor for multi-platform extensibility [\#1233](https://github.com/auth0/react-native-auth0/pull/1233) ([subhankarmaiti](https://github.com/subhankarmaiti))
- feat: added react native web support [\#1233](https://github.com/auth0/react-native-auth0/pull/1233) ([subhankarmaiti](https://github.com/subhankarmaiti))
17
+
18
+
**Changed**
19
+
20
+
- feat(deps): Upgrade React Native to 0.80.1 [\#1237](https://github.com/auth0/react-native-auth0/pull/1237) ([subhankarmaiti](https://github.com/subhankarmaiti))
21
+
22
+
**Fixed**
23
+
24
+
- fix(iOS): Fix ephemeralSession parameter type conversion in webAuth [\#1238](https://github.com/auth0/react-native-auth0/pull/1238) ([subhankarmaiti](https://github.com/subhankarmaiti))
Copy file name to clipboardExpand all lines: FAQ.md
+75Lines changed: 75 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,8 @@
9
9
7.[Auth0 web browser gets killed when going to the background on Android](#7-auth0-web-browser-gets-killed-when-going-to-the-background-on-android)
10
10
8.[How to resolve the _Failed to start this transaction, as there is an active transaction at the moment_ error?](#8-how-to-resolve-the-failed-to-start-this-transaction-as-there-is-an-active-transaction-at-the-moment-error)
11
11
9.[How can I prevent the autogenerated redirect_uri from breaking if the applicationId has mixed cases or special characters in it on Android?](#9-how-can-i-prevent-the-autogenerated-redirect_uri-from-breaking-if-the-applicationId-has-mixed-cases-or-special-characters-in-it-on-android)
12
+
10.[Why doesn't `await authorize()` work on the web? How do I handle login?](#10-why-doesnt-await-authorize-work-on-the-web-how-do-i-handle-login)
13
+
11.[Why do my users get logged out frequently? How do I keep them logged in?](#11-why-do-my-users-get-logged-out-frequently-how-do-i-keep-them-logged-in)
12
14
13
15
## 1. How can I have separate Auth0 domains for each environment on Android?
14
16
@@ -262,3 +264,76 @@ If you don't need SSO, consider using `ephemeral sessions` or `SFSafariViewContr
262
264
## 9. How can I prevent the autogenerated redirect_uri from breaking if the applicationId has mixed cases or special characters in it on Android ?
263
265
264
266
It is recommended to have your applicationId in lower case without special characters to prevent any mismatch with the generated redirect_uri. But in the scenario where you require your applicationId to be of mixed case, to avoid any mismatch , the user can pass a `redirectUri` which matches the one provided in the manage dashboard as part of the `AgentLoginOptions` property.
267
+
268
+
## 10. Why doesn't `await authorize()` work on the web? How do I handle login?
269
+
270
+
This is a key difference between native and web platforms.
271
+
272
+
-**On Native (iOS/Android):**`authorize()` opens an in-app browser overlay. Your app continues running in the background. When the user authenticates, the browser dismisses and the `authorize()` promise resolves with the credentials. `await` works as expected.
273
+
274
+
-**On Web:**`authorize()` triggers a **full-page browser redirect** to the Auth0 Universal Login page. Your application's current state is lost. After authentication, the user is redirected back to your app, which causes your entire React application to reload and re-initialize from scratch. Because of this, the original `authorize()` promise is never able to resolve.
275
+
276
+
**The Solution: Use the `useAuth0` Hook**
277
+
278
+
The recommended way to handle this is by using the `Auth0Provider` and `useAuth0` hook. They are designed to manage this flow automatically:
279
+
280
+
1.**On initial load:** The provider checks if the user is returning from a login redirect. If so, it processes the credentials in the URL and establishes a session.
281
+
2.**State Management:** The `user` and `isLoading` properties from the `useAuth0` hook will automatically update to reflect the authenticated state after the redirect is handled.
282
+
283
+
Your UI should be reactive to the `user` and `isLoading` state, rather than trying to `await` the result of `authorize()`.
284
+
285
+
```jsx
286
+
import { useAuth0 } from'react-native-auth0';
287
+
288
+
constMyComponent= () => {
289
+
const { authorize, user, isLoading } =useAuth0();
290
+
291
+
// This component will re-render after the redirect,
292
+
// and `user` will be populated.
293
+
if (isLoading) {
294
+
return<Text>Loading...</Text>;
295
+
}
296
+
297
+
return (
298
+
<View>
299
+
{user ? (
300
+
<Text>Welcome, {user.name}!</Text>
301
+
) : (
302
+
<Button
303
+
title="Log In"
304
+
onPress={async () => {
305
+
// This will trigger the redirect. No need to `await`.
306
+
awaitauthorize();
307
+
}}
308
+
/>
309
+
)}
310
+
</View>
311
+
);
312
+
};
313
+
```
314
+
315
+
## 11. Why do my users get logged out frequently? How do I keep them logged in?
316
+
317
+
If your users are being asked to log in again after a short period (e.g., when they close and reopen the app), it's likely because the SDK cannot silently refresh their tokens.
318
+
319
+
The `getCredentials()` method is responsible for retrieving tokens. If the `accessToken` is expired, it will attempt to get a new one using a `refreshToken`. This process happens silently without requiring user interaction.
320
+
321
+
To enable this, you **must** request the `offline_access` scope during the initial login. This scope is what signals to Auth0 that you want to receive a `refreshToken`.
322
+
323
+
**The Solution: Add the `offline_access` Scope**
324
+
325
+
When calling `authorize`, ensure you include `offline_access` in the scope string.
326
+
327
+
```javascript
328
+
import { useAuth0 } from'react-native-auth0';
329
+
330
+
const { authorize } =useAuth0();
331
+
332
+
consthandleLogin=async () => {
333
+
awaitauthorize({
334
+
scope:'openid profile email offline_access', // <-- Add this scope
335
+
});
336
+
};
337
+
```
338
+
339
+
By including this scope, the SDK will receive and securely store a `refreshToken`. This token will then be used by `getCredentials()` to maintain the user's session across app launches, providing a much smoother user experience.
The `Credentials` object no longer includes `expiresIn` (a duration). It now provides `expiresAt`, an absolute **UNIX timestamp** (in seconds), making expiration checks simpler and less error-prone.
79
-
80
-
**✅ Action Required:** Replace all logic using `expiresIn` with `expiresAt`.
// Or, use the new helper method (if you have an instance of the Credentials model):
100
-
if (credentials.isExpired()) {
101
-
// ...
102
-
}
103
-
```
104
-
105
-
### Change #3: Standardized `AuthError` Object
76
+
### Change #2: Standardized `AuthError` Object
106
77
107
78
All errors thrown by the library are now instances of a single, consistent `AuthError` class. This replaces multiple error types like `CredentialsManagerError`.
108
79
@@ -130,32 +101,73 @@ catch (e) {
130
101
}
131
102
```
132
103
133
-
### Change #4: Updated `authorize` and `clearSession` Signatures
104
+
### Change #3: Platform-Specific API Availability
105
+
106
+
With the introduction of **React Native Web support**, some methods are only available on native platforms forsecurity reasons. Direct authentication grants that handle user credentials (like passwords or OTP codes) are **not supportedin the browser** and will throw a `NotImplemented` error.
107
+
108
+
**✅ Action Required:** If you are building forthe web, ensure all authentication flows are initiated via the redirect-based `authorize()` method. Review the platform support tablein the [README](README.md#features-and-platform-support) for a full list of platform-specific methods.
109
+
110
+
### Change #4: `authorize()` Behavior on Web
134
111
135
-
For improved clarity, SDK-specific options (like `ephemeralSession`) have been moved into a separate, second `options` object.
112
+
On React Native Web, the `authorize()` method now triggers a **full-page redirect** to Auth0. As a result, the promise returned by `authorize()` will **not resolve**in the browser. Your application must be structured to handle the user state upon reloading after the redirect.
136
113
137
-
**✅ Action Required:** Restructure calls to `authorize` and `clearSession`.
114
+
**✅ Action Required:** Review the new **[FAQ entry](#faq-authorize-web)** for guidance on how to correctly handle the post-login flow on the web. The `Auth0Provider` and `useAuth0` hook are designed to manage this flow automatically.
115
+
116
+
### Change #5: New Peer Dependency for Web Support
117
+
118
+
To support the web platform, the library now has an **optional peer dependency** on `@auth0/auth0-spa-js`.
119
+
120
+
**✅ Action Required:** If you are using `react-native-auth0`in a React Native Web project, you **must** install this package. Native-only projects can ignore this.
121
+
122
+
```bash
123
+
npm install @auth0/auth0-spa-js
124
+
```
125
+
126
+
### Change #6: Hook Methods Now Throw Error
127
+
128
+
Previously, all hook-related methods such as `getCredentials()`, `saveCredentials()`, etc., did not throw error directly. Instead, any issues were silently handled and surfaced via the error property in`useAuth0()`:
129
+
130
+
```javascript
131
+
const { error } = useAuth0();
132
+
// error would be populated if getCredentials failed
133
+
```
134
+
135
+
**What's Changed:**
136
+
137
+
These methods now throw error directly to the caller. You must handle them explicitly using try...catch blocks.
138
+
139
+
**✅ Action Required:** Update your code to handle error for each function call individually.
138
140
139
141
**Before:**
140
142
141
143
```javascript
142
-
// Mixed parameters and options
143
-
await authorize({
144
-
scope: 'openid profile',
145
-
ephemeralSession: true,
146
-
});
144
+
const { getCredentials, error } = useAuth0();
145
+
---
146
+
await getCredentials();
147
+
// Check error manually later
147
148
```
148
149
149
150
**After:**
150
151
151
152
```javascript
152
-
// Parameters and options are now separate arguments
This guide provides instructions for using React Native Auth0 with React Native Web.
4
+
5
+
## What is React Native Web?
6
+
7
+
React Native Web is a library that provides React Native components and APIs that are compatible with React and the web. It allows you to write your application once using React Native and run it on iOS, Android, and web platforms.
8
+
9
+
**Official React Native Web Repository:**https://github.com/necolas/react-native-web
10
+
11
+
## Setup Instructions
12
+
13
+
If you want to use React Native Web with React Native Auth0, follow these steps:
14
+
15
+
### 1. Install React Native Web
16
+
17
+
Follow the official React Native Web installation guide:
React Native Auth0 requires `@auth0/auth0-spa-js` for web platform support:
23
+
24
+
```bash
25
+
# Using npm
26
+
npm install @auth0/auth0-spa-js
27
+
28
+
# Using yarn
29
+
yarn add @auth0/auth0-spa-js
30
+
```
31
+
32
+
### 3. Use React Native Auth0
33
+
34
+
Once React Native Web and Auth0 SPA JS are installed, you can use React Native Auth0 exactly as you would in a native React Native app. The library will automatically detect the web platform and use the appropriate implementation.
- React Native Auth0 automatically detects when running on web and uses the Auth0 SPA JS library under the hood
61
+
- All React Native Auth0 APIs work the same across platforms (iOS, Android, and Web)
62
+
- For web-specific examples, see the [EXAMPLES-WEB.md](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES-WEB.md) file in this repository
0 commit comments