Merge pull request #609 from logto-io/gao-add-rn-guide

docs: add react native guide

docs/sdk/fragments/_checkpoint-test-your-application.md

@@ -0,0 +1,8 @@
+### Checkpoint: Test your application
+
+Now, you can test your application:
+
+1. Run your application, you will see the sign-in button.
+2. Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
+3. After you signed in, you will be redirected back to your application and see the user data with sign-out button.
+4. Click the sign-out button to clear local storage and sign out.

docs/sdk/fragments/_configure-post-sign-out-redirect-uri.mdx

@@ -1,9 +1,8 @@
 <p>
-  Let&apos;s switch to the Application details page of Admin Console in this section. Add a Post
-  Sign-out Redirect URI <code>{props.postSignOutRedirectUri}</code> and click &quot;Save
-  Changes&quot;.
+  Let&apos;s switch to the Application details page of Logto Console. Add a Post Sign-out Redirect
+  URI <code>{props.postSignOutRedirectUri}</code> and click &quot;Save Changes&quot;.
 </p>
 
-<img alt="Post Sign-out Redirect URI in Admin Console" src={props.figureSrc} width="600px" />
+<img alt="Post Sign-out Redirect URI in Logto Console" src={props.figureSrc} width="600px" />
 
 [Post Sign-outRedirect URI](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) is an OAuth 2.0 concept which implies the location should redirect after signing out.

docs/sdk/fragments/_configure-redirect-uri.mdx

@@ -1,8 +1,8 @@
 <p>
-  Let&apos;s switch to the Application details page of Admin Console in this section. Add a Redirect
-  URI <code>{props.redirectUri}</code> and click &quot;Save Changes&quot;.
+  Let&apos;s switch to the Application details page of Logto Console. Add a Redirect URI{' '}
+  <code>{props.redirectUri}</code> and click &quot;Save Changes&quot;.
 </p>
 
