0

Viết Outlook Add-in bằng React: những thứ tài liệu không nói

Outlook Add-in nhìn từ ngoài giống một web app React bình thường: một trang HTML, một bundle JS, chạy trong khung bên phải của Outlook. Mình đã nghĩ thế khi bắt đầu làm add-in đặt phòng họp. Rồi lần lượt gặp những chuyện mà web app thường không bao giờ gặp:

  • Mở add-in từ một cuộc họp trong hộp thư dùng chung, add-in crash vì một store chưa có dữ liệu mặc định.
  • Mở lại đúng cuộc họp đó, add-in báo phòng họp đã đặt cho chính cuộc họp này là "trùng lịch" và tự gỡ phòng ra.
  • Phát hành bản mới, khách hàng cập nhật qua trang quản trị Microsoft 365, và không có gì thay đổi.

Bài này gom những bài học đó, kèm checklist mình dùng trước mỗi lần phát hành add-in. (Chuyện lịch họp lặp lại lệch ngày khi qua giờ mùa hè, cũng từ add-in này, mình đã kể riêng ở bài 1.)

Add-in không có một "trang chủ" duy nhất

Web app có một luồng vào: người dùng mở URL. Add-in thì được mở từ nhiều ngữ cảnh khác nhau, mỗi ngữ cảnh cho dữ liệu khác nhau:

Ngữ cảnh Khác ở chỗ
Đang soạn cuộc họp mới Cuộc họp chưa có trên server, chưa có id
Đang xem cuộc họp đã gửi Có id, có người tham dự, không sửa được mọi trường
Cuộc họp trong hộp thư dùng chung Quyền khác, định danh cuộc họp không đáng tin như hộp thư cá nhân
Outlook trên web, Outlook desktop, Outlook mới Phiên bản API Office.js khác nhau, cách lưu trữ khác nhau

Hệ quả: đừng giả định store đã có dữ liệu từ một bước trước. Mỗi store phải có đủ giá trị mặc định, và mọi phép tra cứu phải trả về một giá trị rõ ràng khi không có gì:

// Trước: một số trường không có mặc định, tra cứu trả về undefined khi thiếu khoá
const useResourceStore = create<ResourceState>()((set, get) => ({
  selectedResources: [],
  resourceFor: (key) => get().sessionResources?.[key],
}));

// Sau: đủ mặc định cho mọi trường, tra cứu trả về null có chủ đích
const useResourceStore = create<ResourceState>()((set, get) => ({
  selectedResources: [],
  originalSelectedResources: null,
  eventResources: null,
  itemProcessing: null,
  guids: {},
  resourceFor: (key) => get().sessionResources?.[key] ?? null,
}));

Bug crash ở hộp thư dùng chung đến từ đúng những trường thiếu mặc định này: trong luồng thường, một bước trước đã gán giá trị cho chúng, còn mở thẳng từ hộp thư dùng chung thì bước đó không chạy.

Và luôn chờ Office.onReady trước khi render bất cứ thứ gì đụng tới Office.js. Gọi API của Outlook trước lúc đó là lỗi lúc có lúc không, tuỳ tốc độ máy.

Đừng tin một định danh duy nhất của cuộc họp

Add-in kiểm tra phòng còn trống hay không bằng cách hỏi server các lượt đặt trùng giờ, sau khi loại ra lượt đặt của chính cuộc họp đang mở (không thì phòng luôn "trùng với chính mình"). Việc loại ra dựa vào định danh của cuộc họp mà Outlook đưa cho.

Với hộp thư cá nhân, định danh đó ổn định. Mở lại một cuộc họp trong hộp thư dùng chung thì định danh có thể rỗng hoặc khác đi. Không khớp được, lượt đặt của chính cuộc họp không bị loại, và phòng bị coi là đã có người đặt. Add-in hiện "trùng lịch" và gỡ phòng ra khỏi cuộc họp.

Bản sửa thêm một cách khớp dự phòng: nếu không khớp được bằng định danh, khớp bằng người tổ chức và khoảng thời gian trùng nhau. Bài học cho phía front end: định danh do môi trường bên ngoài đưa cho (Outlook, Google Calendar, một app mobile) phải được coi là có thể thiếu hoặc sai, và luồng nghiệp vụ không được sụp chỉ vì nó thiếu.

Đăng nhập một lần với MSAL

Add-in cần gọi API của hệ thống với danh tính người dùng Outlook. Cách hiện đại là Nested App Authentication: add-in xin token thông qua chính Outlook, người dùng không phải đăng nhập lại trong một popup riêng. Với MSAL:

import { createNestablePublicClientApplication } from '@azure/msal-browser';

const pca = await createNestablePublicClientApplication({
  auth: { clientId: CLIENT_ID, authority: 'https://login.microsoftonline.com/common', supportsNestedAppAuth: true },
});

