最佳做法

請按照這些外掛程式設計指南,改善使用者的整體體驗。

一般最佳做法

建議您在開發所有外掛程式時,遵循下列最佳做法。

開始前確認外掛程式的擁有權

外掛程式是由 Apps Script 專案定義,這些專案必須由特定帳戶擁有,或放置在共用雲端硬碟中。在編寫外掛程式程式碼前,請先決定專案的擁有者帳戶,以及發布者帳戶。也請決定哪些帳戶將擔任協作者,並確保這些帳戶具有指令碼專案及其相關Cloud 平台專案的存取權。

擴充 Google Workspace 功能,而非複製

外掛程式旨在為其擴充的 Google Workspace 應用程式提供新功能,或自動執行複雜的工作。如果外掛程式只是複製應用程式中已有的功能,或是無法複製工作流程的重大改善,就可能無法通過外掛程式審查而無法發布。

縮小範圍

明確定義範圍時,請一律選擇最不寬鬆的範圍組合。舉例來說,如果外掛程式只需要讀取權,就不要使用 https://www.googleapis.com/auth/calendar 範圍要求使用者日曆的完整存取權。如需唯讀存取權,請使用 https://www.googleapis.com/auth/calendar.readonly 範圍。

避免過度依賴程式庫

使用 Apps Script 程式庫可能會導致外掛程式執行速度變慢,而如果所有 Apps Script 程式碼都包含在單一指令碼專案中,則不會發生這種情況。雖然 Apps Script 程式庫可在外掛程式中運作,但使用這些程式庫可能會導致效能降低。請勿在專案中加入不必要的程式庫,並考慮如何減少外掛程式對這些程式庫的依賴。

上述延遲時間僅適用於用於伺服器端程式庫的 Apps Script 專案。您可以自由使用 jQuery 等用戶端 JavaScript 程式庫,而不會遇到延遲問題。

Google Workspace 外掛程式的最佳做法

下列最佳做法僅適用於 Google Workspace 外掛程式和卡片服務的使用方式。

只使用幾張卡片

如果外掛程式使用過多資訊卡,導覽設定就會變得複雜且難以管理。

避免一時衝動而建立過多不必要的資訊卡。

使用小工具建立函式

編寫用於建立 Card 或其他複雜 UI 物件的程式碼時,請考慮將該程式碼放入其專屬函式。這個建立函式應只建構物件並傳回。這樣一來,您就能在需要重新整理 UI 時,快速重新產生該物件。請記得在卡片服務中使用建構工具類別後呼叫 build()

簡化資訊卡

如果某張資訊卡上的小工具太多,可能會佔據過多螢幕空間,導致資訊卡的實用性降低。雖然大型資訊卡片區段會轉譯為可摺疊的 UI 元素,但這會向使用者隱藏資訊。請盡量簡化外掛程式,並提供使用者所需的功能,不要提供過多功能。

使用錯誤資訊卡

建立錯誤狀態的資訊卡。如果外掛程式產生錯誤,應會顯示資訊卡,其中包含錯誤資訊和如何修正錯誤的說明 (如適用)。舉例來說,如果您的外掛程式因授權失敗而無法連線至非 Google 服務,請顯示說明這項資訊的資訊卡,並要求使用者驗證所使用的帳戶資訊。

編寫測試和測試訊息

您應徹底測試所有建立的擴充功能。建構測試函式,使用測試資料建立資訊卡和小工具,然後驗證物件是否如預期建立。

使用動作回呼函式時,通常必須建構回應物件。您可以使用下列陳述式,確認回應是否正確建構:

    Logger.log(response.printJson());

使用「Run」選單,直接從 Apps Script 編輯器執行您建立的測試函式。當您有可用的外掛程式時,請務必安裝未發布的版本,以便進行測試。

請使用擴充外掛程式所適用的每個主機應用程式的測試資料。舉例來說,如果外掛程式會擴充 Gmail,您可能需要幾封測試電子郵件和其訊息 ID,以便確保在提供不同訊息內容時,外掛程式能正常運作。您可以使用 Gmail API Users.messages.list 方法列出郵件,或使用 Apps Script 的 Gmail 服務取得特定郵件的郵件 ID。

行事曆會議最佳做法

如果外掛程式將第三方日曆會議選項整合至 Google 日曆,請遵循下列其他最佳做法:

保持 onCreateFunction 燈亮

當使用者嘗試建立該類型的會議解決方案時,您在資訊清單中定義的每個 onCreateFunction 都會同步呼叫。請確認這些函式只執行建立會議所需的最低必要工作。在這些函式中執行過多操作,可能會導致使用者體驗變慢。

使用適當的 ConferenceData 欄位儲存會議資料

建構 ConferenceData 物件時,您可以填入會議的詳細資料 (存取碼、電話號碼、PIN 碼、URI 等)。請務必使用對應的 EntryPoint 欄位來提供這項資訊。請勿將這些詳細資料放在 ConferenceData 備註欄位中。

請勿在 Google 日曆活動中附加會議詳細資料

您的外掛程式不需要在 Google 日曆活動說明中新增第三方會議資訊。必要時,Google 日曆會自動執行這項操作。