En vivo en tu app en una tarde
Un script, un token que firma tu backend y los roles que ya tienes. Nunca tenemos acceso a tu código, tu base de datos ni tus llaves de API.
Del script a la primera respuesta
Funciona con React, Vue, Angular y apps renderizadas en servidor.
// KirkyWidget.tsx · se monta una vez, p. ej. en App import { useEffect } from "react"; export function KirkyWidget() { useEffect(() => { const s = document.createElement("script"); s.src = "https://cdn.kirkyapp.com/v1/…"; s.setAttribute("data-kirky-tenant", "tn_4f7k2q"); s.async = true; document.body.appendChild(s); return () => s.remove(); }, []); return null; }
Lo que necesitas
- 01
Una app web que controles
Cualquier front end que genere HTML: React, Vue, Angular, Next.js o páginas renderizadas en servidor. El widget se monta en un Shadow DOM, así que tus estilos no cambian.
- 02
Un backend que pueda firmar un token
Un par de llaves ES256. La llave privada se queda en tu servidor; en el portal solo subes la llave pública.
- 03
Un espacio de trabajo en el portal
Ahí obtienes tu ID de tenant, subes documentos, registras endpoints y decides qué puede ver cada rol.
- 04
Un navegador moderno para tus usuarios
Chrome, Edge y Firefox actuales, y Safari 16.4 o posterior. Funciona con CSP estricta con nonce, strict-dynamic y Trusted Types.
Integra en Test, activa Live
Cada organización tiene un entorno Test gratuito. Tiene su propio ID de tenant, su propio límite de consultas y un modelo más económico, para que integres sin tocar Live.
| Claim | Test | Live |
|---|---|---|
| ID de tenant | tn_test_4f7k2q | tn_4f7k2q |
| Costo | Gratis, con su propio límite de consultas | Tu plan |
| Modelo | Más económico, para integrar | Calidad completa |
| Datos | Separados de Live | Separados de Test |
| Widget | Muestra la etiqueta “Test” | Sin etiqueta |
El token que firma tu backend
Tu backend le dice a Kirky quién es el usuario con un JWT firmado con ES256. Vive cinco minutos como máximo, y un rol nuevo empieza sin permisos hasta que se los das en el portal.
| Claim | Qué significa | Obligatorio |
|---|---|---|
| sub | El ID de tu usuario. Kirky nunca necesita su correo ni su nombre.Obligatorio: Sí | Sí |
| roles | Los roles del usuario en tu app. Deciden qué puede leer y hacer Kirky.Obligatorio: Sí | Sí |
| aud | Tu ID de tenant (Test o Live).Obligatorio: Sí | Sí |
| exp | Vencimiento, 5 minutos como máximo después de emitirlo. El SDK pide uno nuevo cuando lo necesita.Obligatorio: Sí | Sí |
| lang | es o en. Las respuestas lo siguen; sin él, Kirky sigue al navegador.Obligatorio: No | No |
| kid (encabezado) | Cuál de tus llaves públicas lo firmó, para que rotes llaves sin interrupciones.Obligatorio: Sí | Sí |
Registra los endpoints que Kirky puede leer
Para la capa de Datos, Kirky llama a tus propios endpoints de lectura desde el navegador del usuario, con la sesión de ese usuario. Tus credenciales nunca llegan a nuestros servidores.
- 1Importa tu archivo OpenAPIO agrega endpoints a mano. El portal te muestra cada endpoint que Kirky podrá llamar antes de guardar nada.
- 2Describe cada endpoint con palabras simplesKirky elige el endpoint por su descripción, así que “pedidos abiertos del vendedor con sesión” es mejor que “GET /orders”.
- 3Elige qué roles pueden usarloUn endpoint que ningún rol puede usar nunca se llama. Los endpoints de escritura van a la capa de Acciones y siempre piden confirmación.
- 4Pasa los encabezados de autenticación del usuarioLas cookies funcionan tal cual. Para tokens bearer, dale al SDK una función getAuthHeaders(); corre en el navegador, nunca de nuestro lado.
// app.ts · solo apps con tokens bearer Kirky.init({ token, getAuthHeaders: () => ({ Authorization: `Bearer ${session.accessToken}`, }), });
Notas por framework
React y Next.js
Monta el componente del widget una vez cerca de la raíz e inicializa cuando tu propio login termine. En Next.js, cárgalo desde un componente de cliente.
Vue
Carga el script en onMounted de tu componente raíz e inicializa cuando ya conozcas al usuario. Funciona igual con Nuxt en el cliente.
Angular
Agrega la etiqueta a src/index.html y luego inicializa desde un componente o servicio después de la autenticación. No hay módulo que importar.
Apps renderizadas en servidor
Agrega la etiqueta a tu layout y apunta data-kirky-token-url a una ruta de tu mismo dominio que devuelva el token. Sin script en línea, así que una CSP estricta sigue intacta.
Si algo no funciona
El widget no aparece
Revisa primero tu Content Security Policy: permite cdn.kirkyapp.com en script-src o pásale tu nonce a init(). Luego abre la consola del navegador con debug: true y lee lo que reporta diagnostics().
El token es rechazado
Las causas comunes son un aud que no coincide con el entorno (Test o Live), un exp mayor a 5 minutos, un kid que el portal no conoce o un reloj de servidor desfasado más de un minuto.
Las preguntas de datos fallan pero las de documentos funcionan
Probablemente tu endpoint rechaza el preflight del navegador. Permite los encabezados de rastreo que agrega tu herramienta de APM (traceparent, baggage, sentry-trace) y revisa que getAuthHeaders() devuelva un token vigente.
Un rol ve muy poco, o demasiado
Los roles vienen del token. Abre el rol en el portal: un rol nuevo empieza sin permisos, y cada capa y cada endpoint se otorgan por separado.