This version (v0.7) has not been published to npm yet.
Skip to content

Support (widget) ​

Player support is a third-party widget (Zendesk, Intercom...) configured by the operator. The SDK has no support namespace: what exists is config.getSupport(), which returns what the app needs to mount the widget. It does not require login.

Read the configuration ​

ts
const support = await enginex.config.getSupport()
// { enabled: true, provider: 'zendesk', supportType: 'zendesk', widgetUrl: 'https://...', apiKey: '...' }

Without type, the gateway returns Zendesk. For another provider, pass { type: 'intercom' }.

FieldWhat for
enabledfalse when the operator has not configured it: mount nothing
providerprovider code
supportTyperequested type, e.g. zendesk, intercom
widgetUrlURL of the widget script
apiKeykey the gateway says is needed to start the widget
appIdapp identifier (depends on the configured provider)
widgetIdwidget identifier (depends on the configured provider)
domaindomain (depends on the configured provider)

All but enabled are optional: they only arrive when the operator filled them in. The gateway does not say which field each provider uses; check with the operator and the provider's documentation.

Mount the widget ​

The pattern is the same for any provider: load the provider's script with what the gateway returned and initialize it. The examples below are generic; check the widget API in your provider's documentation, because the SDK does not know or validate it.

ts
// Loads a script once and resolves when it is ready.
function loadScript(src: string, id: string): Promise<void> {
  return new Promise((resolve, reject) => {
    if (document.getElementById(id)) return resolve()
    const el = document.createElement('script')
    el.id = id
    el.src = src
    el.async = true
    el.onload = () => resolve()
    el.onerror = () => reject(new Error('Failed to load the support widget'))
    document.head.append(el)
  })
}

Zendesk (example) ​

ts
const support = await enginex.config.getSupport({ type: 'zendesk' })
if (support.enabled && support.widgetUrl) {
  await loadScript(support.widgetUrl, 'support-widget')
  // After loading, initialize the widget as the Zendesk documentation says, with what the operator
  // configured (for example, `support.apiKey`).
}

Another provider (illustrative example) ​

The example below only illustrates the pattern with type: 'intercom'. Which fields your provider requires (here, appId) is an assumption of the example, not a guarantee from the gateway.

ts
const support = await enginex.config.getSupport({ type: 'intercom' })
if (support.enabled && support.widgetUrl && support.appId) {
  // The script URL comes from the gateway. Any provider URL pattern belongs to the provider: the SDK
  // and the gateway do not supply it.
  await loadScript(support.widgetUrl, 'support-widget')
  // Initialize as the provider's documentation says (here, assuming `appId` is what is needed).
}

Good practices:

  • Mount the widget once (for example, in the root layout) and only if enabled is true.
  • Handle the script failing (ad blocker, network): the app must keep working without support, perhaps with a fallback contact link.
  • The gateway only says that apiKey is needed to start the widget; do not assume it is public or secret beyond that, and use it only as the provider documents.
  • Do not send the provider player data the operator has not authorized (email, CPF); identify the player with whatever the operator's privacy policy allows.

Support tickets: not in this version ​

The gateway has ticket routes (/support/tickets), but the SDK does not expose them, because today they do not work end to end:

  • the calls to create, list and reply to tickets are not implemented in the admin service (enginex-admin) that is in the workspace;
  • the gateway sends source: "web" when creating a ticket, a value the service does not accept;
  • there is no route to read the team's replies or to close a ticket.

Exposing this now would lead the app to a ticket screen that fails. When the gateway and the service are complete, tickets will arrive in a future version. Until then, the channel is the widget.

What the gateway does not offer yet ​

  • Support tickets. Create, list, read replies and close; see above.
  • Typed configuration per provider. getSupport returns generic optional fields; the SDK does not know which one is required for each provider.
  • Player identification in the widget. There is no identity token (for example, a user signature) generated by the gateway for the provider.