事件

Msal-Browser （@azure/msal-browser） 從版本 2.4 開始，提供事件 API，供我們核心函式庫與包裝函式庫的使用者使用。 這些事件與驗證及 MSAL 的功能有關，可用於應用程式更新介面、顯示錯誤訊息等。

事件的樣貌

export type EventMessage = {
    eventType: EventType;
    interactionType: InteractionType | null;
    payload: EventPayload;
    error: EventError;
    timestamp: number;
};

有效載荷與誤 EventMessage 差定義如下：

export type EventPayload = PopupRequest | RedirectRequest | SilentRequest | SsoSilentRequest | EndSessionRequest | AuthenticationResult | PopupEvent | null;

export type EventError = AuthError | Error | null;

MSAL 瀏覽器中事件的發射方式

MSAL 瀏覽器具有受保護的功能 emitEvent，會在主要 API 中發出事件。 目前已發射的事件列表，請見下表。

以下是一個 msal-browser 如何發出帶有有效載荷或錯誤事件的範例：

this.emitEvent(EventType.LOGIN_SUCCESS, InteractionType.Redirect, result);

this.emitEvent(EventType.LOGIN_FAILURE, InteractionType.Redirect, null, e);

如何使用事件 API

MSAL 瀏覽器匯 addEventCallback 出包含回調函式的函式，並可用於處理已發出的事件。

以下是你可以在應用程式中處理所發出事件的範例：

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    // Update UI or interact with EventMessage here
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        console.log(message.payload);
     }
});

新增事件回調會回傳一個 ID。此 id 可用來移除回調，如有需要，並可使用 removeEventCallback msal-browser 匯出的函式：

msalInstance.removeEventCallback(callbackId);

處理錯誤

由於 EventError 定義方式，處理事件所產生錯誤時，可能需要先驗證錯誤類型是否正確，才能存取該錯誤的具體屬性。 錯誤可被鑄造為 AuthError 或檢查其為 的實例 AuthError。

以下是一個消費已發射事件並投擲錯誤的範例：

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    // Update UI or interact with EventMessage here
    if (message.eventType === EventType.LOGIN_FAILURE) {
        if (message.error instanceof AuthError) {
            // Do something with the error
        }
     }
});

從活動中獲取互動狀態

你可以透過 getInteractionStatusFromEvent API 從事件中取得當前互動狀態：

以下是一個在沒有互動進行時顯示訊息的範例：

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    const status = EventMessageUtils.getInteractionStatusFromEvent(message);

    // Update UI or interact with EventMessage here
    if (status === InteractionStatus.None) {
        console.log(message.payload);
    }
});

跨分頁和視窗同步登入狀態

如果你想在使用者登出應用程式或在不同分頁或視窗更改活躍帳號時更新使用者介面，你可以訂閱 LOGIN_SUCCESS、 LOGOUT_SUCCESS和 ACTIVE_ACCOUNT_CHANGED 活動。

  • 帳號新增或移除時，payload 會是被新增或移除的 AccountInfo 物件。
  • 對於主動帳號更新，則不會有有效載荷
msalInstance.addEventCallback((message: EventMessage) => {
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        // Update UI with new account
    } else if (message.eventType === EventType.LOGOUT_SUCCESS) {
        // Update UI with account logged out
    } else if (message.eventType === EventType.ACTIVE_ACCOUNT_CHANGED) {
        const accountInfo = msalInstance.getActiveAccount();
        // Update UI with new active account info
    }
});

事件表

這些是目前 msal-browser 所發出的事件。

事件類型 Description 互動類型 有效負載 錯誤
LOGIN_START LoginPopup 或 loginRedirect 稱為 Popup 或 Redirect 彈出請求 或 重定向請求
LOGIN_SUCCESS 成功登入 Popup 或 Redirect AccountInfo
LOGIN_FAILURE 登入時出現錯誤 Popup 或 Redirect AuthError 或 Error（錯誤）
ACQUIRE_TOKEN_START AcquireTokenPopup 或 acquireTokenRedirect 或 acquireTokenSilent 稱為 Popup、Redirect 或 Silent 彈出請求、重定向請求或靜默請求
ACQUIRE_TOKEN_SUCCESS 成功從快取或網路取得的令牌 Popup、Redirect 或 Silent 認證結果
ACQUIRE_TOKEN_FAILURE 取得令牌時的錯誤 Popup、Redirect 或 Silent AuthError 或 Error（錯誤）
ACQUIRE_TOKEN_NETWORK_START 開始從網路取得代幣 Silent
SSO_SILENT_START SsoSilent API 呼叫 Silent SsoSilentRequest
SSO_SILENT_SUCCESS SsoSilent 成功了 Silent 認證結果
SSO_SILENT_FAILURE SsoSilent 失敗了 Silent AuthError 或 Error（錯誤）
HANDLE_REDIRECT_START HandleRedirectPromise 呼叫 Redirect
HANDLE_REDIRECT_END HandleRedirectPromise 完成 Redirect
LOGOUT_START 登出通話 Redirect 或 Popup 結束會話請求 或 結束會話彈出請求
LOGOUT_END 登出結束 Redirect 或 Popup
LOGOUT_SUCCESS 登出成功 Redirect 或 Popup 結束會話請求 或 結束會話彈出請求
LOGOUT_FAILURE 登出失敗 Redirect 或 Popup AuthError 或 Error（錯誤）
ACTIVE_ACCOUNT_CHANGED 在不同的分頁或視窗中，活躍帳號篩選條件被更改了 N/A N/A N/A
INITIALIZE_START 初始化函式為 N/A N/A N/A
INITIALIZE_END 初始化功能完成 N/A N/A N/A
  • Last updated on