Registro de eventos

Los eventos son la materia prima de todo en Joryio: los segmentos, activadores de recorridos, filtros de campaña y la analítica se basan en los eventos que envían tus apps. Esta guía cubre las convenciones y mecánicas compartidas por todos los SDK: web, iOS, Android y React Native. Para la instalación y configuración específica de cada plataforma, consulta las páginas de cada SDK.

Cómo funciona el registro

Cada SDK sigue el mismo flujo:

1. Llamas a track(eventName, properties) en tu app.
2. El SDK pone el evento en cola localmente (con persistencia sin conexión) y lo envía en lotes: por defecto cada cinco segundos o cada 50 eventos, lo que ocurra primero.
3. El lote se entrega a POST /v1/track/batch, autenticado con la clave de SDK de la app (formato jry_sdk_<plataforma>_<aleatorio>, una por app; consulta Resumen de apps).
4. El servidor resuelve el usuario (anónimo o identificado), almacena los eventos y los distribuye a segmentos, activadores de recorridos y analítica.

Un lote puede contener como máximo 500 eventos. El SDK establece las marcas de tiempo al realizar la llamada; el servidor acepta milisegundos de época o cadenas ISO-8601 y usa la hora del servidor si falta la marca de tiempo o no es válida (para que un reloj incorrecto del dispositivo nunca provoque el rechazo de un evento).

Convenciones de nomenclatura de eventos

El nombre de un evento es una cadena de hasta 255 caracteres. Más allá de eso, Joryio no impone un formato, pero la coherencia importa porque los nombres de eventos permiten encontrarlos después en los creadores de segmentos, activadores de recorridos y el Explorador de eventos.

Recomendaciones:

• Usa Title Case con espacios. Los eventos integrados de Joryio siguen la taxonomía de comercio electrónico estándar del sector (objeto + acción en pasado, Title Case): Product Viewed, Product Added, Checkout Started y Order Completed de las integraciones de tienda. Los eventos personalizados en Title Case (Trial Started, Signup Completed) mantienen uniforme el catálogo. Snake case también funciona, pero elige una convención y respétala; mezclarlas crea eventos que parecen duplicados.
• Nombra la acción, no la interfaz. Order Completed sobrevive a un rediseño; Green Button Clicked, no.
• Usa objeto + verbo en pasado. Subscription Upgraded, Video Played, Search Performed.
• Mantén la variabilidad en propiedades, no en nombres. Un evento Product Viewed con una propiedad category es mejor que cincuenta eventos Viewed <Category>: los segmentos y activadores coinciden primero con el nombre y luego filtran propiedades.
• Evita eventos demasiado genéricos. Clicked sin propiedades no te dice nada sobre lo que puedes actuar.

Los nombres de eventos distinguen mayúsculas y minúsculas: order_placed y Order_Placed son dos eventos distintos.

Propiedades y tipos de datos

Las propiedades son un objeto JSON asociado a cada evento. Se acepta cualquier valor JSON:

Tipo	Ejemplo	Notas
Cadena	"currency": "USD"	También para fechas, como cadenas ISO-8601
Número	"total": 149.99	Enteros y decimales
Booleano	"first_order": true
Matriz	"item_ids": ["SKU-1", "SKU-2"]
Objeto	"shipping": { "method": "express" }	Se permiten objetos anidados

Límites por evento en el servidor:

Límite	Valor
Longitud del nombre de evento	255 caracteres
Tamaño total de propiedades (JSON serializado)	50 KB
Claves de propiedad de nivel superior	200
Profundidad de anidamiento	5 niveles
Eventos por solicitud de lote	500

Los eventos que superan estos límites se rechazan. Los nombres de propiedades siguen el mismo consejo que los nombres de eventos: elige una convención (product_id, no a veces productId) y mantén los tipos estables; un order_id que es cadena en un evento y número en otro vuelve poco fiable el filtrado.

