Eventos personalizados

Los eventos representan las acciones que realizan los usuarios en tu aplicación. Registra eventos personalizados para crear segmentos, activar campañas y analizar el comportamiento de los usuarios.

¿Qué son los eventos?

Los eventos son registros con marca de tiempo de las acciones de los usuarios:

{
  "userId": "user_123",
  "eventName": "Order Completed",
  "timestamp": "2024-01-20T14:30:00Z",
  "properties": {
    "orderId": "order_456",
    "total": 99.99,
    "currency": "USD",
    "items": 3,
    "paymentMethod": "credit_card"
  }
}

Registrar eventos

Mediante SDK (lado cliente)

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

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

// Evento sencillo
joryio.track('Button Clicked');

// Evento con propiedades
joryio.track('Order Completed', {
  orderId: 'order_456',
  total: 99.99,
  currency: 'USD',
  items: 3
});

// Vista de página
joryio.track('Page Viewed', {
  page: '/pricing',
  category: 'Marketing',
  title: 'Pricing Page'
});

Mediante API (lado servidor)

fetch('https://api-eu1.joryio.com/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer jry_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_123',
    eventName: 'Order Completed',
    properties: {
      orderId: 'order_456',
      total: 99.99,
      currency: 'USD'
    }
  })
});

Seguimiento por lotes

El SDK agrupa automáticamente los eventos en lotes para mejorar el rendimiento. Los eventos se ponen en cola y se envían por grupos:

// El SDK agrupa automáticamente estos eventos
joryio.track('Product Viewed', { productId: '123' });
joryio.track('Added To Cart', { productId: '123', price: 49.99 });
joryio.track('Cart Viewed', { itemCount: 1 });

// Los eventos se envían juntos después de 10 segundos o al llegar a 20 eventos (configurable)

// Para enviar inmediatamente:
joryio.flush();

// API: POST /track con una matriz como cuerpo sin envoltorio (máximo 500)
POST /track
[
  {
    "userId": "user_123",
    "eventName": "Product Viewed",
    "properties": { "productId": "123" }
  },
  {
    "userId": "user_123",
    "eventName": "Added To Cart",
    "properties": { "productId": "123", "price": 49.99 }
  }
]

Nombres de eventos

Prácticas recomendadas

Usa nombres claros y coherentes:

Correcto (objeto + acción):

joryio.track('Product Viewed');
joryio.track('Cart Abandoned');
joryio.track('Order Completed');
joryio.track('Trial Started');

Incorrecto:

joryio.track('view_product');      // Inconsistent case
joryio.track('clicked');           // Too generic
joryio.track('user_action_123');   // Not descriptive

Convención de nombres

Recomendamos: objeto + verbo en pasado

Product Viewed
Order Completed
Account Created
Feature Enabled
Video Watched
Form Submitted

Propiedades de los eventos

Las propiedades aportan contexto sobre el evento:

Eventos de e-commerce

// Producto visto
joryio.track('Product Viewed', {
  productId: 'prod_123',
  productName: 'Premium Plan',
  category: 'Subscription',
  price: 99.99,
  currency: 'USD',
  inStock: true
});

// Pedido completado
joryio.track('Order Completed', {
  orderId: 'order_456',
  total: 249.99,
  currency: 'USD',
  itemCount: 3,
  discount: 25.00,
  shippingCost: 10.00,
  paymentMethod: 'credit_card',
  products: [
    { id: 'prod_1', name: 'Item 1', price: 99.99 },
    { id: 'prod_2', name: 'Item 2', price: 149.99 }
  ]
});

// Carrito abandonado
joryio.track('Cart Abandoned', {
  cartValue: 149.99,
  itemCount: 2,
  cartAge: '2h 30m'
});

Eventos de SaaS

// Prueba iniciada
joryio.track('Trial Started', {
  plan: 'premium',
  trialDays: 14,
  source: 'pricing_page'
});

// Feature Used
joryio.track('Feature Used', {
  featureName: 'export',
  exportFormat: 'csv',
  recordCount: 1500,
  duration: 3.5 // segundos
});

// Suscripción mejorada
joryio.track('Subscription Upgraded', {
  fromPlan: 'starter',
  toPlan: 'professional',
  billingCycle: 'monthly',
  mrr: 199,
  effectiveDate: '2024-02-01'
});

