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.

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 for setup and SDK Reference for every method and option.

Connectors

GET request with query parameters

Fetch weather data by passing query parameters to the connector:

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:

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:

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:

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):

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)

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

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

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

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 — full method signatures, options, and error handling
• User Context — complete reference for Context.User(), all User methods, and the User object schema
• Testing & Debugging — verify your Connector setup works
• Configuration — set up the connector your widget calls
• Widgets repository template — working examples calling connectors