docs: improve docs regarding firebase js sdk (#262)

capawesome-team · Jan 6, 2023 · d379df0 · d379df0
1 parent aceeb8f
commit d379df0
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 52 deletions.
diff --git a/packages/app-check/README.md b/packages/app-check/README.md
@@ -38,6 +38,10 @@ See [Set up your Firebase project](https://firebase.google.com/docs/app-check/we
 
 No configuration required for this plugin.
 
+## Firebase JavaScript SDK
+
+[Here](/packages/app-check/docs/firebase-js-sdk.md) you can find information on how to use the plugin with the Firebase JS SDK.
+
 ## Demo
 
 A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)
@@ -46,8 +50,6 @@ A working example can be found here: [robingenz/capacitor-firebase-plugin-demo](
 
 ```typescript
 import { FirebaseAppCheck } from '@capacitor-firebase/app-check';
-import { getApp } from 'firebase/app';
-import { initializeAppCheck, CustomProvider } from 'firebase/app-check';
 
 const getToken = async () => {
   const { token } = FirebaseAppCheck.getToken({
@@ -56,25 +58,12 @@ const getToken = async () => {
   return token;
 };
 
-const initializeOnWeb = async () => {
+const initialize = async () => {
   await FirebaseAppCheck.initialize({
     siteKey: 'myKey',
   });
 };
 
-// Only necessary if you want to use this plugin
-// with Firebase JS SDK on Android and iOS.
-const initializeOnNative = async () => {
-  await FirebaseAppCheck.initialize();
-  const provider = new CustomProvider({
-    getToken: () => {
-      return FirebaseAppCheck.getToken();
-    },
-  });
-  const app = getApp();
-  await initializeAppCheck(app, { provider });
-};
-
 const setTokenAutoRefreshEnabled = async () => {
   await FirebaseAppCheck.setTokenAutoRefreshEnabled({ enabled: true });
 };

diff --git a/packages/app-check/docs/firebase-js-sdk.md b/packages/app-check/docs/firebase-js-sdk.md
@@ -0,0 +1,34 @@
+# Firebase JavaScript SDK
+
+> The [Firebase JavaScript SDK](https://firebase.google.com/docs/reference/js) implements the client-side libraries used by applications using Firebase services.
+
+By default, this plugin uses the Firebase JS SDK on the Web, the native Firebase Android SDK on Android, and the native Firebase iOS SDK on iOS. 
+If you want to use the Firebase JS SDK on Android and iOS as well, follow the instructions in this guide.
+
+## Installation
+
+Add Firebase to your JavaScript project if you haven't already (see [here](https://firebase.google.com/docs/web/setup)).
+
+## Usage
+
+Initialize App Check on the native layer, create a custom provider and then initialize app check on the web layer using the token from the native layer.
+
+```ts
+import { FirebaseAppCheck } from '@capacitor-firebase/app-check';
+import { getApp } from 'firebase/app';
+import { initializeAppCheck, CustomProvider } from 'firebase/app-check';
+
+const initialize = async () => {
+    // 1. Initialize on the native layer
+    await FirebaseAppCheck.initialize();
+    // 2. Set up a custom provider
+    const provider = new CustomProvider({
+        getToken: () => {
+            return FirebaseAppCheck.getToken();
+        },
+    });
+    const app = getApp();
+    // 3. Initialize on the web layer
+    await initializeAppCheck(app, { provider });
+};
+```
diff --git a/packages/authentication/README.md b/packages/authentication/README.md
@@ -118,6 +118,10 @@ export default config;
 1. **How can I use this plugin with the Firebase JavaScript SDK?**  
    See [here](/packages/authentication/docs/firebase-js-sdk.md).
 
+## Firebase JavaScript SDK
+
+[Here](/packages/authentication/docs/firebase-js-sdk.md) you can find information on how to use the plugin with the Firebase JS SDK.
+
 ## Demo
 
 A working example can be found here: [robingenz/capacitor-firebase-authentication-demo](https://github.com/robingenz/capacitor-firebase-authentication-demo)
@@ -193,7 +197,7 @@ const sendSignInLinkToEmail = async () => {
         minimumVersion: '12',
       },
       dynamicLinkDomain: 'example.page.link',
-    }
+    },
   });
   // The link was successfully sent. Inform the user.
   // Save the email locally so you don't need to ask the user for it again
@@ -240,19 +244,18 @@ const signInWithEmailLink = async () => {
   // the flow on the same device where they started it.
   const emailLink = window.location.href;
   // Confirm the link is a sign-in with email link.
-  const { isSignInWithEmailLink } = await FirebaseAuthentication.isSignInWithEmailLink({
-    emailLink,
-  });
+  const { isSignInWithEmailLink } =
+    await FirebaseAuthentication.isSignInWithEmailLink({
+      emailLink,
+    });
   if (!isSignInWithEmailLink) {
     return;
   }
   let email = window.localStorage.getItem('emailForSignIn');
   if (!email) {
     // User opened the link on a different device. To prevent session fixation
     // attacks, ask the user to provide the associated email again.
-    email = window.prompt(
-      'Please provide your email for confirmation.',
-    );
+    email = window.prompt('Please provide your email for confirmation.');
   }
   // The client SDK will parse the code from the link for you.
   const result = await FirebaseAuthentication.signInWithEmailLink({

diff --git a/packages/authentication/docs/firebase-js-sdk.md b/packages/authentication/docs/firebase-js-sdk.md
@@ -2,26 +2,17 @@
 
 > The [Firebase JavaScript SDK](https://firebase.google.com/docs/reference/js) implements the client-side libraries used by applications using Firebase services.
 
-## How to use this plugin with the Firebase JavaScript SDK
+By default, this plugin uses the Firebase JS SDK on the Web, the native Firebase Android SDK on Android, and the native Firebase iOS SDK on iOS. 
+This means, by default, this plugin signs the user in only on the native layer of the app.
+If you want to use the Firebase JS SDK on Android and iOS as well, follow the instructions in this guide.
 
-By default, this plugin signs the user in only on the native layer of the app.
-In order to use the Firebase JavaScript SDK on Android and iOS, a sign-in on the web layer is required.
-To do this, follow these steps:
+## Installation
 
-1. [Add Firebase to your JavaScript project](https://firebase.google.com/docs/web/setup)
-1. Set the configuration option [`skipNativeAuth`](/packages/authentication/README.md#configuration) to `true` (sometimes you also need `false`, see [Quirks](#quirks)).
-1. Sign in on the native layer, create web credentials and sign in on the web using [`signInWithCredential`](https://firebase.google.com/docs/reference/js/auth.md#signinwithcredential) (see [Examples](#examples)).
+Add Firebase to your JavaScript project if you haven't already (see [here](https://firebase.google.com/docs/web/setup)).
 
-## Quirks
-
-When using the Firebase JS SDK on Android and iOS, you must be aware of the following:
-
-- **Apple Sign-In** works on Android and iOS only with `skipNativeAuth=true` (see [here](https://github.com/robingenz/capacitor-firebase-authentication/issues/41#issuecomment-884106449)).
-- **Twitter Sign-In** works on iOS only with `skipNativeAuth=false` (see [here](https://github.com/robingenz/capacitor-firebase-authentication/issues/93#issuecomment-939459594)).
-
-**Note**: The [`skipNativeAuth`](/packages/authentication/README.md#configuration) configuration option can be overwritten for each plugin call individually (see `skipNativeAuth` parameter in [SignInOptions](/packages/authentication/README.md#signinoptions)).
+## Usage
 
-## Examples
+Sign in the user on the native layer, create web credentials and sign in the user on the web layer using [`signInWithCredential`](https://firebase.google.com/docs/reference/js/auth.md#signinwithcredential).
 
 ```js
 import { FirebaseAuthentication } from '@capacitor-firebase/authentication';
@@ -36,7 +27,7 @@ import {
 
 const signInWithApple = async () => {
   // 1. Create credentials on the native layer
-  const result = await FirebaseAuthentication.signInWithApple();
+  const result = await FirebaseAuthentication.signInWithApple({ skipNativeAuth: true });
   // 2. Sign in on the web layer using the id token and nonce
   const provider = new OAuthProvider('apple.com');
   const credential = provider.credential({
@@ -47,15 +38,6 @@ const signInWithApple = async () => {
   await signInWithCredential(auth, credential);
 };
 
-const signInWithGoogle = async () => {
-  // 1. Create credentials on the native layer
-  const result = await FirebaseAuthentication.signInWithGoogle();
-  // 2. Sign in on the web layer using the id token
-  const credential = GoogleAuthProvider.credential(result.credential?.idToken);
-  const auth = getAuth();
-  await signInWithCredential(auth, credential);
-};
-
 const signInWithFacebook = async () => {
   // 1. Create credentials on the native layer
   const result = await FirebaseAuthentication.signInWithFacebook();
@@ -67,6 +49,15 @@ const signInWithFacebook = async () => {
   await signInWithCredential(auth, credential);
 };
 
+const signInWithGoogle = async () => {
+  // 1. Create credentials on the native layer
+  const result = await FirebaseAuthentication.signInWithGoogle();
+  // 2. Sign in on the web layer using the id token
+  const credential = GoogleAuthProvider.credential(result.credential?.idToken);
+  const auth = getAuth();
+  await signInWithCredential(auth, credential);
+};
+
 const signInWithPhoneNumber = async () => {
   // 1. Start phone number verification
   const { verificationId } = await FirebaseAuthentication.signInWithPhoneNumber(
@@ -87,6 +78,15 @@ const signInWithPhoneNumber = async () => {
   await signInWithCredential(auth, credential);
 };
 
+const signInWithTwitter = async () => {
+  // 1. Create credentials on the native layer
+  const result = await FirebaseAuthentication.signInWithTwitter({ skipNativeAuth: false });
+  // 2. Sign in on the web layer using the id token and secret
+  const credential = TwitterAuthProvider.credential(result.credential?.idToken, result.credential?.secret);
+  const auth = getAuth();
+  await signInWithCredential(auth, credential);
+};
+
 const linkWithGoogle = async () => {
   // 1. Create credentials on the native layer
   const result = await FirebaseAuthentication.signInWithGoogle();
@@ -125,7 +125,11 @@ const signInWithEmailLink = async () => {
 };
 ```
 
-The dependencies used in these examples:
+## Quirks
+
+When using the Firebase JS SDK on Android and iOS, you must be aware of the following:
 
-- `firebase@9.0.1`
-- `@capacitor-firebase/authentication@0.1.0`
+- **Apple Sign-In** works on Android and iOS only with `skipNativeAuth=true` (see [here](https://github.com/robingenz/capacitor-firebase-authentication/issues/41#issuecomment-884106449)).
+- **Twitter Sign-In** works on iOS only with `skipNativeAuth=false` (see [here](https://github.com/robingenz/capacitor-firebase-authentication/issues/93#issuecomment-939459594)).
+
+**Note**: The [`skipNativeAuth`](/packages/authentication/README.md#configuration) configuration option can be overwritten for each plugin call individually (see `skipNativeAuth` parameter in [SignInOptions](/packages/authentication/README.md#signinoptions)).