Authentication flow

This page tracks the account flow of a React app with Analytics Web and its hooks from @grainql/analytics-web/react. Every block uses Analytics Web. trackSignup sends the signup event and trackLogin sends the login event. login and logout set and clear the user ID. Read Identify users. Call trackSignup with the result of the signup. On success, call login with the new user ID and set the properties that the dashboard segments by. trackSignup takes method, source, plan, success, and errorMessage.

import { useGrainAnalytics } from '@grainql/analytics-web/react';
import { useRouter } from 'next/navigation';

export function SignupForm() {
  const grain = useGrainAnalytics();
  const router = useRouter();

  const handleSignup = async (email: string, password: string) => {
    try {
      const user = await createUser(email, password);

      grain.login({ userId: user.id });
      grain.trackSignup({ method: 'email', source: 'signup_page', plan: 'free', success: true });
      grain.setProperty({ plan: 'free', signup_method: 'email' });

      router.push('/welcome');
    } catch (error) {
      grain.trackSignup({
        method: 'email',
        source: 'signup_page',
        success: false,
        errorMessage: (error as Error).message
      });
    }
  };

  return <form onSubmit={...}>...</form>;
}

login runs before trackSignup, so the signup event holds the new user ID. trackLogin takes method, success, errorMessage, loginAttempt, rememberMe, and twoFactorEnabled. Count the attempts in the component, so a failed login and the retry after it show as one sequence.

import { useGrainAnalytics } from '@grainql/analytics-web/react';
import { useRouter } from 'next/navigation';
import { useState } from 'react';

export function LoginForm() {
  const grain = useGrainAnalytics();
  const router = useRouter();
  const [attempt, setAttempt] = useState(0);

  const handleLogin = async (email: string, password: string, rememberMe: boolean) => {
    const current = attempt + 1;
    setAttempt(current);

    try {
      const user = await authenticateUser(email, password);

      grain.login({ userId: user.id });
      grain.trackLogin({ method: 'email', success: true, rememberMe, loginAttempt: current });

      router.push('/dashboard');
    } catch (error) {
      grain.trackLogin({
        method: 'email',
        success: false,
        errorMessage: (error as Error).message,
        loginAttempt: current
      });
    }
  };

  return <form onSubmit={...}>...</form>;
}

If your backend returns a JWT for GrainQL, pass it as authToken. login({ userId, authToken }) switches the client to the JWT strategy. Read Authentication. The provider name goes in method. The rest of the flow is the same as the email login.

import { useGrainAnalytics } from '@grainql/analytics-web/react';

export function SocialLogin() {
  const grain = useGrainAnalytics();

  const handleSocialLogin = async (provider: 'google' | 'github') => {
    try {
      const user = await loginWithProvider(provider);

      grain.login({ userId: user.id });
      grain.trackLogin({ method: provider, success: true });
      grain.setProperty({ login_method: provider });

      window.location.href = '/dashboard';
    } catch (error) {
      grain.trackLogin({ method: provider, success: false, errorMessage: (error as Error).message });
    }
  };

  return (
    <div>
      <button onClick={() => handleSocialLogin('google')}>Continue with Google</button>
      <button onClick={() => handleSocialLogin('github')}>Continue with GitHub</button>
    </div>
  );
}

Logout

Track the logout while the user ID is still set, with { flush: true }. Then call logout. logout clears the user ID and returns the client to an anonymous ID.

import { useGrainAnalytics } from '@grainql/analytics-web/react';
import { useRouter } from 'next/navigation';

export function LogoutButton() {
  const grain = useGrainAnalytics();
  const router = useRouter();

  const handleLogout = async () => {
    await grain.track('logout', {}, { flush: true });
    grain.logout();
    await signOut();
    router.push('/login');
  };

  return <button onClick={handleLogout}>Logout</button>;
}

Call logout on every sign-out. If the user ID stays set, the events of the next user on the same browser go to the previous user.

Password reset

There is no template method for a password reset. Use track. The visitor is not logged in, so the event holds the anonymous ID.

import { useTrack } from '@grainql/analytics-web/react';
import { useState } from 'react';

export function ForgotPasswordForm() {
  const track = useTrack();
  const [sent, setSent] = useState(false);

  const handleSubmit = async (email: string) => {
    try {
      await sendPasswordResetEmail(email);
      track('password_reset_requested', { success: true });
      setSent(true);
    } catch (error) {
      track('password_reset_requested', { success: false, error: (error as Error).message });
    }
  };

  if (sent) {
    return <p>Check your email for the reset link.</p>;
  }

  return <form onSubmit={...}>...</form>;
}

createUser, authenticateUser, loginWithProvider, signOut, and sendPasswordResetEmail are functions of your app. Read Template events.

Apps

Query API

Authentication flow

Logout

Password reset

​Signup

​Login

​Social login

​Logout

​Password reset

Signup

Login

Social login

Logout

Password reset