Docs Menu

Docs HomeDevelop ApplicationsAtlas Device SDKs

AppProvider (@realm/react)

On this page

  • Props
  • Configure AppProvider
  • Hooks Used with AppProvider
  • useAuth()
  • result
  • logIn(credentials)
  • logInWithAnonymous()
  • logInWithApiKey(key)
  • logInWithEmailPassword(credentials)
  • logInWithJWT(credentials)
  • logInWithGoogle(credentials)
  • logInWithApple(idToken)
  • logInWithFacebook(accessToken)
  • logInWithFunction(payload)
  • logOut()
  • useEmailPasswordAuth()
  • logIn(credentials)
  • logOut()
  • register(args)
  • confirm(args)
  • resendConfirmationEmail(args)
  • retryCustomConfirmation(args)
  • sendResetPasswordEmail(args)
  • resetPassword(args)
  • callResetPasswordFunction(args, restArgs)
  • useApp()
Type signature
AppProvider(props, context?): null | ReactElement<any, any>

Components nested within AppProvider can access your App Services App and use the AppProvider hooks.

All properties of AppConfiguration can be passed as props to AppProvider.

To set up your App client, pass the App ID string to the id prop of the AppProvider. Wrap any components that need to access the App with AppProvider.

import React from 'react';
import {AppProvider} from '@realm/react';
function AppWrapper() {
return (
<View>
<AppProvider id={APP_ID}>
<MyApp />
</AppProvider>
</View>
);
}

You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.

Important

Changing an App Config After Initializing the App

Changed in version realm@12.6.0: baseUrl is not cached

When you initialize the App client, the configuration is cached internally. Attempting to "close" and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

Starting with React Native SDK version 12.6.0, the baseUrl in the AppConfiguration is not cached. This means that you can change the baseUrl and the App client will use the updated configuration. In earlier SDK versions, changes to the baseUrl in a cached App configuration have no effect.

Type signature
useAuth(): UseAuth

useAuth has an authentication method for every App Services authentication provider.

Type signature
result: AuthResult

Result of authentication hook operation. For example, result.operation gives you the name of the current operation.

Enum values

  • state. Can be "not-started", "pending", "success", "error".

  • operation. For a list of all operation names, refer to the API documentation.

  • pending. Can be true or false.

  • success. Can be true or false.

  • error. Error-based object or undefined.

Type signature
logIn(credentials: Realm.Credentials): void

Parameters

  • credentials. A Realm credential supplied by any supported Realm authentication.

Example

Logs in a user with any authentication mechanism supported by Realm. If called when a user is logged in, the current user switches to the new user. Usually, it's better to use the more specific login methods.

const {logIn, result} = useAuth();
useEffect(() => logIn(Realm.Credentials.anonymous()), []);
if(result.pending) {
return (<LoadingSpinner/>)
}
if(result.error) {
return (<ErrorComponent/>)
}
if(result.success) {
return (<SuccessComponent/>)
}
//...
Type signature
logInWithAnonymous(): void

Example

Log in with the anonymous authentication provider.

const {logInWithAnonymous, result} = useAuth();
const performLogin = () => {
logInWithAnonymous();
};
Type signature
logInWithApiKey(key: string): void

Parameters

  • key. A string that is linked to an App Services user.

Example

Log in with an API key.

const {logInWithApiKey, result} = useAuth();
const performLogin = () => {
const key = getApiKey(); // user defined function
logInWithApiKey(key);
};
Type signature
logInWithEmailPassword(credentials: {
email: string;
password: string;
}): void

Parameters

  • credentials. An object with email and password fields.

Example

Log in with Email/Password.

const {logInWithEmailPassword, result} = useAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performLogin = () => {
logInWithEmailPassword({email, password});
};
Type signature
logInWithJWT(token: string): void

Parameters

  • credentials. A string representation of a user's JWT.

Example

Log in with a JSON Web Token (JWT).

const {logInWithJWT, result} = useAuth();
const performLogin = () => {
const token = authorizeWithCustomerProvider(); // user defined function
logInWithJWT(token);
};
Type signature
logInWithGoogle(credentials: {
idToken: string;
} | {
authCode: string;
}): void;

Parameters

  • credentials. An object with an idToken or authCode field that should contain the string token you get from Google Identity Services.

Example

Log in with Google.

const {logInWithGoogle, result} = useAuth();
const performLogin = () => {
const token = getGoogleToken(); // user defined function
logInWithGoogle({idToken: token});
};
Type signature
logInWithApple(idToken: string): void;

Parameters

  • idToken. A string you get from the Apple SDK.

Example

Log in with Apple.

