跳到主要內容

串接工作流程

DID Connect 讓您能夠將多個獨立的驗證會話連結在一起，從單一的初始互動為使用者建立一個無縫的多步驟流程。這對於複雜的場景非常理想，例如使用者註冊後接著進行 KYC，或登入後接著進行交易確認。

本指南將說明串接工作流程背後的機制，以及如何在它們之間傳遞資料。

核心機制

串接工作流程的關鍵在於 onAuth 生命週期回呼。當 DID Connect 會話中的一個步驟成功完成時，onAuth 處理程式不是簡單地結束會話，而是可以啟動一個新的會話，並指示使用者的錢包自動進行到下一個會話。

這是透過從 onAuth 函式中回傳兩個特定屬性來實現的：

  • nextWorkflow：下一個 DID Connect 會話的完整深層連結 URL。
  • nextToken：下一個工作流程的會話權杖。

當錢包收到包含 nextWorkflow 的回應時，它會立即開啟此 URL，開始流程的下一階段，而無需使用者掃描新的 QR Code。原始會話會保持在待處理狀態，直到整個工作流程鏈完成或被拒絕為止。

會話完成的運作方式

當您將會話 A 連結到會話 B 時：

  1. 會話 A 的 onAuth 回傳會話 B 的 nextWorkflow 和 nextToken。
  2. 會話 A 不會被標記為 succeed。相反地，它會記錄已被會話 B 接替。
  3. 當會話 B（鏈中的最終會話）成功完成時，它會將自己標記為 succeed。
  4. 然後它會尋找 prevToken（會話 A 的權杖），並將該會話也標記為 succeed，確保整個鏈被正確關閉。

Chaining Workflows

在工作流程之間傳遞資料

通常，您需要將上下文從一個步驟傳遞到下一個步驟。例如，將使用者的 DID 從登入步驟傳遞到後續的購買步驟。這是透過使用 nextWorkflowData 和 previousWorkflowData 來實現的。

  1. 發送資料

    在第一個會話的 onAuth 處理程式中，回傳一個名為 nextWorkflowData 的物件。此物件將被自動進行 Base64 編碼，並作為 previousWorkflowData 查詢參數附加到 nextWorkflow URL。

  2. 接收資料

    下一個會話將自動解析此參數。解碼後的資料將在該會話的所有生命週期掛鉤（onStart、onConnect、onAuth）內的 extraParams.previousWorkflowData 物件中可用。

如果您串接了兩個以上的工作流程（A → B → C），資料將會被合併。當會話 B 回傳自己的 nextWorkflowData 時，它會與從 A 收到的 previousWorkflowData 合併，並將合併後的物件傳遞給 C。

實作範例

讓我們考慮一個場景，使用者登入後立即被提示簽署一則歡迎訊息。

步驟 1：定義登入工作流程

在您的登入會話的 onAuth 處理程式中，您將為簽署訊息產生一個新的會話，並將其作為 nextWorkflow 回傳。

login-handler.js

javascript
// 這是一個簡化的範例。在實際應用程式中，您會有一個單獨的端點來產生權杖。
const { WalletHandlers, WalletAuthenticator } = require('@arcblock/did-connect');
const get = require('lodash/get');

// 假設 authenticator 和 tokenStorage 已被初始化
const authenticator = new WalletAuthenticator(/* ... */);
const tokenStorage = new MemoryAuthStorage();

const handlers = new WalletHandlers({ authenticator, tokenStorage });

// 第一步的處理程式：登入
handlers.attach({
  app: server,
  action: 'login',
  claims: { profile: { description: 'Please provide your profile' } },
  onAuth: async ({ userDid, claims }) => {
    const profile = claims.find(x => x.type === 'profile');
    console.log(`${userDid} with name ${profile.fullName} logged in.`);

    // 現在，為簽署訊息建立下一個工作流程
    // 在實際應用程式中，您會呼叫自己的權杖產生端點
    const { data: nextSession } = await axios.get('https://yourapp.com/api/did/sign/token');

    return {
      // 下一個會話的 URL 和權杖
      nextWorkflow: nextSession.url,
      nextToken: nextSession.token,
      // 將使用者名稱傳遞到下一步
      nextWorkflowData: {
        fullName: profile.fullName,
      },
    };
  },
});

步驟 2：定義簽章工作流程

此工作流程將從登入步驟接收使用者名稱，並用它來自訂簽章請求。

sign-handler.js

javascript
// 第二步的處理程式：簽署訊息
handlers.attach({
  app: server,
  action: 'sign',
  claims: {
    signature: ({ extraParams }) => {
      // 從前一個工作流程存取資料
      const fullName = get(extraParams, 'previousWorkflowData.fullName', 'user');
      return {
        type: 'mime:text/plain',
        description: `Hi ${fullName}, please sign this welcome message!`,
        data: `Welcome aboard, ${fullName}!`,
      };
    },
  },
  onAuth: async ({ userDid }) => {
    console.log(`${userDid} signed the welcome message.`);
    // 這是最後一步，所以我們不回傳 nextWorkflow
    return { successMessage: 'Onboarding complete!' };
  },
});

透過此設定，使用者只需掃描一個 QR Code 進行登入，批准後，其錢包中會立即顯示個人化的簽章請求。簽署後，整個多步驟流程即告完成。

串接工作流程是一項強大的功能，可用於設計複雜且使用者友善的互動。您可以建立複雜的入門流程、多方協議或任何需要順序性、已驗證步驟的流程。

接下來，了解另一項用於更複雜應用程式結構的進階功能。請參閱 委派連線 指南。