Advanced Topics

Once you are comfortable with the core components like SessionProvider and DidConnect, you're ready to explore the more powerful and flexible features of the @arcblock/did-connect-react library. This section covers advanced subjects that allow you to build more sophisticated, robust, and user-friendly decentralized identity applications.

We will explore three main areas:

  1. Alternative Authentication Methods: Go beyond the default QR code scan and integrate popular login methods like OAuth (social login), Passkeys (passwordless), and Federated Login.
  2. Utility Functions: Leverage a suite of helper functions to handle common tasks such as URL encoding, creating API clients, and managing popups.
  3. Error Handling: Learn how to gracefully handle common errors, from blocked popups to WebAuthn API failures, ensuring a smooth user experience.


Authentication Methods#

While DID Connect is the primary authentication method, the library provides seamless integration with other popular login flows. This allows you to offer users multiple ways to sign in, catering to different preferences and security levels.

Utilities#

The library exports a collection of utility functions designed to simplify common tasks and reduce boilerplate code in your application. These helpers cover everything from data encoding and cryptographic operations to managing browser popups for authentication flows.

Error Handling#

Building a robust application requires graceful error handling. The @arcblock/did-connect-react library provides specific error types and helper functions to make this process easier.

When using authentication methods that require a popup window (like OAuth), the browser's popup blocker might interfere. The openPopup function will throw a NotOpenError if it fails to open the window. You should catch this error and provide appropriate feedback to the user.

Handling Popup Errors

import { openPopup, runPopup } from '@arcblock/did-connect-react/lib/utils';
import { NotOpenError } from '@arcblock/did-connect-react/lib/error';

async function startOAuthFlow(url) {
  try {
    const popup = openPopup(url);
    const result = await runPopup({ popup });
    console.log('OAuth successful:', result);
  } catch (err) {
    if (err instanceof NotOpenError) {
      alert('Popup was blocked. Please allow popups for this site and try again.');
    } else {
      alert(`An error occurred: ${err.message}`);
    }
  }
}

API and WebAuthn Errors#

For interactions with backend services or WebAuthn APIs (used by Passkeys), the library provides helper functions to parse complex error objects into user-friendly messages.

  • getApiErrorMessage(err, defaultMessage): Extracts an error message from an Axios error response.
  • getWebAuthnErrorMessage(err, defaultMessage, t): Handles WebAuthn-specific errors (e.g., user cancellation, unsupported browser) and provides translatable, user-friendly messages.

Handling WebAuthn Errors

import { usePasskey } from '@arcblock/did-connect-react';
import { getWebAuthnErrorMessage } from '@arcblock/did-connect-react/lib/utils';

function PasskeyLoginButton() {
  const { loginWithPasskey } = usePasskey();

  const handleLogin = async () => {
    try {
      await loginWithPasskey();
      // Handle successful login
    } catch (err) {
      // Use the utility to get a user-friendly message
      const friendlyMessage = getWebAuthnErrorMessage(err, 'An unknown error occurred.');
      alert(friendlyMessage);
    }
  };

  return <button onClick={handleLogin}>Login with Passkey</button>;
}

By implementing proper error handling, you can significantly improve the user experience when things don't go as planned.


Next Steps#

Now that you have an overview of the advanced capabilities, you can dive deeper into the topics that are most relevant to your project.

Logo
Authentication Methods