Appearance
Examples
Ready-to-use code examples for common widget patterns using the SDK. Each example shows a complete, self-contained call to connectors.execute that you can copy and adapt.
Prerequisites
These examples run inside a widget hosted in Customer Community, where window.WidgetServiceSDK is globally available. See Widget SDK for constructor options.
GET request with query parameters
Fetch weather data by passing query parameters to the connector:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK();
const weather = await sdk.connectors.execute({
permalink: "weather-api",
method: "GET",
queryParams: {
q: "Warsaw",
units: "metric"
}
});
console.log(weather);
})();1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
POST request with JSON body
Create a resource by sending a JSON payload:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK();
const result = await sdk.connectors.execute({
permalink: "crm-contacts",
method: "POST",
payload: {
firstName: "Jane",
lastName: "Doe",
email: "jane@example.com"
}
});
console.log(result);
})();1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
PUT request to update a resource
Update an existing resource by its identifier:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK();
const updated = await sdk.connectors.execute({
permalink: "crm-contacts",
method: "PUT",
queryParams: { id: "contact-42" },
payload: {
firstName: "Jane",
lastName: "Smith"
}
});
console.log(updated);
})();1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
DELETE request
Remove a resource using DELETE:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK();
await sdk.connectors.execute({
permalink: "task-manager",
method: "DELETE",
queryParams: { taskId: "task-99" }
});
})();1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Custom headers per request
Pass additional headers for a single request without affecting the global SDK configuration:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK();
const data = await sdk.connectors.execute({
permalink: "internal-api",
method: "GET",
headers: {
"X-Request-Id": crypto.randomUUID(),
"Accept-Language": "en-US"
}
});
})();1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Global headers via constructor
Set headers that apply to every request made through the SDK instance:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK({
headers: {
"X-App-Version": "2.1.0",
"X-Client": "custom-widget"
}
});
const data = await sdk.connectors.execute({
permalink: "analytics-api",
method: "GET"
});
})();1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
Custom timeout
Override the default 30-second timeout for long-running requests:
javascript
(async () => {
const sdk = new window.WidgetServiceSDK({
timeout: 60000
});
const report = await sdk.connectors.execute({
permalink: "report-generator",
method: "POST",
payload: { range: "last-90-days" }
});
})();1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Handling errors with a styled fallback
Wrap execute calls in try/catch and render a small, styled fallback using design tokens so the widget degrades gracefully instead of showing an empty container. This example lives inside init(sdk) — the only example on this page that does — so the connector-calling instance is named widgetServiceSdk rather than sdk, avoiding a collision with the sdk parameter already in scope (see Common mistakes for what goes wrong if you don't):
javascript
export async function init(sdk) {
await sdk.whenReady()
const container = sdk.getContainer()
container.innerHTML = `<div class="status">Loading…</div>`
const status = sdk.$('.status')
try {
const widgetServiceSdk = new window.WidgetServiceSDK()
const data = await widgetServiceSdk.connectors.execute({
permalink: "weather-api",
method: "GET",
queryParams: { q: "Warsaw" }
})
status.textContent = `${data.city}: ${data.temperature}°C`
} catch (error) {
status.textContent = "Couldn't load weather data right now."
status.style.color = "var(--color-content-subtle, #4F5663)"
console.error("Connector request failed:", error)
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
A plain-text fallback styled with the community's own design tokens reads as an intentional state, not a broken widget. See Design Tokens Reference for the full design-token catalog.
Next Steps
- Widget SDK Methods and Constructors — Full SDK method signatures and error handling
- Testing & Debugging — Verify your Connector setup works
- Configuration — Set up the connector your widget calls
- Widgets repository template — Working examples calling connectors