What the difference between authStateChanges(), userChanges(), and idTokenChanges() Firebase Auth Events/Streams in Flutter

Firebase Authentication is a powerful tool for managing user authentication and authorization in your Flutter applications. In Flutter, Firebase provides three key streams or Firebase Auth Events to monitor authentication-related events: authStateChanges(), userChanges(), and idTokenChanges(). Understanding when and how to use these streams is crucial for building robust and secure applications. This article thoroughly explores each stream, providing practical examples to help you decide which one to use in various scenarios.

1. authStateChanges() Firebase Auth Event

The authStateChanges() stream in Flutter Firebase Auth is triggered whenever the user’s authentication state changes. This includes when a user signs in, signs out, or when the user’s ID token is refreshed.

Key Points:

• Fired when the user signs in or signs out.
• Triggered when the user’s ID token is refreshed.
• Used to detect whether a user is authenticated or not.

Example:

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: AuthStateExample(),
    );
  }
}

class AuthStateExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: FirebaseAuth.instance.authStateChanges(),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return CircularProgressIndicator();
        } else if (snapshot.hasData) {
          return HomePage();
        } else {
          return SignInPage();
        }
      },
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Home'),
      ),
      body: Center(
        child: Text('User is signed in.'),
      ),
    );
  }
}

class SignInPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sign In'),
      ),
      body: Center(
        child: Text('User is not signed in.'),
      ),
    );
  }
}

Use Case:
Use authStateChanges() to update the UI based on the user’s authentication status. This stream is ideal for determining if a user is signed in or out and for navigating between different screens based on the authentication state.

2. userChanges() Firebase Auth Event

The userChanges() stream is triggered whenever the properties of the User object change. This includes changes to the user’s profile, email, or password.

Key Points:

• Fired when the properties of the User object change.
• Triggered on profile updates like display name or photo URL change.
• Can also trigger on password or email changes.

Example:

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: UserChangeExample(),
    );
  }
}

class UserChangeExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: FirebaseAuth.instance.userChanges(),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return CircularProgressIndicator();
        } else if (snapshot.hasData) {
          User? user = snapshot.data;
          return ProfilePage(user: user);
        } else {
          return SignInPage();
        }
      },
    );
  }
}

class ProfilePage extends StatelessWidget {
  final User? user;

  ProfilePage({required this.user});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Profile'),
      ),
      body: Center(
        child: Text('User profile: ${user?.displayName}'),
      ),
    );
  }
}

class SignInPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sign In'),
      ),
      body: Center(
        child: Text('User is not signed in.'),
      ),
    );
  }
}

Use Case:
Use userChanges() to update the UI based on changes to the user’s profile or other properties. This stream is useful for scenarios where you need to respond to updates in user information, such as displaying the updated profile name or photo.

3. idTokenChanges() Firebase Auth Event

The idTokenChanges() stream is triggered whenever the ID token of the user is updated. This includes the initial sign-in and subsequent token refreshes.

Key Points:

• Triggered when the user’s ID token is refreshed.
• Fired on initial sign-in and subsequent token refreshes.
• Ensures that you always have a valid ID token for authenticated requests.

Example:

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: IdTokenChangeExample(),
    );
  }
}

class IdTokenChangeExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: FirebaseAuth.instance.idTokenChanges(),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return CircularProgressIndicator();
        } else if (snapshot.hasData) {
          User? user = snapshot.data;
          user?.getIdToken().then((token) {
            print('ID token: $token');
            // Use the token for authenticated requests.
          });
          return HomePage();
        } else {
          return SignInPage();
        }
      },
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Home'),
      ),
      body: Center(
        child: Text('User is signed in.'),
      ),
    );
  }
}

class SignInPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sign In'),
      ),
      body: Center(
        child: Text('User is not signed in.'),
      ),
    );
  }
}

Use Case:
Use idTokenChanges() to ensure that your application always has a valid ID token for making authenticated API requests. This stream is crucial for maintaining secure sessions and handling token expiration.

Choosing the Right Stream

When to use authStateChanges()

• You need to update the UI based on the user’s sign-in or sign-out state.
• You want to navigate between different screens based on the authentication status.

When to use userChanges()

• You need to respond to changes in the user’s profile information.
• You want to update the UI with the latest user details, such as display name or photo.

When to use idTokenChanges()

• You need to ensure that your application always has a valid ID token for authenticated API requests.
• You want to handle token refreshes seamlessly to maintain secure sessions.

Conclusion

Understanding the differences between authStateChanges(), userChanges(), and idTokenChanges() in Flutter Firebase Auth is crucial for building responsive and secure applications. Each stream serves a specific purpose, from monitoring authentication states and profile changes to handling ID token refreshes. By choosing the right stream for your needs, you can create a more efficient and user-friendly authentication flow in your Flutter applications.