Eventos de contenido y multimedia

// Vídeo visto
joryio.track('Video Watched', {
  videoId: 'vid_123',
  videoTitle: 'Product Demo',
  duration: 120, // segundos
  percentWatched: 85,
  quality: '1080p',
  platform: 'web'
});

// Artículo leído
joryio.track('Article Read', {
  articleId: 'article_456',
  title: '10 Tips for Better Marketing',
  category: 'Marketing',
  author: 'John Doe',
  readTime: 5, // minutos
  scrollDepth: 90
});

Ejemplos de eventos habituales

Ciclo de vida del usuario

// Flujo de registro
joryio.track('Signup Started');
joryio.track('Signup Completed', {
  method: 'email',
  source: 'homepage_cta'
});
joryio.track('Email Verified');
joryio.track('Onboarding Completed', {
  stepsCompleted: 5,
  timeSpent: '8m 30s'
});

// Interacción
joryio.track('Session Started');
joryio.track('Feature Discovered', {
  featureName: 'advanced_filters'
});
joryio.track('Help Article Viewed', {
  articleId: 'help_123',
  query: 'how to export data'
});
joryio.track('Session Ended', {
  duration: '15m 20s',
  pagesViewed: 8
});

Embudo de e-commerce

// Exploración
joryio.track('Product Searched', {
  query: 'wireless headphones',
  results: 45
});
joryio.track('Product Viewed', {
  productId: 'prod_123',
  price: 199.99
});
joryio.track('Product Compared', {
  productIds: ['prod_123', 'prod_456']
});

// Carrito
joryio.track('Added To Cart', {
  productId: 'prod_123',
  quantity: 1,
  price: 199.99
});
joryio.track('Cart Viewed');
joryio.track('Coupon Applied', {
  code: 'SAVE20',
  discount: 39.99
});

// Pago
joryio.track('Checkout Started', {
  value: 159.99
});
joryio.track('Payment Info Entered');
joryio.track('Order Completed', {
  orderId: 'order_789',
  revenue: 159.99
});

Métricas de SaaS

// Activación
joryio.track('Trial Started');
joryio.track('Integration Connected', {
  integration: 'salesforce'
});
joryio.track('First Report Created');
joryio.track('Team Member Invited');

// Interacción
joryio.track('Daily Active', {
  loginCount: 45
});
joryio.track('API Call Made', {
  endpoint: '/users',
  method: 'GET'
});

// Ingresos
joryio.track('Subscription Created', {
  plan: 'professional',
  mrr: 199
});
joryio.track('Subscription Renewed', {
  plan: 'professional'
});
joryio.track('Subscription Cancelled', {
  reason: 'too_expensive'
});

Tipos de datos de las propiedades

Tipos admitidos

joryio.track('Event Name', {
  // Cadena
  name: "John Doe",
  plan: "premium",

  // Número
  age: 30,
  price: 99.99,
  quantity: 5,

  // Booleano
  isActive: true,
  emailVerified: false,

  // Fecha (cadena ISO 8601)
  createdAt: "2024-01-20T10:30:00Z",
  expiresAt: "2024-02-20T23:59:59Z",

  // Matriz
  tags: ["vip", "early-access"],
  categories: ["electronics", "accessories"],

  // Objeto
  address: {
    city: "San Francisco",
    state: "CA",
    zip: "94102"
  },
  metadata: {
    source: "web",
    campaign: "summer_sale"
  }
});

Nombres de propiedades reservados

Las propiedades que empiezan por $ están reservadas:

$app_id: identificador de la app.
$app_name: nombre de la app.
$platform: plataforma (web, ios, android).
$session_id: identificador de sesión.
$anonymous_id: ID de usuario anónimo.
$is_identified: indica si el usuario se ha identificado.

No uses estos nombres para propiedades personalizadas.

Usar eventos para segmentar

Crea segmentos basados en el comportamiento de los eventos:

Evento realizado

Segment: Active users
Filter: Performed "Session Started" within last 7 days

Evento NO realizado

Segment: Users who haven't upgraded
Filter: Has NOT performed "Subscription Upgraded"

Recuento de eventos