-<img alt="Redirect URI in Admin Console" src={props.figureSrc} width="600px" />
+<img alt="Redirect URI in Logto Console" src={props.figureSrc} width="600px" />
 
 [Redirect URI](https://www.oauth.com/oauth2-servers/redirect-uris/) is an OAuth 2.0 concept which implies the location should redirect after authentication.

docs/sdk/native/android/api-resources/_fetch-organization-token-for-user.mdx

@@ -4,7 +4,7 @@ import ConfigOrganizationCode from './code/_config-organization-code.md';
 import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
 
 <FetchOrganizationTokenForUser
-  organizationScope="UserScope.ORGANIZATIONS"
+  organizationScope="UserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />

docs/sdk/native/android/api-resources/code/_config-organization-code.md

@@ -1,6 +1,6 @@
 ```kotlin
 val logtoConfig = LogtoConfig(
     // ...other configs
-    scopes = listOf(UserScope.ORGANIZATIONS),
+    scopes = listOf(UserScope.Organizations),
 )
 ```

docs/sdk/native/expo/README.mdx

@@ -0,0 +1,41 @@
+---
+slug: /sdk/expo
+sidebar_label: Expo (React Native)
+---
+
+import FurtherReadings from '../../fragments/_further-readings.md';
+import GetUserInformation from '../../spa/react/_get-user-information.mdx';
+import ApiResources from '../../spa/react/api-resources/_index.mdx';
+
+import GuideTip from './_guide-tip.md';
+import Installation from './_installation.mdx';
+import Integration from './_integration.mdx';
+
+# Integrate Logto with Expo (React Native)
+
+<GuideTip />
+
+## Prerequisites
+
+- A [Logto Cloud](https://cloud.logto.io) account or a self-hosted Logto (Check out the [⚡ Get started](/docs/tutorials/get-started/) guide to create one if you don't have).
+- A Logto native application created.
+
+## Installation
+
+<Installation />
+
+## Integration
+
+<Integration />
+
+## Get user information
+
+<GetUserInformation />
+
+## API resources
+
+<ApiResources />
+
+## Further readings
+
+<FurtherReadings />

docs/sdk/native/expo/_guide-tip.md

@@ -0,0 +1,6 @@
+:::tip
+
+- The following demonstration is built on Expo ~50.0.6.
+- The sample project is available on our [SDK repository](https://github.com/logto-io/react-native/tree/master/packages/rn-sample).
+
+:::

docs/sdk/native/expo/_installation.mdx

@@ -0,0 +1,39 @@
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+Install Logto SDK and peer dependencies via your favorite package manager:
+
+<Tabs>
+
+  <TabItem value="npm" label="npm">
+
+```bash
+npm i @logto/rn
+npm i expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add @logto/rn
+yarn add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
+```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add @logto/rn
+pnpm add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
+```
+
+  </TabItem>
+
+</Tabs>
+
+The `@logto/rn` package is the SDK for Logto. The remaining packages are its peer dependencies. They couldn't be listed as direct dependencies because the Expo CLI requires that all dependencies for native modules be installed directly within the root project's `package.json`.
+
+:::note
+If you're installing this in a [bare React Native app](https://docs.expo.dev/bare/overview), you should also follow these [additional installation instructions](https://docs.expo.dev/bare/installing-expo-modules/).
+:::

docs/sdk/native/expo/_integration.mdx

@@ -0,0 +1,98 @@
+import Checkpoint from '../../fragments/_checkpoint-test-your-application.md';
+import SignInFlowSummary from '../../fragments/_web-sign-in-flow-summary.mdx';
+
+### Init Logto provider
+
+Import and use `LogtoProvider` to provide a Logto context:
+
+```tsx
+import { LogtoProvider, LogtoConfig } from '@logto/rn';
+
+const config: LogtoConfig = {
+  endpoint: '<your-logto-endpoint>',
+  appId: '<your-application-id>',
+};
+
+const App = () => (
+  <LogtoProvider config={config}>
+    <YourAppContent />
+  </LogtoProvider>
+);
+```
+
+### Implement sign-in and sign-out
+
+<SignInFlowSummary />
+
+Switch to the application details page of Logto Console. Add a native redirect URI (for example, `io.logto://callback`), then click "Save".
+
+- For iOS, the redirect URI scheme does not really matter since the `ASWebAuthenticationSession` class will listen to the redirect URI regardless of if it's registered.
+- For Android, the redirect URI scheme must be filled in Expo's `app.json` file, for example:
+
+  ```json
+  {
+    "expo": {
+      "scheme": "io.logto"
+    }
+  }
+  ```
+
+  Now back to your app, you can use `useLogto` hook to sign in and sign out:
+
+```tsx
+import { useLogto } from '@logto/rn';
+import { Button } from 'react-native';
+
+const Content = () => {
+  const { signIn, signOut, isAuthenticated } = useLogto();
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <Button title="Sign out" onPress={async () => signOut()} />
+      ) : (
+        // Replace the redirect URI with your own
+        <Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
+      )}
+    </div>
+  );
+};
+```
+
+### Display user information
+
+To display the user's information, you use the `getIdTokenClaims()` method:
+
+```tsx
+import { useLogto } from '@logto/rn';
+import { Button, Text } from 'react-native';
+
+const Content = () => {
+  const { getIdTokenClaims, isAuthenticated } = useLogto();
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      getIdTokenClaims().then((claims) => {
+        setUser(claims);
+      });
+    }
+  }, [isAuthenticated]);
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <>
+          <Text>{user?.name}</Text>
+          <Text>{user?.email}</Text>
+          <Button title="Sign out" onPress={async () => signOut()} />
+        </>
+      ) : (
+        <Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
+      )}
+    </div>
+  );
+};
+```
+
+<Checkpoint />

docs/sdk/native/flutter/_organization.mdx

@@ -6,7 +6,7 @@ import ConfigOrganizationCode from './code-snippets/_organization-config-code.md
 Just like API resources, you may also request for organization token for the user. The organization token is used to access the organization's resources on behalf of the user.
 
 <FetchOrganizationTokenForUser
-  organizationScope="LogtoUserScope.ORGANIZATIONS"
+  organizationScope="LogtoUserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />

docs/sdk/spa/angular/_integration.mdx

@@ -4,10 +4,6 @@ import SignInFlowSummary from '../../fragments/_web-sign-in-flow-summary.mdx';
 
 <AssumingUrl />
 
-<SignInFlowSummary />
-
-<WebConfigureRedirectUris />
-
 ### Configure application
 
 In your Angular project, add the auth provider your `app.config.ts`:
@@ -35,6 +31,10 @@ export const appConfig: ApplicationConfig = {
 
 ### Implement sign-in and sign-out
 
+<SignInFlowSummary />
+
+<WebConfigureRedirectUris />
+
 In the component where you want to implement sign-in and sign-out (for example, `app.component.ts`), inject the `OidcSecurityService` and use it to sign in and sign out.
 
 ```ts

docs/sdk/spa/react/README.mdx

@@ -3,22 +3,17 @@ slug: /sdk/react
 sidebar_label: React
 ---
 
-import ApiResourcesDescription from '../../fragments/_api-resources-description.md';
 import FurtherReadings from '../../fragments/_further-readings.md';
-import GetUserInfoApis from '../../fragments/_get-user-info-apis.mdx';
-import ScopesAndClaims from '../../fragments/_scopes-and-claims.mdx';
 
 import CheckIntegration from './_check-integration.mdx';
+import GetUserInformation from './_get-user-information.mdx';
 import GuideTip from './_guide-tip.mdx';
 import HandleAuthenticationStatus from './_handle-authentication-status.mdx';
 import ImplementSignIn from './_implement-sign-in.mdx';
 import ImplementSignOut from './_implement-sign-out.mdx';
 import InitClient from './_init-client.mdx';
 import Installation from './_installation.mdx';
-import ScopesAndClaimsCode from './_scopes-and-claims-code.mdx';
-import ConfigApiResources from './api-resources/_config-api-resources.mdx';
-import FetchAccessTokenForApiResources from './api-resources/_fetch-access-token-for-api-resources.mdx';
-import FetchOrganizationTokenForUser from './api-resources/_fetch-organization-token-for-user.mdx';
+import ApiResources from './api-resources/_index.mdx';
 
 # React SDK guide
 
@@ -38,7 +33,7 @@ This guide will show you how to integrate Logto into your React application.
 
 ## Integration
 
-### Init LogtoClient
+### Init Logto provider
 
 <InitClient />
 
@@ -60,25 +55,11 @@ This guide will show you how to integrate Logto into your React application.
 
 ## Get user information
 
-<GetUserInfoApis getIdTokenClaimsApi="getIdTokenClaims" fetchUserInfoApi="fetchUserInfo" />
-
-<ScopesAndClaims configScopesCode={<ScopesAndClaimsCode />} />
+<GetUserInformation />
 
 ## API resources
 
-<ApiResourcesDescription />
-
-### Configure Logto client
-
-<ConfigApiResources />
-
-### Fetch access token for the API resource
-
-<FetchAccessTokenForApiResources />
-
-### Fetch organization token for user
-
-<FetchOrganizationTokenForUser />
+<ApiResources />
 
 ## Further readings
 

docs/sdk/spa/react/_get-user-information.mdx

@@ -0,0 +1,8 @@
+import GetUserInfoApis from '../../fragments/_get-user-info-apis.mdx';
+import ScopesAndClaims from '../../fragments/_scopes-and-claims.mdx';
+
+import ScopesAndClaimsCode from './_scopes-and-claims-code.mdx';
+
+<GetUserInfoApis getIdTokenClaimsApi="getIdTokenClaims" fetchUserInfoApi="fetchUserInfo" />
+
+<ScopesAndClaims configScopesCode={<ScopesAndClaimsCode />} />

docs/sdk/spa/react/api-resources/_fetch-organization-token-for-user.mdx

@@ -4,7 +4,7 @@ import ConfigOrganizationCode from './code/_config-organization-code.md';
 import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
 
 <FetchOrganizationTokenForUser
-  organizationScope="UserScope.ORGANIZATIONS"
+  organizationScope="UserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />

docs/sdk/spa/react/api-resources/_index.mdx

@@ -0,0 +1,19 @@
+import ApiResourcesDescription from '../../../fragments/_api-resources-description.md';
+
+import ConfigApiResources from './_config-api-resources.mdx';
+import FetchAccessTokenForApiResources from './_fetch-access-token-for-api-resources.mdx';
+import FetchOrganizationTokenForUser from './_fetch-organization-token-for-user.mdx';
+
+<ApiResourcesDescription />
+
+### Configure Logto client
+
+<ConfigApiResources />
+
+### Fetch access token for the API resource
+
+<FetchAccessTokenForApiResources />
+
+### Fetch organization token for user
+
+<FetchOrganizationTokenForUser />

docs/sdk/spa/vue/api-resources/_fetch-organization-token-for-user.mdx

@@ -4,7 +4,7 @@ import ConfigOrganizationCode from './code/_config-organization-code.md';
 import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
 
 <FetchOrganizationTokenForUser
-  organizationScope="UserScope.ORGANIZATIONS"
+  organizationScope="UserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />

docs/sdk/web/express/api-resources/_fetch-organization-token-for-user.mdx

@@ -4,7 +4,7 @@ import ConfigOrganizationCode from './code/_config-organization-code.md';
 import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
 
 <FetchOrganizationTokenForUser
-  organizationScope="UserScope.ORGANIZATIONS"
+  organizationScope="UserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />

docs/sdk/web/next-app-router/api-resources/_fetch-organization-token-for-user.mdx

@@ -4,7 +4,7 @@ import ConfigOrganizationCode from './code/_config-organization-code.md';
 import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
 
 <FetchOrganizationTokenForUser
-  organizationScope="UserScope.ORGANIZATIONS"
+  organizationScope="UserScope.Organizations"
   configOrganizationCode={<ConfigOrganizationCode />}
   getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
 />