Las propiedades con prefijo $ (como $platform, $session_id, $app_id) se añaden automáticamente: algunas mediante los SDK ($device_id, datos de dispositivo en Session Start) y otras mediante la canalización de ingesta de Joryio al recibir el evento ($app_id, $session_id, $is_identified). Trata este prefijo como reservado y no lo uses para tus propias propiedades.

Reglas de nombres para atributos de usuario

Las claves de atributos (el objeto que pasas a setAttributes / setAttribute) tienen dos restricciones adicionales, y una clave que incumpla cualquiera de ellas se descarta; el resto de la llamada se guarda con normalidad:

No permitido	Por qué
Un . en cualquier parte de la clave	El punto se interpreta como separador de RUTA, no como carácter. "profile.email" se guardaría anidado como profile: { email }, así que un segmento sobre profile.email no coincidiría con nada.
Un $ inicial	Reservado, igual que en las propiedades de evento anteriores.
Una clave vacía	No hay nada que guardar.

Las claves se descartan en lugar de renombrarse a propósito: renombrarlas informaría de un éxito mientras deja tus datos donde nunca los consultas.

identify frente a track

Las dos llamadas principales cumplen funciones distintas:

• identify(userId) indica quién es el usuario. Vincula el dispositivo o sesión actual con tu ID de usuario estable y fusiona cualquier historial anónimo con ese perfil. Los atributos establecidos con setAttributes describen al usuario (email, plan y nombre) y viven en el perfil.
• track(eventName, properties) indica qué ocurrió. Las propiedades describen el evento, no al usuario, y son inmutables una vez registradas.

Reglas prácticas:

• Llama a identify en cuanto conozcas al usuario: al iniciar sesión y al iniciar la app si se restaura una sesión. Usa el mismo ID de usuario en todas las plataformas para que la actividad web y móvil llegue a un solo perfil (consulta Seguimiento multiplataforma).
• Antes de identify, los eventos se registran con un ID anónimo. Cuando identificas más tarde, el servidor fusiona el historial anónimo con el perfil identificado, para que no se pierdan eventos previos al registro (primera visita y atribución).
• Usa alias(userId) al registrarse para vincular explícitamente al usuario anónimo con la cuenta nueva y después identify(userId).
• Coloca los datos de cada ocurrencia en propiedades de evento (total, coupon) y los datos duraderos de la persona en atributos (plan, lifetime_value).
• Llama a reset() al cerrar sesión para que el siguiente usuario del dispositivo no herede el perfil.

El mismo evento en todos los SDK

La llamada track tiene intencionadamente la misma estructura en todos los SDK. Aquí está el mismo evento Order Completed en las cuatro plataformas.

Web (JS)

import JoryioSDK from '@joryio/web-sdk';

const joryio = new JoryioSDK({ sdkKey: 'jry_sdk_web_...' });

joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

iOS (Swift)

Joryio.shared.track("Order Completed", properties: [
    "order_id": "ORD-2024-001",
    "total": 149.99,
    "currency": "USD",
    "item_count": 3,
    "coupon": "SAVE10"
])

Android (Kotlin)

Joryio.track("Order Completed", mapOf(
    "order_id" to "ORD-2024-001",
    "total" to 149.99,
    "currency" to "USD",
    "item_count" to 3,
    "coupon" to "SAVE10"
))

React Native

import Joryio from '@joryio/react-native-sdk';

Joryio.track('Order Completed', {
  order_id: 'ORD-2024-001',
  total: 149.99,
  currency: 'USD',
  item_count: 3,
  coupon: 'SAVE10',
});

Como el nombre y las propiedades son idénticos, una condición de segmento o activador de recorrido coincide con el evento sin importar de qué plataforma proceda.

Para actividad estándar de comercio electrónico (vistas de producto, carritos, checkout y pedidos), prioriza los rastreadores de comercio electrónico integrados en los SDK: emiten los nombres de evento estandarizados que esperan las funciones de comercio electrónico de Joryio. Consulta la guía de seguimiento de comercio electrónico para todos los SDK.

