From d379df030080aee6632945fe7b54311ac31f5378 Mon Sep 17 00:00:00 2001 From: Robin Genz Date: Fri, 6 Jan 2023 14:47:33 +0100 Subject: [PATCH] docs: improve docs regarding firebase js sdk (#262) --- packages/app-check/README.md | 21 ++----- packages/app-check/docs/firebase-js-sdk.md | 34 ++++++++++ packages/authentication/README.md | 17 ++--- .../authentication/docs/firebase-js-sdk.md | 62 ++++++++++--------- 4 files changed, 82 insertions(+), 52 deletions(-) create mode 100644 packages/app-check/docs/firebase-js-sdk.md diff --git a/packages/app-check/README.md b/packages/app-check/README.md index 27b2fa4a..87e26bcf 100644 --- 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 new file mode 100644 index 00000000..61a15ffd --- /dev/null +++ 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 }); +}; +``` \ No newline at end of file diff --git a/packages/authentication/README.md b/packages/authentication/README.md index bd137e49..d63396d6 100644 --- 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,9 +244,10 @@ 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; } @@ -250,9 +255,7 @@ const signInWithEmailLink = async () => { 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 index bc878998..66cf1d4a 100644 --- 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)).