Segment: Power users
Filter: Performed "Feature Used" >= 50 times within last 30 days

Propiedades de eventos

Segment: High-value customers
Filter: Performed "Order Completed"
  WHERE properties.total >= 500
  within last 90 days

Segmentos de comportamiento complejos

Segment: At-risk users
Filter Group 1 (AND):
  - Performed "Login" within last 90 days
  - Has NOT performed "Login" within last 14 days
  - Performed "Order Completed" at least 1 time

Uso: campaña de reactivación

Campañas activadas por eventos

Activa campañas basadas en eventos:

Ejemplo 1: abandono de carrito

Disparador: evento "Cart Abandoned"
Espera: 1 hora
Condición: NO ha realizado "Order Completed"
Acción: enviar email de recuperación con descuento

Ejemplo 2: onboarding

Disparador: evento "Signup Completed"
Flujo:
  → Email de bienvenida (inmediato)
  → Esperar 2 días
  → Guía de primeros pasos
  → Esperar 5 días
  → Comprobar: ¿ha realizado "First Report Created"?
     - Sí: email con consejos avanzados
     - No: email ofreciendo ayuda

Límites y rendimiento de eventos

Límites de velocidad

Plan	Eventos/segundo	Eventos diarios
Free	10/seg	100.000
Starter	50/seg	500.000
Pro	100/seg	2.000.000
Enterprise	Personalizado	Sin límite

Prácticas recomendadas para el rendimiento

El SDK agrupa automáticamente los eventos en lotes:

// El SDK los agrupa automáticamente en lotes
joryio.track(event1);
joryio.track(event2);
joryio.track(event3);
// Los tres se envían juntos al alcanzar batchFlushInterval (5 s de forma predeterminada) o batchSize (50 de forma predeterminada)

// Para eventos críticos que requieren envío inmediato:
joryio.track('Order Completed', {...});
joryio.flush(); // Envía inmediatamente

No registres actividad con demasiada frecuencia:

// Incorrecto: registrar cada desplazamiento
window.addEventListener('scroll', () => {
  joryio.track('Page Scrolled');
});

// Correcto: registrar hitos de profundidad de desplazamiento
joryio.track('Page Scrolled', {
  depth: 75 // %
});

Mantén las propiedades dentro de límites razonables:
- Máximo 50 propiedades por evento.
- Tamaño total máximo del evento: 10 KB.
- Evita cadenas extremadamente largas.

Depurar eventos

Activar el modo de depuración

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  enableDebug: true // Consulta todos los eventos en la consola
});

Verificar los eventos en el dashboard

Ve a Usuarios y busca al usuario.
Abre la pestaña Actividad.
Consulta todos los eventos registrados.

Problemas habituales

Los eventos no aparecen:

Comprueba que el SDK esté inicializado.
Verifica que el usuario se haya identificado (o que exista un ID anónimo).
Activa el modo de depuración.
Revisa la consola del navegador en busca de errores.

Las propiedades no aparecen:

Verifica que los nombres de propiedades sean correctos.
Comprueba los tipos de datos.
Evita los nombres de propiedades reservados (prefijo $).

¿Qué son los eventos?​

Registrar eventos​

Mediante SDK (lado cliente)​

Mediante API (lado servidor)​

Seguimiento por lotes​

Nombres de eventos​

Prácticas recomendadas​

Convención de nombres​

Propiedades de los eventos​

Eventos de e-commerce​

Eventos de SaaS​

Eventos de contenido y multimedia​

Ejemplos de eventos habituales​

Ciclo de vida del usuario​

Embudo de e-commerce​

Métricas de SaaS​

Tipos de datos de las propiedades​

Tipos admitidos​

Nombres de propiedades reservados​

Usar eventos para segmentar​

Evento realizado​

Evento NO realizado​

Recuento de eventos​

Propiedades de eventos​

Segmentos de comportamiento complejos​

Campañas activadas por eventos​

Ejemplo 1: abandono de carrito​

Ejemplo 2: onboarding​

Límites y rendimiento de eventos​

Límites de velocidad​

Prácticas recomendadas para el rendimiento​

Depurar eventos​

Activar el modo de depuración​

Verificar los eventos en el dashboard​

Problemas habituales​

Próximos pasos​