@pbackup/authentication v1.1.1

@capacitor-firebase/authentication

⚡️ Capacitor plugin for Firebase Authentication.

Installation

npm install @capacitor-firebase/authentication firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

On iOS, verify that this function is included in your app's AppDelegate.swift:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
  return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}

Attention: If you use this plugin on iOS in combination with @capacitor-firebase/messaging, then add the following to your app's AppDelegate.swift:

+ import FirebaseAuth

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    if Auth.auth().canHandle(url) {
+      return true
+    }
    return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
}

The further installation steps depend on the selected authentication method:

• Apple Sign-In
• Facebook Sign-In
• GitHub Sign-In
• Google Sign-In
• Microsoft Sign-In
• Play Games Sign-In
• Twitter Sign-In

• Yahoo Sign-In

• Anonymous Sign-In

• Email Link Sign-In
• Phone Number Sign-In
• Custom Token Sign-In

Attention: Please note that this plugin uses third-party SDKs to offer native sign-in. These SDKs can initialize on their own and collect various data. Here you can find more information.

Configuration

These configuration values are available:

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseAuthentication": {
      "skipNativeAuth": false,
      "providers": ["apple.com", "facebook.com"]
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor/firebase-authentication" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseAuthentication: {
      skipNativeAuth: false,
      providers: ["apple.com", "facebook.com"],
    },
  },
};

export default config;

FAQ

1. What does this plugin do?
   This plugin enables the use of Firebase Authentication in a Capacitor app. It uses the Firebase SDK for Java (Android), Swift (iOS) and JavaScript.
2. What is the difference between the web implementation of this plugin and the Firebase JS SDK?
   The web implementation of this plugin encapsulates the Firebase JS SDK and enables a consistent interface across all platforms. You can decide if you prefer to use the web implementation or the Firebase JS SDK.
3. What is the difference between the native and web authentication?
   For web authentication, the Firebase JS SDK is used. This only works to a limited extent on Android and iOS in the WebViews (see here). For native authentication, the native SDKs from Firebase, Google, etc. are used. These offer all the functionalities that the Firebase JS SDK also offers on the web. However, after a login with the native SDK, the user is only logged in on the native layer of the app. If the user should also be logged in on the web layer, additional steps are required (see here).
4. How can I use this plugin with the Firebase JavaScript SDK?
   See here.

Demo

A working example can be found here: robingenz/capacitor-firebase-authentication-demo

Usage

import { FirebaseAuthentication } from '@capacitor-firebase/authentication';

const applyActionCode = async () => {
  await FirebaseAuthentication.applyActionCode({ oobCode: '1234' });
};

const createUserWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
    email: 'mail@exmaple.com',
    password: '1234',
  });
  return result.user;
};

const confirmPasswordReset = async () => {
  await FirebaseAuthentication.confirmPasswordReset({
    oobCode: '1234',
    newPassword: '4321',
  });
};

const getCurrentUser = async () => {
  const result = await FirebaseAuthentication.getCurrentUser();
  return result.user;
};

const getIdToken = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  const result = await FirebaseAuthentication.getIdToken();
  return result.token;
};

const sendEmailVerification = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.sendEmailVerification();
};

const sendPasswordResetEmail = async () => {
  await FirebaseAuthentication.sendPasswordResetEmail({
    email: 'mail@example.com',
  });
};