Qué ocurre en el servidor

Cuando se acepta un lote, cada evento:

• Se almacena en el almacén de analítica, asociado al perfil de usuario resuelto (identificado o anónimo).
• Se evalúa frente a activadores de recorridos. Un recorrido cuyo activador de entrada coincide con el nombre de evento (y filtros de propiedad) inscribe al usuario de inmediato; así comienzan los recorridos de «carrito abandonado» o «bienvenida».
• Alimenta segmentos. Las condiciones de segmento basadas en eventos («realizó Order Completed en los últimos 30 días») se actualizan desde el flujo de eventos y las campañas dirigidas a esos segmentos recogen el cambio.
• Aparece en analítica: Explorador de eventos, embudos y analítica por app.
• Puede actualizar el perfil. Algunos eventos tienen efectos secundarios gestionados por el servidor; por ejemplo, los eventos Session Start actualizan el registro de dispositivo y establecen atributos como country (derivado de la IP de la solicitud).

Dos comportamientos del servidor que conviene conocer:

• Marcado de bots. Las solicitudes de agentes de usuario de bots conocidos se marcan (los eventos se etiquetan y la analítica los excluye); las llamadas que modifican perfiles como identify y setAttributes se omiten para bots. Por ello, el tráfico de navegadores sin interfaz de tu automatización de pruebas puede no crear perfiles.
• Validación flexible. Los campos extra desconocidos de la carga se eliminan en vez de rechazarse, para que una diferencia de versión del SDK no descarte tus eventos.

Verificación y depuración

Comprobar que llegó un evento

1. Activa el evento en tu app.
2. En el panel de Joryio, abre Analítica → Explorador de eventos. Filtra por nombre de evento y deberías verlo en segundos después de que el SDK envíe su lote (intervalo predeterminado: cinco segundos).
3. Para una vista por app, abre Configuración → Apps y haz clic en Ver analítica en la app. Muestra el total de eventos, la marca de tiempo del último evento y los nombres de eventos principales, con lo que confirmas rápidamente si está llegando algo desde esa clave de SDK.

Si los eventos no aparecen

• Fuerza un envío. Los eventos se agrupan en lotes; llama a flush() (disponible en todos los SDK) para enviar inmediatamente en lugar de esperar el temporizador.
• Activa el registro de depuración. Todos los SDK tienen una opción enableDebug que registra cada evento en cola y cada solicitud de red con su respuesta.
• Comprueba la clave de SDK. Debe coincidir con la plataforma de la app: jry_sdk_web_... para SDK web, jry_sdk_ios_... para iOS y jry_sdk_android_... para Android. Una clave regenerada invalida la anterior de inmediato.
• Comprueba que la app está activa en Configuración → Apps: se rechazan los eventos enviados con la clave de una app desactivada.
• Observa la respuesta de red. Una respuesta de lote incluye success y, ante un fallo parcial, failedIndices, que indica qué eventos del lote no se almacenaron. Las propiedades demasiado grandes (más de 50 KB, más de 200 claves o más de cinco niveles de anidamiento) son la causa habitual de eventos rechazados.
• Solo web: los endpoints de seguimiento del SDK permiten cualquier origen (Access-Control-Allow-Origin: *), por lo que los errores CORS suelen indicar un apiEndpoint incorrecto o una extensión de navegador bloqueadora; consulta la consola. Confirma también que el sitio se ejecuta mediante HTTPS para que funcione la persistencia de cola basada en localStorage.
• ¿Pruebas desde automatización? Recuerda el marcado de bots anterior: verifica con un navegador o dispositivo real.

Contenido relacionado

• Web SDK · iOS SDK · Android SDK · React Native SDK
• Eventos personalizados
• Seguimiento multiplataforma