const {logInWithApple, result} = useAuth();
const performLogin = () => {
const token = getAppleToken(); // user defined function
logInWithApple(token);
};
Type signature
logInWithFacebook(accessToken: string): void;

Parameters

  • accessToken. A string you get from the Facebook SDK.

Example

Log in with Facebook.

const {logInWithFacebook, result} = useAuth();
const performLogin = () => {
const token = getFacebookToken(); // user defined function
logInWithFacebook(token);
};
Type signature
logInWithFunction<PayloadType extends Record<string, unknown>>(payload: PayloadType): void;

Parameters

  • payload. An object that contains user information you want to pass to the App Services function that processes log in requests.

Example

Log in with a custom function.

const {logInWithFunction, result} = useAuth();
const performLogin = () => {
const customPayload = getAuthParams(); // user defined arguments
logInWithFunction(customPayload);
};
Type signature
logOut(): void;

Example

Logs out the current user.

const {logOut, result} = useEmailPasswordAuth();
const performLogout = () => {
logOut();
}
Type signature
result: AuthResult

Result of authentication hook operation. For example, result.operation gives you the name of the current operation.

Enum values

  • state. Can be "not-started", "pending", "success", "error".

  • operation. For a list of all operation names, refer to the API documentation.

  • pending. Can be true or false.

  • success. Can be true or false.

  • error. Error-based object or undefined.

Type signature
logIn(credentials: { email: string; password: string }): void;

Parameters

  • credentials. An object that contains email and password properties.

Example

Logs a user in using an email and password. You could also call logIn(Realm.Credentials.emailPassword(email, password)). Returns a Realm.User instance of the logged-in user.

const {logIn, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performLogin = () => {
logIn({email, password});
};
if(result.pending) {
return (<LoadingSpinner/>)
}
if(result.error) {
return (<ErrorComponent/>)
}
if(result.success) {
return (<SuccessComponent/>)
}
//...
Type signature
logOut(): void;

Example

Logs out the current user.

const {logOut, result} = useEmailPasswordAuth();
const performLogout = () => {
logOut();
}
Type signature
register(args: { email: string; password: string }): void;

Parameters

  • args. An object that contains email and password properties.

Example

Registers a new user. Requires a user email and password.

const {register, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performRegister = () => {
register({email, password});
};
Type signature
confirm(args: { token: string; tokenId: string }): void;

Parameters

  • args. An object that contains token and tokenId properties.

Example

Confirms a user account. Requires a token and tokenId.

const {confirm, result} = useEmailPasswordAuth();
const performConfirmation = () => {
confirm({token, tokenId});
};
Type signature
resendConfirmationEmail(args: { email: string }): void;

Parameters

  • args. An object that contains an email property.

Example

Resends a confirmation email.

const {resendConfirmationEmail, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performResendConfirmationEmail = () => {
resendConfirmationEmail({email});
};
Type signature
retryCustomConfirmation(args: { email: string }): void;

Parameters

  • args. An object that contains an email property.

Example

Retries confirmation with a custom function.

const {retryCustomConfirmation, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performRetryCustomConfirmation = () => {
retryCustomConfirmation({email});
};
Type signature
sendResetPasswordEmail(args: { email: string }): void;

Parameters

  • args. An object that contains an email property.

Example

Sends a password reset email.

const {sendResetPasswordEmail, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const performSendResetPasswordEmail = () => {
sendResetPasswordEmail({email});
};
Type signature
resetPassword(args: { token: string; tokenId: string; password: string }): void;

Parameters

  • args. An object that contains token, tokenId, and password properties.

Example

Resets a user's password.

const {resetPassword, result} = useEmailPasswordAuth();
const [password, setPassword] = useState('');
const performResetPassword = () => {
resetPassword({token, tokenId, password});
};
Type signature
callResetPasswordFunction<Args extends unknown[] = []>(
args: {
email: string;
password: string;
},
...restArgs: Args
): void;

Parameters

  • args. An object that contains email and password properties.

  • restArgs. Additional arguments that you need to pass to your custom reset password function.

Example

Calls your App Services backend password reset function. Can pass arguments to the function as needed.

const {callResetPasswordFunction, result} = useEmailPasswordAuth();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const performResetPassword = () => {
callResetPasswordFunction({email, password}, "extraArg1", "extraArg2");
};
Type signature
useApp<FunctionsFactoryType, CustomDataType>(): Realm.App<FunctionsFactoryType, CustomDataType>

Example

The useApp() hook provides access to a Realm.App instance.

import React from 'react';
import {useApp} from '@realm/react';
function MyApp() {
const app = useApp();
// Proceed to app logic...
}

Returns

  • Realm.App An instance of the current Realm.App created by AppProvider.

← RealmProvider (@realm/react)