Documentación para desarrolladores

Integra el asistente en tu producto en minutos

El asistente comprende la interfaz de tu aplicación, guía a las personas paso a paso y ejecuta acciones directamente en pantalla. Esta guía cubre la instalación del SDK, la instrumentación del DOM con selectores inmutables, el CLI de la plataforma y la sincronización del System Prompt por API.

Paso 01

Instalación

Instala el cliente oficial. El paquete expone OnboardingAssistant.init() como punto de entrada único; entre sus opciones reales están publishableKey, apiUrl, websocketUrl, showVirtualCursor, autoTrackSpaRoutes, debug y los callbacks onStepAdvanced y onSessionTerminated.

Terminal

npm install @onboarding-assistant/sdk

Inicialización React / Next.jsCambia el ejemplo con el selector de framework de la barra lateral.

Inicialización del asistente

import { useEffect } from 'react';
import { OnboardingAssistant } from '@onboarding-assistant/sdk';

export function AssistantLoader() {
  useEffect(() => {
    const assistant = OnboardingAssistant.init({
      publishableKey: 'pk_live_9f8a7b6c',
      showVirtualCursor: true,
    });

    void assistant.start();
    return () => assistant.stop('React desmontó el componente');
  }, []);

  return null;
}

Al llamar a start(), el SDK completa el handshake seguro (POST /api/v1/sdk/handshake) validando tu clave publicable y el origen declarado antes de abrir el canal de voz.

Paso 02

Selectores inmutables data-oa-id

El asistente localiza cada elemento con una cascada de criterios: [data-oa-id] → [aria-label] → css-path. Declara el primer criterio directamente en tu interfaz para que el asistente no dependa de clases volátiles ni de la posición del elemento en el documento.

Criterio	Cómo se escribe	Cuándo se usa
`[data-oa-id]`	`data-oa-id="btn-crear-factura"`	Primer criterio y recomendado: identificador inmutable declarado por ti.
`[aria-label]`	`aria-label="Crear factura"`	Respaldo: reutiliza la etiqueta de accesibilidad ya presente en tu interfaz.
`css-path`	`main > form > button:nth-child(2)`	Último recurso: ruta estructural calculada por el asistente sobre el DOM.

Trata los data-oa-id como contrato público de tu interfaz: no los renombres entre despliegues sin avisar al asistente.
Mantén un identificador único por vista y acción (btn-crear-factura, input-numero-factura, modal-confirmacion).
Nunca dependas de clases generadas por tu pipeline de estilos (css-1x2y3z) ni de posiciones dinámicas :nth-child.

Paso 03

CLI de la plataforma

Autentica la CLI con el flujo de código de dispositivo: la terminal muestra un código XXXX-XXXX y lo confirmas desde el navegador en /auth/cli-device. Al completar la vinculación, la CLI queda autorizada para sincronizar mapas funcionales y lanzar sesiones de entrenamiento interactivo.

1. Autenticación de dispositivo

npx @onboarding-assistant/cli login

2. Sesión de entrenamiento interactivo

npx @onboarding-assistant/cli train

Paso 04

Sincroniza tu System Prompt por API

Actualiza el prompt y los pasos de onboarding de tu proyecto con PUT /api/v1/projects/:projectId/prompt autenticado con Authorization: Bearer. Cada publicación sella el mapa funcional con canonicalización determinista y SHA-256: las versiones son inmutables y toda sesión de voz apunta exactamente a la revisión que publicaste.

SHA-256 3f9a8c…c21bSello de la revisión publicada del mapa funcional.

Terminal — Sincronización del System Prompt

curl --request PUT \
  --url https://api.plataforma.com/api/v1/projects/prj_9f2c1a84/prompt \
  --header 'Authorization: Bearer $OA_SESSION_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "systemPrompt": "Guía al usuario para emitir su primera factura y confirma antes de enviarla.",
    "strictStepEnforcement": true,
    "askConfirmationBeforeSubmit": true
  }'

El historial conserva cada versión sellada: puedes comparar hashes para auditar cuándo cambió el comportamiento del asistente.

Uso responsable

Consentimiento de voz

El canal de voz se activa únicamente cuando la persona usuaria final otorga su consentimiento. Antes de publicar tu integración revisa la Política de Uso Aceptable de Voz IA y el Consentimiento de voz del usuario final. Al crear tu organización aceptas el aviso marco; tu sistema debe certificar después el consentimiento individual con POST /api/v1/public/end-user-consents usando tu clave secreta de backend. El registro es idempotente por usuario final y versión documental; enviar consentGranted: false deja constancia de la revocación.

Terminal — Certificación de consentimiento de voz

curl --request POST \
  --url https://api.plataforma.com/api/v1/public/end-user-consents \
  --header 'Authorization: Bearer sk_live_tu_clave_secreta' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalEndUserId": "usr_8f2c1a84",
    "consentGranted": true,
    "grantedAt": "2026-10-19T14:52:00Z",
    "evidence": { "source": "checkout-web", "consentTextVersion": "v1.0.0" }
  }'

La evidencia guarda la versión del aviso, su sello SHA-256, la IP hasheada y los metadatos que envíes. Nunca compartas tu clave secreta en el navegador.