async function getToken(scopes: string[]) {
  const account = pca.getActiveAccount() ?? pca.getAllAccounts()[0];
  try {
    return (await pca.acquireTokenSilent({ scopes, account })).accessToken;
  } catch {
    return (await pca.acquireTokenPopup({ scopes })).accessToken; // lần đầu cần đồng ý quyền
  }
}

Hai điều cần nhớ: cấu hình này dành riêng cho add-in chạy trong Outlook. Cùng codebase nếu có một trang web độc lập (ví dụ trang quản trị), trang đó dùng cấu hình MSAL thường, không bật nested auth. Và luôn có đường dự phòng bằng popup, vì không phải phiên bản Outlook nào cũng hỗ trợ cách mới.

Mở lại khung add-in phải nhanh: lưu cache truy vấn

Người dùng đóng mở khung add-in liên tục khi chuyển giữa các cuộc họp. Mỗi lần mở là một lần khởi động lại app từ đầu. Nếu mỗi lần đều gọi lại danh sách địa điểm, loại phòng, cấu hình, người dùng nhìn spinner vài giây mỗi lần.

TanStack Query có sẵn cách lưu cache xuống bộ nhớ trình duyệt:

import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';

const persister = createSyncStoragePersister({ storage: window.localStorage, key: 'addin-query-cache' });

<PersistQueryClientProvider
  client={queryClient}
  persistOptions={{ persister, maxAge: 24 * 60 * 60 * 1000, buster: APP_VERSION }}
>
  <App />
</PersistQueryClientProvider>

Ba lưu ý:

  • buster bằng phiên bản app. Lên bản mới mà cấu trúc dữ liệu đổi, cache cũ bị bỏ thay vì làm app crash.
  • Chỉ lưu dữ liệu tham chiếu ít đổi (địa điểm, loại phòng). Không lưu tình trạng phòng trống: thứ đó phải luôn mới.
  • Không lưu token hay thông tin nhạy cảm vào localStorage. MSAL tự quản lý token của nó.

Phát hành: version manifest phải cao hơn bản đang dùng

Add-in được cài qua một file manifest. Office và trang quản trị Microsoft 365 chỉ coi là bản cập nhật khi version trong manifest cao hơn version khách đang có. Bản build mới với manifest cùng version sẽ không được đẩy xuống người dùng.

Chuyện của mình: version của add-in được đóng dấu theo version sản phẩm, và một nhánh phát hành mới có version manifest thấp hơn bản mà khách hàng nâng cấp từ đó đã có. Cách sửa là một script tăng version manifest có kiểm tra "phải cao hơn bản đã phát hành gần nhất", chạy trong bước build, thay vì sửa tay.

Checklist trước mỗi lần phát hành add-in

[ ] Thử mở từ: soạn mới, xem cuộc họp đã gửi, hộp thư dùng chung
[ ] Thử trên: Outlook web, Outlook desktop, Outlook mới
[ ] Mọi store có đủ mặc định; tra cứu thiếu khoá trả null, không crash
[ ] Không có luồng nào chết chỉ vì định danh cuộc họp rỗng hoặc lạ
[ ] Đăng nhập: thử lần đầu (cần đồng ý quyền) và lần sau (im lặng)
[ ] Cache: buster theo version, không lưu dữ liệu nhạy cảm hay dữ liệu phải luôn mới
[ ] Version manifest cao hơn bản khách đang dùng
[ ] Chuỗi họp lặp qua mốc giờ mùa hè hiển thị đúng ngày, đúng giờ

Thử ngay: nếu bạn đang làm add-in, mở nó từ một cuộc họp trong hộp thư dùng chung. Nếu bạn làm web app thường, câu hỏi tương tự vẫn đúng: app có bao nhiêu "cửa vào" (link chia sẻ, thông báo, deep link từ app khác), và mỗi cửa có giả định store đã có dữ liệu không?

Bài sau trong series: app nằm dưới base path của một hệ thống khác. Chọn route theo đường dẫn hay theo dấu #, và chuyện theme người dùng chọn phải được nhớ khi mở trang mới. Bạn từng làm add-in cho Office hay Google Workspace chưa? Comment kể cái bẫy bạn gặp nhé.

P.S. Hai bug ở phần đầu bài đều là kiểu "luồng thường chạy đúng, một ngữ cảnh lạ thì vỡ". Mình tìm ra nguyên nhân bằng skill debug trong PrimeKit, bộ skill mình tự làm: tái hiện lỗi trong đúng ngữ cảnh, so với ngữ cảnh chạy đúng, kiểm từng giả thuyết trước khi sửa. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:debug kèm mô tả lỗi và ngữ cảnh. Tái hiện được trên đúng phiên bản Outlook của khách vẫn là phần khó nhất, và phần đó cần bạn.


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí