Skip to content

Commit fb75abd

Browse files
claveryclavery
committed
Add extension telemetry; restructure configuration & features docs
Telemetry: - Wire SDK Telemetry into the VS Code extension (project=b2c-vs-extension) using the same App Insights connection string as the MCP server. - Lifecycle events (EXTENSION_ACTIVATED / DEACTIVATED / ACTIVATION_FAILED) plus per-command COMMAND_INVOKED with outcome and duration via registerSafeCommand. Exceptions reported through sendException. - Honors vscode.env.isTelemetryEnabled (telemetry.telemetryLevel) plus SFCC_DISABLE_TELEMETRY / SF_DISABLE_TELEMETRY. Persists anonymous cliId in globalStorageUri. Docs: - Lead Configuration with "Connecting to a B2C Instance" — a per-feature credential requirements table modeled on the CLI's per-command auth sections (sandbox.md, scapi-schemas.md). Adds an example dw.json with inline comments tagging each block to features. - Demote b2c-dx.* settings to a "Settings reference" section near the bottom with a clear "you usually don't need to change these" callout. - Add Telemetry section documenting what's collected, what's not, and three independent opt-out paths. - Add per-feature "Requires" callouts on every feature in features.md plus a top-of-page jump nav.
1 parent 0d13e34 commit fb75abd

9 files changed

Lines changed: 342 additions & 65 deletions

File tree

‎.changeset/vscode-telemetry.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'b2c-vs-extension': minor
3+
---
4+
5+
Add anonymous usage telemetry (extension lifecycle, command invocations, exceptions) to help prioritize fixes during the Developer Preview. Honors VS Code's `telemetry.telemetryLevel` setting and the `SFCC_DISABLE_TELEMETRY` / `SF_DISABLE_TELEMETRY` environment variables. No credentials, hostnames, or business data are collected. See the [Telemetry section in Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/vscode-extension/configuration#telemetry) for opt-out instructions and the full data inventory.

‎docs/vscode-extension/configuration.md‎

Lines changed: 116 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,147 @@
11
---
2-
description: Configure the B2C DX VS Code Extension — feature toggles, log level, sandbox polling, and project root pinning.
2+
description: Connect the B2C DX VS Code Extension to a B2C Commerce instance — credentials, OAuth, telemetry, and the b2c-dx.* settings reference.
33
---
44

55
# Configuration
66

7-
The extension reads B2C Commerce credentials from the same sources as the [B2C CLI](../guide/configuration) (`dw.json`, `SFCC_*` environment variables, `~/.dw.json`, etc.). This page covers the **VS Code-specific** settings under the `b2c-dx.*` namespace, configurable via **Settings** (Cmd+,) → search for `b2c-dx`, or directly in `settings.json`.
7+
The extension reuses the [B2C CLI](../guide/configuration)'s configuration system, so anything that works with `b2c` works here — `dw.json`, `SFCC_*` environment variables, and active-instance selection.
88