const sendSignInLinkToEmail = async () => {
  const email = 'mail@example.com';
  await FirebaseAuthentication.sendSignInLinkToEmail({
    email,
    actionCodeSettings: {
      // URL you want to redirect back to. The domain (www.example.com) for this
      // URL must be in the authorized domains list in the Firebase Console.
      url: 'https://www.example.com/finishSignUp?cartId=1234',
      // This must be true.
      handleCodeInApp: true,
      iOS: {
        bundleId: 'com.example.ios',
      },
      android: {
        packageName: 'com.example.android',
        installApp: true,
        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
  // if they open the link on the same device.
  window.localStorage.setItem('emailForSignIn', email);
};

const setLanguageCode = async () => {
  await FirebaseAuthentication.setLanguageCode({ languageCode: 'en-US' });
};

const signInAnonymously = async () => {
  const result = await FirebaseAuthentication.signInAnonymously();
  return result.user;
};

const signInWithApple = async () => {
  const result = await FirebaseAuthentication.signInWithApple();
  return result.user;
};

const signInWithCustomToken = async () => {
  const result = await FirebaseAuthentication.signInWithCustomToken({
    token: '1234',
  });
  return result.user;
};

const signInWithEmailAndPassword = async () => {
  const result = await FirebaseAuthentication.signInWithEmailAndPassword({
    email: 'mail@example.com',
    password: '1234',
  });
  return result.user;
};

const signInWithEmailLink = async () => {
  // Get the email if available. This should be available if the user completes
  // 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 result = await FirebaseAuthentication.isSignInWithEmailLink({
    emailLink,
  });
  if (
    result.isSignInWithEmailLink
  ) {
    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.',
      );
    }
    // The client SDK will parse the code from the link for you.
    const result = await FirebaseAuthentication.signInWithEmailLink({
      email,
      emailLink,
    });
    // Clear email from storage.
    window.localStorage.removeItem('emailForSignIn');
    return result.user;
  } else {
    alert('emailLink is invalid.');
  }
};

const signInWithFacebook = async () => {
  const result = await FirebaseAuthentication.signInWithFacebook();
  return result.user;
};

const signInWithGithub = async () => {
  const result = await FirebaseAuthentication.signInWithGithub();
  return result.user;
};

const signInWithGoogle = async () => {
  const result = await FirebaseAuthentication.signInWithGoogle();
  return result.user;
};

const signInWithMicrosoft = async () => {
  const result = await FirebaseAuthentication.signInWithMicrosoft();
  return result.user;
};

const signInWithPlayGames = async () => {
  const result = await FirebaseAuthentication.signInWithPlayGames();
  return result.user;
};

const signInWithPhoneNumber = async () => {
  const { verificationId } = await FirebaseAuthentication.signInWithPhoneNumber(
    {
      phoneNumber: '123456789',
    },
  );
  const verificationCode = window.prompt(
    'Please enter the verification code that was sent to your mobile device.',
  );
  const result = await FirebaseAuthentication.signInWithPhoneNumber({
    verificationId,
    verificationCode,
  });
  return result.user;
};

const signInWithTwitter = async () => {
  const result = await FirebaseAuthentication.signInWithTwitter();
  return result.user;
};

const signInWithYahoo = async () => {
  const result = await FirebaseAuthentication.signInWithYahoo();
  return result.user;
};

const signOut = async () => {
  await FirebaseAuthentication.signOut();
};

const updateEmail = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updateEmail({
    newEmail: 'new.mail@example.com',
  });
};

const updatePassword = async () => {
  const currentUser = getCurrentUser();
  if (!currentUser) {
    return;
  }
  await FirebaseAuthentication.updatePassword({
    newPassword: '4321',
  });
};

const useAppLanguage = async () => {
  await FirebaseAuthentication.useAppLanguage();
};

const useEmulator = async () => {
  await FirebaseAuthentication.useEmulator({
    host: '10.0.2.2',
    port: 9099,
  });
};

API

