Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Soporte (widget) ​

El soporte al jugador es un widget de terceros (Zendesk, Intercom...) configurado por el operador. El SDK no tiene un namespace de soporte: lo que existe es config.getSupport(), que devuelve lo que la app necesita para montar el widget. No requiere inicio de sesión.

Leer la configuración ​

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

Sin type, el gateway devuelve Zendesk. Para otro proveedor, pasa { type: 'intercom' }.

CampoPara qué
enabledfalse cuando el operador no lo configuró: no montes nada
providercódigo del proveedor
supportTypetipo solicitado, p. ej., zendesk, intercom
widgetUrlURL del script del widget
apiKeyclave que el gateway indica como necesaria para iniciar el widget
appIdidentificador de la app (depende del proveedor configurado)
widgetIdidentificador del widget (depende del proveedor configurado)
domaindominio (depende del proveedor configurado)

Todos, salvo enabled, son opcionales: solo llegan cuando el operador los completó. El gateway no indica qué campo usa cada proveedor; confírmalo con el operador y con la documentación del proveedor.

Montar el widget ​

El patrón es el mismo para cualquier proveedor: cargar el script del proveedor con lo que el gateway devolvió e inicializarlo. Los ejemplos de abajo son genéricos; consulta la API del widget en la documentación de tu proveedor, porque el SDK no la conoce ni la valida.

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 (ejemplo) ​

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`).
}

Otro proveedor (ejemplo ilustrativo) ​

El ejemplo de abajo solo ilustra el patrón con type: 'intercom'. Qué campos exige tu proveedor (aquí, appId) es una suposición del ejemplo, no una garantía del 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).
}

Buenas prácticas:

  • Monta el widget una sola vez (por ejemplo, en el layout raíz) y solo si enabled es true.
  • Maneja el fallo del script (bloqueador de anuncios, red): la app debe seguir funcionando sin el soporte, quizá con un enlace de contacto alternativo.
  • El gateway solo indica que apiKey es necesaria para iniciar el widget; no asumas que es pública ni secreta más allá de eso, y úsala únicamente como lo documenta el proveedor.
  • No envíes al proveedor datos del jugador que el operador no haya autorizado (correo, CPF); identifica al jugador con lo que la política de privacidad del operador permita.

Tickets de soporte: fuera de esta versión ​

El gateway tiene rutas de tickets (/support/tickets), pero el SDK no las expone, porque hoy no funcionan de punta a punta:

  • las llamadas para crear, listar y responder tickets no están implementadas en el servicio administrativo (enginex-admin) que está en el workspace;
  • el gateway envía source: "web" al crear un ticket, un valor que el servicio no acepta;
  • no hay ruta para leer las respuestas del equipo ni para cerrar un ticket.

Exponer esto ahora llevaría a la app a una pantalla de tickets que falla. Cuando el gateway y el servicio estén completos, los tickets entrarán en una versión futura. Hasta entonces, el canal es el widget.

Lo que el gateway aún no ofrece ​

  • Tickets de soporte. Crear, listar, leer respuestas y cerrar; consulta arriba.
  • Configuración tipada por proveedor. getSupport devuelve campos genéricos opcionales; el SDK no sabe cuál es obligatorio en cada proveedor.
  • Identificación del jugador en el widget. No hay un token de identidad (por ejemplo, la firma del usuario) generado por el gateway para el proveedor.