# 入門指南

本指南將引導您完成使用 `@arcblock/did-connect-react` 將去中心化身分（DID）驗證整合到您的 React 應用程式中的基本步驟。只需幾分鐘，您就可以擁有一個功能齊全的登入和登出流程。

### 前提條件

在開始之前，請確保您的開發環境符合以下標準：

- 您已設定好一個 React 專案。
- 您有一個正在執行的 Blocklet Server 實例，它將處理驗證請求。該函式庫旨在與由 Blocklet Server 驅動的後端無縫協作。

## 步驟 1：安裝函式庫

首先，將 `@arcblock/did-connect-react` 套件新增到您的專案中。您可以使用 npm 或 yarn。

```bash Install with npm icon=logos:npm
npm install @arcblock/did-connect-react
```

```bash Install with yarn icon=logos:yarn
yarn add @arcblock/did-connect-react
```

## 步驟 2：設定 SessionProvider

`SessionProvider` 是該函式庫的核心。它是一個 context provider，負責管理使用者的會話狀態（如登入狀態和使用者資訊），並將其提供給所有被它包裹的元件。您應該將它放在應用程式的根部，例如，在您的 `App.js` 檔案中。

對於基於 Blocklet 建構的應用程式，建議使用 `createAuthServiceSessionContext` 工廠函數來初始化 provider。

```javascript App.js icon=logos:react
import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import Home from './Home'; // 我們將在下一步建立此元件

// createAuthServiceSessionContext 專為 Blocklet 環境進行了最佳化
const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    // serviceHost 屬性指向您後端驗證服務的基礎路徑。
    // 對於標準的 Blocklet，這通常是 blocklet 的前綴或 '/'。
    <SessionProvider serviceHost="/">
      <Home />
    </SessionProvider>
  );
}

export default App;
```

## 步驟 3：實作登入和登出

現在，讓我們建立一個允許使用者登入和登出的元件。我們可以使用 React 的 `useContext` hook 搭配 `SessionContext` 來存取會話資料和函數。

`session` 物件為您提供了所需的一切：目前的 `user`、`loading` 狀態，以及像 `login()` 和 `logout()` 這樣的函數。

```javascript Home.js icon=logos:react
import React, { useContext } from 'react';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import Button from '@arcblock/ux/lib/Button'; // 一個通用按鈕
import CircularProgress from '@mui/material/CircularProgress';

function Home() {
  // 存取會話 context
  const { session } = useContext(SessionContext);

  // 解構以便於存取
  const { user, loading, login, logout } = session;

  // 在會話初始化期間顯示載入指示器
  if (loading) {
    return <CircularProgress />;
  }

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      {user ? (
        // 如果使用者已登入，顯示他們的 DID 和一個登出按鈕
        <div>
          <h1>歡迎！</h1>
          <p>您的 DID： {user.did}</p>
          <Button variant="contained" color="secondary" onClick={logout}>
            登出
          </Button>
        </div>
      ) : (
        // 如果未登入，顯示登入按鈕
        <div>
          <h1>請登入</h1>
          <ConnectButton onClick={() => login()}>
            連接錢包
          </ConnectButton>
        </div>
      )}
    </div>
  );
}

export default Home;
```

當使用者點擊 `ConnectButton` 時，會呼叫 `login()` 函數。此函數負責打開 DID Connect 彈出視窗，該視窗會顯示一個 QR code 供使用者使用他們的 DID Wallet 掃描，並管理整個驗證過程。

## 步驟 4：存取使用者資料

一旦使用者成功登入，`session.user` 物件將會被填入資料。此物件包含從使用者的 DID Wallet 中檢索到的個人資料資訊。

由 context 提供的 `session` 物件是您與使用者驗證狀態互動的主要介面。以下是其關鍵屬性：

<x-field-group>
  <x-field data-name="user" data-type="object | null" data-desc="已驗證的使用者物件。如果沒有使用者登入，則為 `null`。">
    <x-field data-name="did" data-type="string" data-desc="使用者的去中心化身分識別碼（DID）。"></x-field>
    <x-field data-name="fullName" data-type="string" data-desc="來自使用者錢包個人資料的全名。"></x-field>
    <x-field data-name="email" data-type="string" data-desc="來自使用者錢包個人資料的電子郵件。"></x-field>
  </x-field>
  <x-field data-name="loading" data-type="boolean" data-desc="在會話初始化或刷新期間為 `true`，否則為 `false`。"></x-field>
  <x-field data-name="login" data-type="function" data-desc="一個啟動登入過程的函數，它會打開 DID Connect 使用者介面。"></x-field>
  <x-field data-name="logout" data-type="function" data-desc="一個將使用者登出並清除會話的函數。"></x-field>
  <x-field data-name="initialized" data-type="boolean" data-desc="初始會話檢查完成後為 `true`。"></x-field>
</x-field-group>

## 你已完成所有設定！

恭喜！您已成功在您的 React 應用程式中實作了一個完整的基於 DID 的驗證流程。使用者現在可以使用他們的 DID Wallet 登入，您的應用程式也可以安全地存取他們的會話資訊。

### 後續步驟

要深入了解並探索更多進階功能，請查看以下部分：

<x-cards>
  <x-card data-title="會話管理 (SessionProvider)" data-icon="lucide:key-round" data-href="/core-components/session-provider">
    了解 SessionProvider 的所有設定選項，以自訂會話行為、逾時等。
  </x-card>
  <x-card data-title="連接 UI (DidConnect)" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
    探索 DidConnect 元件，以一種宣告式的方式將連接 UI 直接嵌入到您的頁面中。
  </x-card>
</x-cards>