9-
<!-- TODO(screenshot): replace ./images/settings.svg with ./images/settings.png — Settings UI filtered to b2c-dx -->
10-
![B2C DX settings](./images/settings.svg)
9+
This page covers:
10+
11+
- [Connecting to a B2C Instance](#connecting-to-a-b2c-instance) — credentials per feature.
12+
- [Switching the Active Instance](#switching-the-active-instance) — single-workspace, multi-instance.
13+
- [Project Root Pinning](#project-root-pinning) — multi-root workspaces.
14+
- [Telemetry](#telemetry) — what we collect and how to opt out.
15+
- [Settings Reference](#settings-reference) — the `b2c-dx.*` toggles and verbosity controls.
16+
17+
## Connecting to a B2C Instance
1118

12-
## Feature Toggles
19+
The extension needs different credentials depending on which feature you use. **A `dw.json` at your workspace root is the recommended setup** — populate the fields each feature needs, and the extension picks them up automatically.
1320

14-
Each feature is enabled by default. Disable any toggle to hide its tree views, commands, and context-menu entries — useful when you want a leaner UI or are debugging activation issues.
21+
### Per-feature requirements
1522

16-
| Setting | Default | What it controls |
17-
| ------- | ------- | ---------------- |
18-
| `b2c-dx.features.sandboxExplorer` | `true` | Sandbox Realm Explorer view + lifecycle commands |
19-
| `b2c-dx.features.webdavBrowser` | `true` | WebDAV Browser tree + `b2c-webdav://` filesystem provider |
20-
| `b2c-dx.features.contentLibraries` | `true` | Content Libraries tree + export/import commands |
21-
| `b2c-dx.features.codeSync` | `true` | Cartridges view, watch/deploy, code-version commands |
22-
| `b2c-dx.features.logTailing` | `true` | Log tail commands + B2C DX log output channel |
23-
| `b2c-dx.features.scaffold` | `true` | "New from Scaffold..." command and file/newFile menu entry |
24-
| `b2c-dx.features.apiBrowser` | `true` | SCAPI API Browser view + Swagger UI panel |
25-
| `b2c-dx.features.cap` | `true` | Commerce App Package install command + file decorations |
23+
Each feature documents its own requirements in [Features](./features). The summary:
24+
25+
| Feature | Required `dw.json` fields |
26+
| ------- | ------------------------- |
27+
| **Sandbox Realm Explorer** | OAuth (browser login by default; `client-id` + `client-secret` for headless). `Sandbox API User` role with a tenant filter. |
28+
| **WebDAV Browser** | `hostname`, `username`, `password` (WebDAV access key). OAuth (`client-id` + `client-secret`) also accepted. |
29+
| **Content Libraries** | Same as WebDAV. Optionally `contentLibrary` (or `libraries`) to seed the tree. |
30+
| **Cartridge Code Sync** | WebDAV for transfer **and** OCAPI (`client-id` + `client-secret`) for code-version operations. |
31+
| **SCAPI API Browser** | `client-id`, `client-secret`, `short-code`, `tenant-id`. |
32+
| **B2C Script Debugger** | WebDAV (for source-mapping). |
33+
| **Log Tailing** | WebDAV (logs are read from `Logs/`). |
34+
| **CAP install** | WebDAV; some apps additionally require OAuth client credentials. |
35+
| **Scaffold**, **Page Designer Assistant** | None — local-only. |
36+
37+
### Example `dw.json`
2638

2739
```jsonc
28-
// .vscode/settings.json
2940
{
30-
"b2c-dx.features.sandboxExplorer": true,
31-
"b2c-dx.features.codeSync": true,
32-
"b2c-dx.features.apiBrowser": false
41+
// WebDAV (Code Sync, WebDAV Browser, Content Libraries, Log Tailing, Debugger)
42+
"hostname": "abcd-001.dx.commercecloud.salesforce.com",
43+
"username": "your-bm-username",
44+
"password": "your-webdav-access-key",
45+
"code-version": "version1",
46+
47+
// OCAPI / OAuth (Sandbox API, Code Versions, CAP)
48+
"client-id": "...",
49+
"client-secret": "...",
50+
51+
// SCAPI (API Browser)
52+
"short-code": "...",
53+
"tenant-id": "...",
54+
55+
// Optional — content tree seed
56+
"contentLibrary": "your-library-id"
3357
}
3458
```
3559

36-
The B2C Script Debugger registers regardless of these toggles — it activates only when a `b2c-script` launch configuration is used.
60+
You can also set any of these via `SFCC_*` environment variables (`SFCC_SERVER`, `SFCC_USERNAME`, `SFCC_CLIENT_ID`, `SFCC_TENANT_ID`, etc.). See the [CLI Configuration guide](../guide/configuration) for the complete list and precedence rules, and the [Authentication Setup guide](../guide/authentication) for OAuth scope requirements and Account Manager API client setup.
3761

38-
## Log Level
62+
<!-- TODO(screenshot): replace ./images/settings.svg with ./images/settings.png — Settings UI filtered to b2c-dx -->
3963

40-
| Setting | Default | Description |
41-
| ------- | ------- | ----------- |
42-
| `b2c-dx.logLevel` | `info` | Verbosity for the **B2C DX** output channel |
64+
## Switching the Active Instance
4365

44-
Allowed values: `trace`, `debug`, `info`, `warn`, `error`, `silent`. The setting is applied immediately on change — no reload needed.
66+
When `dw.json` defines multiple named instances (the recommended pattern for working across dev / staging / sandbox), click the cloud icon in the status bar to run **B2C DX: Switch Active Instance** — a quick-pick over the configured instances. Selecting a new one updates the underlying `dw.json` active-instance pointer and refreshes every view.
4567

46-
<!-- TODO(screenshot): replace ./images/output-channel.svg with ./images/output-channel.png — B2C DX output channel showing log stream -->
47-
![B2C DX output channel](./images/output-channel.svg)
68+
The same pointer is shared with the CLI: switching here is equivalent to running `b2c setup instance set-active <name>`.
4869

49-
The output channel surfaces SDK logs (request/response summaries, safety-mode evaluations, polling events) plus extension lifecycle events. Drop to `debug` or `trace` when filing a bug report.
70+
## Project Root Pinning
5071

51-
## Sandbox Polling Interval
72+
In a multi-root workspace, the extension auto-detects the project root by walking up from the active editor (or the first workspace folder) looking for `dw.json` / `package.json` markers. Two commands let you override the auto-detected root:
5273

53-
| Setting | Default | Range | Description |
54-
| ------- | ------- | ----- | ----------- |
55-
| `b2c-dx.sandbox.pollingInterval` | `10` | 2–300 | Seconds between polls while a sandbox is in a transitional state |
74+
- **B2C DX: Use as B2C Commerce Root** — only available on a workspace-root folder when more than one folder is open in the workspace. Right-click that folder in the Explorer and select the command to pin it. While a pin is active, the status bar shows a `$(pinned)` indicator.
75+
- **B2C DX: Reset B2C Commerce Root to Auto-Detect** — clears the pin and returns to auto-detection. Run from the Command Palette (this command has no Explorer context-menu entry).
5676

57-
The Sandbox Realm Explorer auto-polls a realm only when at least one sandbox is in a transitional state (`creating`, `starting`, `stopping`, `deleting`, `cloning`). Once the realm is fully settled, polling stops.
77+
The pin is workspace-scoped (stored in workspace state).
5878

59-
```jsonc
60-
{
61-
"b2c-dx.sandbox.pollingInterval": 5
62-
}
63-
```
79+
## Telemetry
6480

65-
## Project Root Pinning
81+
The extension reports anonymous usage data to help us prioritize fixes during the Developer Preview.
6682

67-
In a multi-root workspace, the extension auto-detects the project root by walking up from the active editor (or the first workspace folder) looking for `dw.json` / `package.json` markers. Two commands let you override the auto-detected root:
83+
**What we collect:** extension lifecycle events (`EXTENSION_ACTIVATED`, `EXTENSION_DEACTIVATED`, `ACTIVATION_FAILED`), command invocations (command ID, success/failure, duration), and exceptions. Each event includes anonymous session and machine identifiers, plus environment info (VS Code version, platform, architecture, Node.js version).
6884

69-
- **B2C DX: Use as B2C Commerce Root** — only available on a workspace-root folder when more than one folder is open in the workspace. Right-click that folder in the Explorer and select the command to pin it. While a pin is active, the status bar shows a `$(pinned)` indicator.
70-
- **B2C DX: Reset B2C Commerce Root to Auto-Detect** — clears the pin and returns to auto-detection. Run from the Command Palette (this command has no Explorer context-menu entry).
85+
**What we don't collect:** credentials, hostnames, sandbox IDs, file contents, command arguments, or any business data. String attributes have `$HOME` redacted to `~` before transmission.
86+
87+
**Opt out** in any of the following ways — telemetry is disabled if **any** of them is true:
88+
89+
| Source | Setting |
90+
| ------ | ------- |
91+
| VS Code `settings.json` | `"telemetry.telemetryLevel": "off"` (also disables when set to `crash` or `error`) |
92+
| Environment variable | `SFCC_DISABLE_TELEMETRY=true` |
93+
| Environment variable | `SF_DISABLE_TELEMETRY=true` (Salesforce CLI standard) |
94+
95+
The extension respects VS Code's built-in `telemetry.telemetryLevel` first, so opting out of all VS Code telemetry automatically disables ours.
96+
97+
## Settings Reference
98+
99+
These VS Code settings live under the `b2c-dx.*` namespace. **You usually don't need to change any of them** — they exist for niche cases like disabling a feature you don't use, or quieting the log channel for a bug report. To browse: **Settings** (Cmd+,) → search for `b2c-dx`.
100+
101+
### Feature toggles
102+
103+
Each feature is enabled by default. Set to `false` to skip its activation entirely (no tree views, no commands, no context-menu entries). Useful for trimming the UI, isolating activation issues, or running in a project where a feature isn't applicable.
104+
105+
| Setting | Default |
106+
| ------- | ------- |
107+
| `b2c-dx.features.sandboxExplorer` | `true` |
108+
| `b2c-dx.features.webdavBrowser` | `true` |
109+
| `b2c-dx.features.contentLibraries` | `true` |
110+
| `b2c-dx.features.codeSync` | `true` |
111+
| `b2c-dx.features.logTailing` | `true` |
112+
| `b2c-dx.features.scaffold` | `true` |
113+
| `b2c-dx.features.apiBrowser` | `true` |
114+
| `b2c-dx.features.cap` | `true` |
115+
116+
The B2C Script Debugger registers regardless of these toggles — it activates only when a `b2c-script` launch configuration is used.
117+
118+
### Verbosity & polling
71119

72-
The pin is workspace-scoped (stored in workspace state). Pin a specific folder when you have multiple cartridge projects in a single workspace and want to keep CLI commands targeting one of them.
120+
| Setting | Default | Description |
121+
| ------- | ------- | ----------- |
122+
| `b2c-dx.logLevel` | `info` | Verbosity for the **B2C DX** output channel. Allowed: `trace`, `debug`, `info`, `warn`, `error`, `silent`. Applied immediately on change. Drop to `debug` or `trace` when filing a bug. |
123+
| `b2c-dx.sandbox.pollingInterval` | `10` | Seconds between polls while a sandbox is in a transitional state (`creating`, `starting`, `stopping`, `deleting`, `cloning`). Range: 2–300. Polling stops automatically once the realm settles. |
124+
125+
### Complete defaults (copy-paste)
126+
127+
```jsonc
128+
// .vscode/settings.json
129+
{
130+
"b2c-dx.features.sandboxExplorer": true,
131+
"b2c-dx.features.webdavBrowser": true,
132+
"b2c-dx.features.contentLibraries": true,
133+
"b2c-dx.features.codeSync": true,
134+
"b2c-dx.features.logTailing": true,
135+
"b2c-dx.features.scaffold": true,
136+
"b2c-dx.features.apiBrowser": true,
137+
"b2c-dx.features.cap": true,
138+
"b2c-dx.logLevel": "info",
139+
"b2c-dx.sandbox.pollingInterval": 10
140+
}
141+
```
73142

74143
## Next Steps
75144

76-
- [Features](./features) — full feature tour.
77-
- [Authentication Setup](../guide/authentication) — credential formats, OAuth scopes, MRT API keys.
145+
- [Features](./features) — full feature tour with per-feature credential callouts.
146+
- [Authentication Setup](../guide/authentication) — Account Manager API clients, WebDAV access keys, OAuth scopes.
147+
- [CLI Configuration](../guide/configuration) — full `dw.json` reference and precedence rules.

0 commit comments

Comments
 (0)