遙測擴充功能作者指南

Visual Studio Code 會收集使用數據並傳送給 Microsoft，以協助改善我們的產品與服務。請閱讀我們的 隱私權聲明 與 遙測文件 以了解更多資訊。

本主題提供擴充功能作者相關指南，協助其擴充功能符合 VS Code 的遙測要求與最佳實踐。

注意：如果您不希望傳送使用數據給 Microsoft，可以將 telemetry.telemetryLevel 使用者 設定 設為 off。

遙測模組

VS Code 團隊維護著 @vscode/extension-telemetry npm 模組，該模組提供了一種在 VS Code 內收集遙測數據的一致且安全的方式。此模組將遙測數據回報至 Azure Monitor 與 Application Insights，並確保與舊版 VS Code 的向後相容性。

請遵循此指南來設定 Azure Monitor 並取得您的 Application Insights 檢測金鑰 (Instrumentation Key)。

不使用遙測模組的情況

若擴充功能作者不希望使用 Application Insights，可以採用自訂解決方案來傳送遙測數據。在此情況下，作者仍須透過使用 isTelemetryEnabled 與 onDidChangeTelemetryEnabled API 來尊重使用者的選擇。透過此舉，使用者將擁有一個集中式的位置來控制其遙測設定。

自訂遙測設定

擴充功能可能會希望讓使用者獨立於 VS Code 遙測之外，控制該擴充功能專屬的遙測。若有此需求，我們建議您導入特定的擴充功能設定。建議將自訂遙測設定標記為 telemetry 與 usesOnlineServices，以便使用者能更輕易地在設定 UI 中搜尋到它們。新增自訂遙測設定並不能免除尊重使用者決策的責任，且必須始終遵守 isTelemetryEnabled 與 onDidChangeTelemetryEnabled 旗標。如果 isTelemetryEnabled 回報為 false，即使您的設定已啟用，也不得傳送遙測數據。

telemetry.json

我們了解遙測對許多使用者來說是敏感話題，因此我們致力於保持透明。VS Code 核心產品與大多數第一方擴充功能都在根目錄中附帶了一個 telemetry.json 檔案。這允許使用者使用帶有 --telemetry 旗標的 VS Code CLI 來取得 VS Code 所產生的所有遙測資料轉儲。擴充功能作者可以在根目錄中包含 telemetry.json 檔案，該檔案也會出現在 CLI 轉儲中。

建議與不建議事項

✔️ 建議做法

• 如果您適用 Application Insights，請使用 @vscode/extension-telemetry npm 模組。
• 否則，請務必遵守 isTelemetryEnabled 與 onDidChangeTelemetryEnabled API。
• 如果您有自訂遙測設定，請將其標記為 telemetry 與 usesOnlineServices。
• 盡可能收集最少量的遙測數據。
• 對於您所收集的內容，請盡可能對使用者保持透明。

❌ 不建議做法

• 請勿引入未徵求使用者同意的自訂遙測收集解決方案。
• 請勿收集個人識別資訊 (PII)。
• 請勿收集超過必要範圍的遙測數據。
• 請勿僅使用 telemetry.telemetryLevel 設定，因為與 isTelemetryEnabled 相比，它有時可能不準確。