---
url: https://developer-portal.gainsight.com/docs/sdk/examples.md
description: >-
  Runnable code examples for the SDK — connector requests, headers and timeouts,
  error fallbacks, and Web SDK user context recipes
---

# SDK Examples

Ready-to-use snippets for common SDK tasks. Each example is self-contained — copy it into your widget or sitewide script and adapt it.

::: info Prerequisites
These examples run in a widget, or in a sitewide script registered with `"type": "module"`, on a community page. Examples that touch `document` are written for sitewide scripts; inside a widget, query your own markup with `sdk.$()` in `init(sdk)` instead. Each imports `connectors` or `web` from `@gainsight-hub/sdk` — see [SDK](/sdk/) for setup and [SDK Reference](/sdk/reference) for every method and option.
:::

## Connectors

### GET request with query parameters

Fetch weather data by passing query parameters to the connector:

```javascript
import { connectors } from "@gainsight-hub/sdk";

const weather = await connectors.execute({
  permalink: "weather-api",
  method: "GET",
  queryParams: {
    q: "Warsaw",
    units: "metric"
  }
});

console.log(weather);
```

### POST request with JSON body

Create a resource by sending a JSON payload:

```javascript
import { connectors } from "@gainsight-hub/sdk";

const result = await connectors.execute({
  permalink: "crm-contacts",
  method: "POST",
  payload: {
    firstName: "Jane",
    lastName: "Doe",
    email: "jane@example.com"
  }
});

console.log(result);
```

`PUT`, `PATCH`, and `DELETE` use the same call: change `method`, and identify the resource with `queryParams` or `pathParams`.

### Custom headers per request

Pass additional headers for a single request without changing the client configuration:

```javascript
import { connectors } from "@gainsight-hub/sdk";

const data = await connectors.execute({
  permalink: "internal-api",
  method: "GET",
  headers: {
    "X-Request-Id": crypto.randomUUID(),
    "Accept-Language": "en-US"
  }
});
```

### Client-wide headers and timeout

`configure` changes the shared client, so its settings apply to every widget on the page:

```javascript
import { connectors } from "@gainsight-hub/sdk";

connectors.configure({
  headers: { "X-Client": "custom-widget" },
  timeout: 60000
});
```

### Handling errors with a fallback

Wrap `execute` calls in `try`/`catch` and render a fallback so the widget degrades gracefully instead of showing an empty container. This example lives inside `init(sdk)`:

```javascript
import { connectors } from "@gainsight-hub/sdk"

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 data = await 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."
    console.error("Connector request failed:", error)
  }
}
```

## Web SDK

### Get the current user (viewer context)

```javascript
import { web } from "@gainsight-hub/sdk";

const me = await web.Context.User()
const greeting = me.userId === null ? "Welcome, guest" : `Welcome back, ${me.username}`
```

### Show the current user's badges

```javascript
import { web } from "@gainsight-hub/sdk";

const me = await web.Context.User()
if (me.userId !== null && me.badges.length > 0) {
  const list = document.createElement('ul')
  me.badges.forEach((badge) => {
    const li = document.createElement('li')
    li.textContent = badge.title
    list.appendChild(li)
  })
  document.getElementById('badges')?.appendChild(list)
}
```

### Personalize based on profile fields

```javascript
import { web } from "@gainsight-hub/sdk";

const me = await web.Context.User()
if (me.userId !== null) {
  // Find a profile field by ID (field IDs are specific to your community)
  const seniority = me.profileFields.find((f) => f.id === 3)
  if (seniority?.value === 'senior') {
    document.getElementById('advanced-content')?.removeAttribute('hidden')
  }
}
```

### List moderators

```javascript
import { web } from "@gainsight-hub/sdk";

const { totalItems, items } = await web.User.list({
  role: [7], // role IDs are specific to your community
  sort: 'lastVisit',
  order: 'desc',
  size: 10
})
console.log(`${items.length} of ${totalItems} moderators`)
items.forEach((u) => console.log(u.username, u.rank?.name))
```

## Next Steps

* [SDK Reference](/sdk/reference) — full method signatures, options, and error handling
* [User Context](/sdk/user-context) — complete reference for `Context.User()`, all User methods, and the User object schema
* [Testing & Debugging](/connectors/testing-and-debugging) — verify your Connector setup works
* [Configuration](/connectors/configuration) — set up the connector your widget calls
* [Widgets repository template](https://github.com/gainsight-hub/widgets-repository-template/tree/main/widgets) — working examples calling connectors