Volver al portal

Entrega e instalación de M.A.T.I.A.S. Signals

Portal: https://d3l58up0dymby.cloudfront.net/

Supervisión desde tu cuenta

Para ver las métricas de varias implementaciones desde tu cuenta, crea un proyecto por cliente dentro de tu organización y abre Metrics en cada proyecto. Entrega a cada cliente su snippet y, para la integración de backend, su API key por un canal seguro. El acceso al tablero requiere pertenecer a la organización del proyecto; crear una cuenta no concede acceso a organizaciones ajenas.

Acceso e instalación

  1. Crea una cuenta en el portal y confirma el código enviado por Cognito. El portal también permite reenviar el código y recuperar la contraseña.
  2. Crea una organización y un proyecto. El proyecto obtiene un sandbox con orígenes http://localhost:3000 y http://localhost:5173.
  3. En Overview, selecciona el entorno y copia Installation Snippet. El snippet usa los identificadores públicos de ese entorno; nunca incluyas una server API key en el navegador.
  4. Conecta el consentimiento de tu sitio: ejecuta window.matiasSignals.setConsent({ analytics: true }) únicamente cuando la persona acepte analítica. Al retirarlo, ejecuta setConsent({ analytics: false }).
  5. Comprueba eventos en Live Debugger y Metrics, seleccionando Sandbox. Envía al menos 11 eventos consentidos antes de activar producción.
  6. Registra cada hostname real en Domains y publica el TXT solicitado. Verifica el dominio en el portal. www.ejemplo.com y ejemplo.com son hosts distintos.
  7. En Production, completa los controles, activa el proyecto y pulsa Obtener entorno y snippet de producción. Este entorno requiere HTTPS, consentimiento y dominios verificados.
  8. Instala el snippet del entorno de producción y crea su API key desde API Keys, después de seleccionar el entorno en Overview. Guarda el secreto en el backend; se muestra una sola vez.

No hay que configurar manualmente la URL de la API en el portal alojado. El registro y los datos se mantienen separados por organización, proyecto y tenant.

Vinculación con una solicitud

Desde el backend, crea un token en POST https://gc10o64rh3.execute-api.us-east-1.amazonaws.com/v1/link-tokens, autenticado con Authorization: Bearer SERVER_API_KEY y cuerpo:

{"application_id":"APP-UUID-ALEATORIO","application_created_at":"FECHA_ISO_8601_CON_ZONA"}

Usa un identificador opaco, nunca documento, correo, teléfono o contraseña. Entrega el link_token temporal al navegador y llama:

const accepted = await window.matiasSignals.linkToken(link_token);

El SDK 1.0.1 envía al servicio Linking los identificadores de sesión y visitante con consentimiento. El token tiene caducidad y protección contra reutilización. El resultado inicial se estabiliza mediante la cola de reconciliación después de cinco minutos. decision_influence=false: Signals no aprueba ni rechaza créditos.

Métricas y conexión con otro tablero

Entra al proyecto y abre Metrics. Incluye eventos, visitantes y sesiones únicos dentro de cada tenant, páginas vistas, formularios enviados, solicitudes identificadas en eventos, tendencia diaria, tipos de evento y dispositivos. Los visitantes de tenants distintos se cuentan por separado.

La API usa los mismos permisos del portal:

GET https://ocmqo40ok6.execute-api.us-east-1.amazonaws.com/v1/projects/PROJECT_ID/metrics?start_date=2026-09-01&end_date=2026-09-10&environment=production
Authorization: Bearer COGNITO_ACCESS_TOKEN

Filtros opcionales: tenant_id, environment (sandbox, staging, production). Omite environment para combinar entornos. Las fechas son inclusivas, en America/Bogota. Sin fechas se consulta el mes actual. Se puede descargar el mismo JSON desde el tablero.

Contrato principal: schema_version, complete, generated_at, events, visitors, sessions, page_views, form_starts, form_submissions, linked_applications, last_event_at, daily, event_types, devices, browsers, tenant_metrics. No expone los identificadores de visitantes ni propiedades de formularios. Las solicitudes vinculadas de esta métrica se basan en eventos application_linked; no son un conteo de snapshots de Linking.

Límites explícitos de esta versión: consulta de hasta 31 días y 10000 registros del índice. Si se exceden, devuelve 422 para reducir el intervalo. No devuelve resultados parciales presentados como totales. Un fallo de almacenamiento devuelve 503. Los índices tienen consistencia eventual: espera unos segundos después de la ingesta.

Las métricas reflejan eventos todavía retenidos en DynamoDB. La retención es configurable por tenant (30 días por defecto). El archivo raw S3 tiene una política separada de 365 días; no se consulta para las métricas interactivas. La purga explícita requiere el flujo autorizado de eliminación de datos.

Operación

APIs de producción:

Las alarmas operativas están disponibles en CloudWatch. El tablero de negocio está en la pestaña Metrics del portal. El dashboard adicional de CloudWatch está preparado en Terraform, desactivado hasta disponer de permisos PutDashboard/GetDashboard. Las alarmas cubren errores de los servicios, respuestas 5xx, atraso de la cola y ambas DLQ. La entrega por correo depende de confirmar la suscripción SNS recibida; una alarma visible en CloudWatch no prueba entrega de correo.

Verificación antes de cada entrega a un cliente

CORS del SDK

Las APIs públicas de Collector y Linking admiten CORS HTTPS y localhost de desarrollo en API Gateway, sin cookies ni credenciales del navegador. La autorización del POST sigue siendo estricta: Collector exige tenant activo, public key y origen exacto del registro; Linking valida firma, caducidad, origen firmado y nonce. No se usa esta política para el Control Plane autenticado: su lista de orígenes contiene únicamente el portal. API Gateway limita el tráfico a 100 solicitudes/s con ráfaga de 200, Collector limita el cuerpo a 256 KiB y Linking a 16 KiB. Estas son protecciones globales; los campos de cuota por tenant son informativos en esta versión.