docs: add webflow full integration guide (#670)

Author: charIeszhao

docs/quick-starts/framework/webflow/README.mdx

@@ -0,0 +1,60 @@
+---
+slug: /quick-starts/webflow
+sidebar_label: Webflow
+sidebar_custom_props:
+  description: Webflow is a SaaS platform for website building and hosting.
+---
+
+import FurtherReadings from '../../fragments/_further-readings.md';
+
+import Checkpoint from './_checkpoint-test-your-webflow-site.md';
+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 ApiResources from './api-resources/_index.mdx';
+
+# Webflow integration guide
+
+This guide will show you how to integrate Logto into your Webflow sites.
+
+<GuideTip />
+
+## Prerequisits
+
+1. Integrating Logto with Webflow requires the "Custom code" feature of Webflow, which requires at least the "Basic" plan.
+2. A Webflow site, either use an existing site or create a new one.
+
+## Integration
+
+### Init Logto provider
+
+<InitClient />
+
+### Implement sign-in
+
+<ImplementSignIn />
+
+### Implement sign-out
+
+<ImplementSignOut />
+
+### Handle authentication status
+
+<HandleAuthenticationStatus />
+
+<Checkpoint />
+
+## Get user information
+
+<GetUserInformation />
+
+## API resources
+
+<ApiResources />
+
+## Further readings
+
+<FurtherReadings />

docs/quick-starts/framework/webflow/_checkpoint-test-your-webflow-site.md

@@ -0,0 +1,8 @@
+### Checkpoint: Test your Webflow site
+
+Now, test your site:
+
+1. Deploy and visit your site URL, the sign-in button should be visible.
+2. Click the sign-in button, the SDK will initiate the sign-in process, redirecting you to the Logto sign-in page.
+3. After signing in, you will be redirected back to your site, seeing the username and the sign-out button.
+4. Click the sign-out button to sign-out.

docs/quick-starts/framework/webflow/_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/quick-starts/framework/webflow/_guide-tip.mdx

@@ -0,0 +1,5 @@
+:::tip
+
+- The sample project is available at [Webflow project preview](https://preview.webflow.com/preview/charless-trendy-site-f191c0?utm_medium=preview_link&utm_source=designer&utm_content=charless-trendy-site-f191c0&preview=0eae5f73661a8a5791787f0438bc29de&workflow=preview).
+- A live demo is deployed at https://charless-trendy-site-f191c0.webflow.io/.
+  :::

docs/quick-starts/framework/webflow/_handle-authentication-status.mdx

@@ -0,0 +1,10 @@
+In Logto SDK, generally we can use `logtoClient.isAuthenticated()` method to check the authentication status, if the user is signed in, the value will be `true`; otherwise, it will be `false`.
+
+In your Webflow site, you can also use it to programmatically show and hide the sign-in and sign-out buttons. Apply the following custom code to adjust button CSS accordingly.
+
+```js
+const isAuthenticated = await logtoClient.isAuthenticated();
+
+signInButton.style.display = isAuthenticated ? 'none' : 'block';
+signOutButton.style.display = isAuthenticated ? 'block' : 'none';
+```

docs/quick-starts/framework/webflow/_handle-redirect.mdx

@@ -0,0 +1,15 @@
+We're almost there! In the last step, we use `https://your-awesome-site.webflow.io/callback` as the Redirect URI, and now we need to handle it properly.
+
+First let's create a "Callback" page in Webflow, and simply put some static text "Redirecting..." on it. Then add the following page-level custom code to "Callback" page.
+
+```html
+<script type="module">
+  (async () => {
+    // Handle sign-in callback logic by calling the SDK method
+    await logtoClient.handleSignInCallback(window.location.href);
+
+    // Redirect back to the home page when the handling is done
+    window.location.assign('https://your-awesome-site.webflow.io');
+  })();
+</script>
+```

docs/quick-starts/framework/webflow/_implement-sign-in.mdx

@@ -0,0 +1,30 @@
+import redirectUriFigure from '../../assets/web-redirect-uri.png';
+import ConfigureRedirectUri from '../../fragments/_configure-redirect-uri.mdx';
+import SignInFlowSummary from '../../fragments/_web-sign-in-flow-summary.mdx';
+
+import HandleRedirect from './_handle-redirect.mdx';
+
+<SignInFlowSummary />
+
+#### Configure sign-in redirect URI
+
+<ConfigureRedirectUri
+  figureSrc={redirectUriFigure}
+  redirectUri="https://your-awesome-site.webflow.io/callback"
+/>
+
+#### Implement a sign-in button
+
+Return to your Webflow designer, drag and drop a "Sign in" button to the home page, and assign it an ID “sign-in” for later reference using `getElementById()`.
+
+```html
+<script type="module">
+  const signInButton = document.getElementById('sign-in');
+  const onClickSignIn = () => logtoClient.signIn('https://your-awesome-site.webflow.io/callback');
+  signInButton.addEventListener('click', onClickSignIn);
+</script>
+```
+
+#### Handle redirect
+
+<HandleRedirect />

docs/quick-starts/framework/webflow/_implement-sign-out.mdx

@@ -0,0 +1,13 @@
+Calling `.signOut()` will clear all the Logto data in memory and localStorage if they exist.
+
+After signing out, it'll be great to redirect your user back to your website. Let's add `https://your-awesome-site.webflow.io` as one of the Post Sign-out URIs in Admin Console (shows under Redirect URIs), and use the URL as the parameter when calling `.signOut()`.
+
+#### Implement a sign-out button
+
+Return to the Webflow designer, and add a “Sign out” button on your home page. Similarly, assign an ID “sign-out” to the button, and add the following code to the page-level custom code.
+
+```js
+const signOutButton = document.getElementById('sign-out');
+const onClickSignOut = () => logtoClient.signOut('https://your-awesome-site.webflow.io');
+signOutButton.addEventListener('click', onClickSignOut);
+```

docs/quick-starts/framework/webflow/_init-client.mdx

@@ -0,0 +1,21 @@
+:::note
+In the following steps, we assume your Webflow site is running on `https://your-awesome-site.webflow.io`.
+:::
+
+In this step, we'll add global-level custom code to your Webflow site. Since NPM is not supported in Webflow, we'll use the [jsdelivr.com](https://www.jsdelivr.com/) CDN service to import the Logto SDK.
+
+Open the "Site settings" page, and navigate to the "Custom code" section. Add the following code to the "Head code" section.
+
+```html
+<script type="module">
+  // Import \`@logto/browser\` SDK from the jsdelivr CDN
+  import LogtoClient from 'https://esm.run/@logto/browser';
+
+  // Assign the \`logtoClient\` instance to window object,
+  // enabling global usage in other pages
+  window.logtoClient = new LogtoClient({
+    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
+    appId: '<your-application-id>',
+  });
+</script>
+```

docs/quick-starts/framework/webflow/_scopes-and-claims-code.mdx

@@ -0,0 +1,20 @@
+```html
+<script type="module">
+  // Import \`@logto/browser\` SDK from the jsdelivr CDN
+  import LogtoClient from 'https://esm.run/@logto/browser';
+
+  // Assign the \`logtoClient\` instance to window object,
+  // enabling global usage in other pages
+  window.logtoClient = new LogtoClient({
+    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
+    appId: '<your-application-id>',
+    scopes: [
+      UserScope.Email,
+      UserScope.Phone,
+      UserScope.CustomData,
+      UserScope.Identities,
+      UserScope.Organizations,
+    ],
+  });
+</script>
+```

docs/quick-starts/framework/webflow/api-resources/_config-api-resources.mdx

@@ -0,0 +1,11 @@
+import ConfigApiResources from '../../../fragments/_config-api-resources.mdx';
+
+import ConfigResourcesCode from './code/_config-resources-code.md';
+import ConfigResourcesWithScopesCode from './code/_config-resources-with-scopes-code.md';
+import ConfigResourcesWithSharedScopesCode from './code/_config-resources-with-shared-scopes-code.md';
+
+<ConfigApiResources
+  configResourcesCode={<ConfigResourcesCode />}
+  configResourcesWithScopesCode={<ConfigResourcesWithScopesCode />}
+  configResourcesWithSharedScopesCode={<ConfigResourcesWithSharedScopesCode />}
+/>

docs/quick-starts/framework/webflow/api-resources/_fetch-access-token-for-api-resources.mdx

@@ -0,0 +1,8 @@
+import FetchAccessTokenForApiResources from '../../../fragments/_fetch-access-token-for-api-resources.mdx';
+
+import GetAccessTokenCode from './code/_get-access-token-code.md';
+
+<FetchAccessTokenForApiResources
+  getAccessTokenApi="getAccessToken"
+  getAccessTokenCode={<GetAccessTokenCode />}
+/>

docs/quick-starts/framework/webflow/api-resources/_fetch-organization-token-for-user.mdx

@@ -0,0 +1,10 @@
+import FetchOrganizationTokenForUser from '../../../fragments/_fetch-organization-token-for-user.mdx';
+
+import ConfigOrganizationCode from './code/_config-organization-code.md';
+import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
+
+<FetchOrganizationTokenForUser
+  organizationScope="UserScope.Organizations"
+  configOrganizationCode={<ConfigOrganizationCode />}
+  getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
+/>

docs/quick-starts/framework/webflow/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/quick-starts/framework/webflow/api-resources/code/_config-organization-code.md

@@ -0,0 +1,8 @@
+```js
+import LogtoClient, { UserScope } from 'https://esm.run/@logto/browser';
+
+window.logtoClient = new LogtoClient({
+  // ...other configs
+  scopes: [UserScope.Organizations],
+});
+```

docs/quick-starts/framework/webflow/api-resources/code/_config-resources-code.md

@@ -0,0 +1,14 @@
+```html
+<script type="module">
+  // Import \`@logto/browser\` SDK from the jsdelivr CDN
+  import LogtoClient from 'https://esm.run/@logto/browser';
+
+  // Assign the \`logtoClient\` instance to window object,
+  // enabling global usage in other pages
+  window.logtoClient = new LogtoClient({
+    endpoint: '<your-logto-endpoint>', // E.g. http://localhost:3001
+    appId: '<your-application-id>',
+    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
+  });
+</script>
+```

docs/quick-starts/framework/webflow/api-resources/code/_config-resources-with-scopes-code.md

@@ -0,0 +1,13 @@
+```html
+<script type="module">
+  // Import \`@logto/browser\` SDK from the jsdelivr CDN
+  import LogtoClient from 'https://esm.run/@logto/browser';
+
+  window.logtoClient = new LogtoClient({
+    endpoint: '<your-logto-endpoint>',
+    appId: '<your-application-id>',
+    scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
+    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
+  });
+</script>
+```

docs/quick-starts/framework/webflow/api-resources/code/_config-resources-with-shared-scopes-code.md

@@ -0,0 +1,13 @@
+```html
+<script type="module">
+  // Import \`@logto/browser\` SDK from the jsdelivr CDN
+  import LogtoClient from 'https://esm.run/@logto/browser';
+
+  window.logtoClient = new LogtoClient({
+    endpoint: '<your-logto-endpoint>',
+    appId: '<your-application-id>',
+    scopes: ['read', 'write'],
+    resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
+  });
+</script>
+```

docs/quick-starts/framework/webflow/api-resources/code/_get-access-token-code.md

@@ -0,0 +1,10 @@
+```js
+const isAuthenticated = await logtoClient.isAuthenticated();
+
+if (isAuthenticated) {
+  (async () => {
+    const token = await logtoClient.getAccessToken();
+    console.log(token);
+  })();
+}
+```

docs/quick-starts/framework/webflow/api-resources/code/_get-organization-access-token-code.md

@@ -0,0 +1,21 @@
+```js
+import { UserScope } from 'https://esm.run/@logto/browser';
+
+const isAuthenticated = await logtoClient.isAuthenticated();
+
+(async () => {
+  if (!isAuthenticated) {
+    return;
+  }
+  const claims = await logtoClient.getIdTokenClaims();
+
+  console.log('ID token claims:', claims);
+  console.log('Organization IDs:', claims.organizations);
+
+  // Assuming there's at least one organization, let's take the first one
+  const organizationId = claims.organizations[0];
+  const token = await logtoClient.getOrganizationToken(organizationId);
+
+  console.log('Organization access token:', token);
+})();
+```