• applyActionCode(...)
• createUserWithEmailAndPassword(...)
• confirmPasswordReset(...)
• getCurrentUser()
• getIdToken(...)
• getTenantId()
• isSignInWithEmailLink(...)
• linkWithApple(...)
• linkWithEmailAndPassword(...)
• linkWithEmailLink(...)
• linkWithFacebook(...)
• linkWithGithub(...)
• linkWithGoogle(...)
• linkWithMicrosoft(...)
• linkWithPhoneNumber(...)
• linkWithPlayGames(...)
• linkWithTwitter(...)
• linkWithYahoo(...)
• sendEmailVerification()
• sendPasswordResetEmail(...)
• sendSignInLinkToEmail(...)
• setLanguageCode(...)
• setTenantId(...)
• signInAnonymously()
• signInWithApple(...)
• signInWithCustomToken(...)
• signInWithEmailAndPassword(...)
• signInWithEmailLink(...)
• signInWithFacebook(...)
• signInWithGithub(...)
• signInWithGoogle(...)
• signInWithMicrosoft(...)
• signInWithPhoneNumber(...)
• signInWithPlayGames(...)
• signInWithTwitter(...)
• signInWithYahoo(...)
• signOut()
• unlink(...)
• updateEmail(...)
• updatePassword(...)
• useAppLanguage()
• useEmulator(...)
• addListener('authStateChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

applyActionCode(...)

applyActionCode(options: ApplyActionCodeOptions) => Promise<void>

Applies a verification code sent to the user by email.

Since: 0.2.2

createUserWithEmailAndPassword(...)

createUserWithEmailAndPassword(options: CreateUserWithEmailAndPasswordOptions) => Promise<SignInResult>

Creates a new user account with email and password. If the new account was created, the user is signed in automatically.

Returns: Promise<SignInResult>

Since: 0.2.2

confirmPasswordReset(...)

confirmPasswordReset(options: ConfirmPasswordResetOptions) => Promise<void>

Completes the password reset process.

Since: 0.2.2

getCurrentUser()

getCurrentUser() => Promise<GetCurrentUserResult>

Fetches the currently signed-in user.

Returns: Promise<GetCurrentUserResult>

Since: 0.1.0

getIdToken(...)

getIdToken(options?: GetIdTokenOptions | undefined) => Promise<GetIdTokenResult>

Fetches the Firebase Auth ID Token for the currently signed-in user.

Returns: Promise<GetIdTokenResult>

Since: 0.1.0

getTenantId()

getTenantId() => Promise<GetTenantIdResult>

Get the tenant id.

Returns: Promise<GetTenantIdResult>

Since: 1.1.0

isSignInWithEmailLink(...)

isSignInWithEmailLink(options: IsSignInWithEmailLinkOptions) => Promise<IsSignInWithEmailLinkResult>

Checks if an incoming link is a sign-in with email link suitable for signInWithEmailLink.

Returns: Promise<IsSignInWithEmailLinkResult>

Since: 1.1.0

linkWithApple(...)

linkWithApple(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Apple authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithEmailAndPassword(...)

linkWithEmailAndPassword(options: LinkWithEmailAndPasswordOptions) => Promise<LinkResult>

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithEmailLink(...)

linkWithEmailLink(options: LinkWithEmailLinkOptions) => Promise<LinkResult>

Links the user account with Email authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithFacebook(...)

linkWithFacebook(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Facebook authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithGithub(...)

linkWithGithub(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with GitHub authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithGoogle(...)

linkWithGoogle(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Google authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithMicrosoft(...)

linkWithMicrosoft(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Microsoft authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithPhoneNumber(...)

linkWithPhoneNumber(options: LinkWithPhoneNumberOptions) => Promise<LinkResult>

Links the user account with Phone Number authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithPlayGames(...)

linkWithPlayGames(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Play Games authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithTwitter(...)

linkWithTwitter(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Twitter authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

linkWithYahoo(...)

linkWithYahoo(options?: SignInWithOAuthOptions | undefined) => Promise<LinkResult>

Links the user account with Yahoo authentication provider.

The user must be logged in on the native layer. The skipNativeAuth configuration option has no effect here.

Returns: Promise<SignInResult>

Since: 1.1.0

sendEmailVerification()

sendEmailVerification() => Promise<void>

Sends a verification email to the currently signed in user.

Since: 0.2.2

sendPasswordResetEmail(...)

sendPasswordResetEmail(options: SendPasswordResetEmailOptions) => Promise<void>

Sends a password reset email.

Since: 0.2.2

sendSignInLinkToEmail(...)

sendSignInLinkToEmail(options: SendSignInLinkToEmailOptions) => Promise<void>

Sends a sign-in email link to the user with the specified email.

To complete sign in with the email link, call signInWithEmailLink with the email address and the email link supplied in the email sent to the user.

Since: 1.1.0

setLanguageCode(...)

setLanguageCode(options: SetLanguageCodeOptions) => Promise<void>

Sets the user-facing language code for auth operations.

Since: 0.1.0

setTenantId(...)

setTenantId(options: SetTenantIdOptions) => Promise<void>

Sets the tenant id.

Since: 1.1.0

signInAnonymously()

signInAnonymously() => Promise<SignInResult>

Signs in as an anonymous user.

Returns: Promise<SignInResult>

Since: 1.1.0

signInWithApple(...)

signInWithApple(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Apple sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithCustomToken(...)

signInWithCustomToken(options: SignInWithCustomTokenOptions) => Promise<SignInResult>

Starts the Custom Token sign-in flow.

This method cannot be used in combination with skipNativeAuth on Android and iOS. In this case you have to use the signInWithCustomToken interface of the Firebase JS SDK directly.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithEmailAndPassword(...)

signInWithEmailAndPassword(options: SignInWithEmailAndPasswordOptions) => Promise<SignInResult>

Starts the sign-in flow using an email and password.

Returns: Promise<SignInResult>

Since: 0.2.2

signInWithEmailLink(...)

signInWithEmailLink(options: SignInWithEmailLinkOptions) => Promise<SignInResult>

Signs in using an email and sign-in email link.

Returns: Promise<SignInResult>

Since: 1.1.0

signInWithFacebook(...)

signInWithFacebook(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Facebook sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithGithub(...)

signInWithGithub(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the GitHub sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithGoogle(...)

signInWithGoogle(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Google sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithMicrosoft(...)

signInWithMicrosoft(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Microsoft sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithPhoneNumber(...)

signInWithPhoneNumber(options: SignInWithPhoneNumberOptions) => Promise<SignInWithPhoneNumberResult>

Starts the sign-in flow using a phone number.

Either the phone number or the verification code and verification ID must be provided.

Only available for Android and iOS.

Returns: Promise<SignInWithPhoneNumberResult>

Since: 0.1.0

signInWithPlayGames(...)

signInWithPlayGames(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Play Games sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithTwitter(...)

signInWithTwitter(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Twitter sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signInWithYahoo(...)

signInWithYahoo(options?: SignInWithOAuthOptions | SignInOptions | undefined) => Promise<SignInResult>

Starts the Yahoo sign-in flow.

Returns: Promise<SignInResult>

Since: 0.1.0

signOut()

signOut() => Promise<void>

Starts the sign-out flow.

Since: 0.1.0

unlink(...)

unlink(options: UnlinkOptions) => Promise<UnlinkResult>

Unlinks a provider from a user account.

Returns: Promise<UnlinkResult>

Since: 1.1.0

updateEmail(...)

updateEmail(options: UpdateEmailOptions) => Promise<void>

Updates the email address of the currently signed in user.

Since: 0.1.0

updatePassword(...)

updatePassword(options: UpdatePasswordOptions) => Promise<void>

Updates the password of the currently signed in user.

Since: 0.1.0

useAppLanguage()

useAppLanguage() => Promise<void>

Sets the user-facing language code to be the default app language.

Since: 0.1.0

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Authentication emulator.

Since: 0.2.0

addListener('authStateChange', ...)

addListener(eventName: 'authStateChange', listenerFunc: AuthStateChangeListener) => Promise<PluginListenerHandle> & PluginListenerHandle

Listen for the user's sign-in state changes.

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

ApplyActionCodeOptions

SignInResult

User

AuthCredential

AdditionalUserInfo

CreateUserWithEmailAndPasswordOptions

ConfirmPasswordResetOptions

GetCurrentUserResult

GetIdTokenResult

GetIdTokenOptions

GetTenantIdResult

IsSignInWithEmailLinkResult

IsSignInWithEmailLinkOptions

SignInWithOAuthOptions

SignInCustomParameter

LinkWithEmailAndPasswordOptions

LinkWithEmailLinkOptions

LinkWithPhoneNumberOptions

SendPasswordResetEmailOptions

SendSignInLinkToEmailOptions

ActionCodeSettings

An interface that defines the required continue/state URL with optional Android and iOS bundle identifiers.

SetLanguageCodeOptions

SetTenantIdOptions

SignInOptions

SignInWithCustomTokenOptions

SignInWithEmailAndPasswordOptions

SignInWithEmailLinkOptions

SignInWithPhoneNumberResult

SignInWithPhoneNumberOptions

UnlinkResult

UnlinkOptions

UpdateEmailOptions

UpdatePasswordOptions

UseEmulatorOptions

PluginListenerHandle

AuthStateChange

Type Aliases

LinkWithOAuthOptions

SignInWithOAuthOptions

LinkResult

SignInResult

AuthStateChangeListener

Callback to receive the user's sign-in state change notifications.

(change: AuthStateChange): void

Enums

ProviderId

Changelog

See CHANGELOG.md.

License

See LICENSE.

Credits

This plugin is based on the Capacitor Firebase Authentication plugin. Thanks to everyone who contributed to the project!