Endpoint de Conversión

El endpoint /api/experiments/convert registra cuando un visitante que ha sido expuesto a un experimento realiza una acción definida como meta u objetivo. Estas conversiones son fundamentales para analizar el rendimiento de las diferentes variantes de un experimento.

Especificación de la API

• URL: /api/experiments/convert
• 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",
  "goal_id": "goal_1",
  "url": "https://ejemplo.com/gracias-por-su-compra",
  "value": 99.95,
  "timestamp": 1646123789456,
  "metadata": {
    "order_id": "ord_98765",
    "products": [
      {
        "id": "prod_123",
        "name": "Zapato Casual Negro",
        "price": 49.95,
        "quantity": 2
      }
    ],
    "coupon_applied": "WELCOME10"
  }
}

Respuesta

{
  "success": true,
  "conversion_id": "conv_12345abcde",
  "timestamp": 1646123789460
}

Códigos de estado HTTP

• 200 OK: Conversió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 meta no encontrados
• 409 Conflict: Conversión duplicada
• 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": "no_exposure",
    "message": "No hay registro de exposición a este experimento para el visitante",
    "details": {
      "experiment_id": "exp_12345",
      "visitor_id": "vis_abcd1234"
    }
  }
}

Tipos de conversión

El sistema soporta diferentes modelos de atribución para las conversiones:

1. Directa: Se atribuye al último experimento visto
2. First touch: Se atribuye al primer experimento visto
3. Linear: Se distribuye equitativamente entre todos los experimentos vistos
4. Time decay: Se atribuye de forma ponderada, dando más peso a exposiciones recientes
5. Position based: Se da más peso al primer y último experimento visto

El modelo de atribución por defecto es “Directa”, pero se puede especificar usando el campo attribution_model:

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "experiment_id": "exp_12345",
  "goal_id": "goal_1",
  "url": "https://ejemplo.com/gracias-por-su-compra",
  "value": 99.95,
  "attribution_model": "linear"
}

Conversiones de múltiples experimentos

En entornos donde un visitante puede estar expuesto a múltiples experimentos, se puede registrar una conversión para varios experimentos simultáneamente:

{
  "site_id": "site_123abc",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "url": "https://ejemplo.com/gracias-por-su-compra",
  "value": 99.95,
  "timestamp": 1646123789456,
  "conversions": [
    {
      "experiment_id": "exp_12345",
      "goal_id": "goal_1"
    },
    {
      "experiment_id": "exp_67890",
      "goal_id": "goal_3"
    }
  ]
}

Conversiones automáticas

Algunos tipos de eventos pueden convertirse automáticamente sin necesidad de llamar explícitamente a este endpoint:

1. Clics: Si una meta está definida como un clic en un selector específico
2. Pageviews: Si una meta está definida como una visita a una URL específica
3. Formularios: Si una meta está definida como un envío de formulario

Para estas conversiones automáticas, el script de tracking se encarga de registrarlas.

Ventana de conversión

Por defecto, las conversiones se atribuyen a experimentos vistos dentro de una ventana de 30 días. Este valor se puede configurar en el panel de control.

Deduplicación de conversiones

Para evitar contar múltiples veces la misma conversión, el sistema implementa las siguientes reglas:

1. Mismo objetivo en la misma sesión: Solo se cuenta una vez por experimento y sesión.

2. Objetivos repetibles: Algunos objetivos pueden marcarse como “repetibles”, lo que permite contabilizar múltiples conversiones (ej: compras recurrentes).

Buenas prácticas

1. Conversión precisa: Asegúrate de que el evento de conversión se dispare en el momento exacto en que se completa la acción deseada.

2. Incluir valor: Para objetivos relacionados con compras o ingresos, incluye siempre el campo value para calcular el valor monetario de cada variante.

3. Datos contextuales: Incluye información relevante en el campo metadata para análisis más detallados.

4. Reintentos: Implementa un mecanismo de reintentos para casos de error de red, ya que es crucial no perder conversiones.

Implementación en el script de tracking

// Función para registrar conversiones de experimentos
siteAnalyzer.trackConversion = function(experimentId, goalId, value = null, metadata = {}) {
  return fetch('/api/experiments/convert', {
    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,
      goal_id: goalId,
      url: window.location.href,
      value: value,
      timestamp: Date.now(),
      metadata: metadata
    })
  })
  .then(response => response.json())
  .catch(error => {
    // Guardar en cola para reintento posterior
    this.retryQueue.push({
      type: 'convert',
      payload: {
        experiment_id: experimentId,
        goal_id: goalId,
        value: value,
        metadata: metadata
      }
    });
    console.error('Error registrando conversión:', error);
  });
};
 
// Ejemplo de uso
siteAnalyzer.trackConversion('exp_12345', 'goal_1', 99.95, {
  order_id: 'ord_98765',
  coupon_applied: 'WELCOME10'
});

Límites y cuotas

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