Endpoint de Exposición

El endpoint /api/experiments/expose registra cuándo un visitante ha sido expuesto a un experimento. Debe llamarse cada vez que un experimento se muestra o aplica a un usuario. Esta información es crucial para calcular correctamente las métricas de conversión y realizar análisis estadísticos precisos.

Especificación de la API

• URL: /api/experiments/expose
• Método: POST
• Formato de datos: JSON
• Autenticación: API Key en encabezado X-SA-API-KEY

Parámetros del Request

Ejemplo de payload

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "experiment_id": "exp_12345",
  "variation_id": "var_b",
  "url": "https://ejemplo.com/productos",
  "timestamp": 1646123456789,
  "metadata": {
    "page_title": "Catálogo de Productos",
    "device_type": "desktop",
    "viewport_size": "1200x800"
  }
}

Respuesta

{
  "success": true,
  "exposure_id": "exp_12345_vis_abcd1234",
  "timestamp": 1646123456790
}

Códigos de estado HTTP

• 200 OK: Exposición registrada correctamente
• 400 Bad Request: Parámetros inválidos o faltantes
• 401 Unauthorized: API key inválida o faltante
• 403 Forbidden: El sitio no tiene permisos para usar experimentos
• 404 Not Found: Experimento o variante no encontrados
• 429 Too Many Requests: Se ha excedido el límite de peticiones
• 500 Internal Server Error: Error en el servidor

Gestión de errores

En caso de error, la respuesta incluirá detalles sobre el problema:

{
  "success": false,
  "error": {
    "code": "invalid_parameters",
    "message": "El parámetro experiment_id es obligatorio",
    "details": {
      "missing_fields": ["experiment_id"]
    }
  }
}

Deduplicación de exposiciones

Para evitar contabilizar múltiples veces una misma exposición, el sistema implementa las siguientes reglas:

1. Misma sesión: Si un visitante ve la misma variante del mismo experimento varias veces en una sesión, solo se cuenta como una exposición.

2. Diferentes sesiones: Si un visitante ve la misma variante en diferentes sesiones, se cuenta como exposiciones diferentes.

3. Cambio de variante: Si un visitante ve diferentes variantes del mismo experimento (por ejemplo, si la configuración cambia), cada variante cuenta como una exposición separada.

Tiempos de exposición

El sistema también puede registrar cuánto tiempo el usuario estuvo expuesto a una variante:

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "experiment_id": "exp_12345",
  "variation_id": "var_b",
  "url": "https://ejemplo.com/productos",
  "timestamp": 1646123456789,
  "exposure_time": 45.2,
  "exposure_type": "viewed"
}

Tipos de exposición

• viewed: El elemento modificado está dentro del viewport y visible para el usuario
• rendered: El experimento se aplicó pero no hay garantía de que el usuario lo haya visto
• interacted: El usuario interactuó directamente con el elemento modificado

Buenas prácticas

1. Registrar inmediatamente: Llama a este endpoint tan pronto como se aplique un experimento en la página.

2. Verificar visibilidad: Cuando sea posible, verifica que el elemento modificado sea visible para el usuario antes de registrar la exposición.

3. Incluir metadatos relevantes: Proporciona información contextual en el campo metadata para análisis más detallados.

4. Gestionar errores: Implementa reintentos en caso de fallos de red, ya que es crucial registrar las exposiciones correctamente para la validez estadística.

Implementación en el script de tracking

// Función para registrar exposición a experimentos
siteAnalyzer.exposeExperiment = function(experimentId, variationId, metadata = {}) {
  return fetch('/api/experiments/expose', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-SA-API-KEY': this.apiKey
    },
    body: JSON.stringify({
      site_id: this.siteId,
      visitor_id: this.visitorId,
      session_id: this.sessionId,
      experiment_id: experimentId,
      variation_id: variationId,
      url: window.location.href,
      timestamp: Date.now(),
      metadata: {
        page_title: document.title,
        viewport_size: `${window.innerWidth}x${window.innerHeight}`,
        device_type: this.getDeviceType(),
        ...metadata
      }
    })
  })
  .then(response => response.json())
  .catch(error => {
    // Guardar en cola para reintento posterior
    this.retryQueue.push({
      type: 'expose',
      payload: {
        experiment_id: experimentId,
        variation_id: variationId,
        metadata: metadata
      }
    });
    console.error('Error registrando exposición:', error);
  });
};

Límites y cuotas

• Máximo de exposiciones por minuto: 100 por IP
• Tamaño máximo de payload: 50KB
• Tamaño máximo de metadata: 10KB