Guía de la API de JavaScript para el seguimiento de eventos en el sitio

Copiar enlace al artículo

Copiado

Contenido

1. Primeros pasos: objeto ocapi
2. Envío de eventos
   • Datos transmitidos automáticamente
   • Creación de un nuevo cliente al enviar un evento
   • Uso de parámetros en la segmentación
3. Tipos de eventos y sus parámetros
   • Vista de la página (page_view)
   • Clic en un elemento (click)
   • Registro (register)
   • Acceso a la cuenta (login)
   • Solicitud de consulta (consult)
   • Apertura del carrito (open_cart)
   • Envío del formulario de contacto (contact)
   • Cambio del estado del carrito (cart)
   • Formalización del pedido (order)
   • Suscripción a envíos masivos (subscription)
   • Inicio de la cumplimentación del formulario (form_start)
   • Envío del formulario (form_submit)
   • Descarga de un archivo (file_download)
   • Actualización de productos favoritos (favorite_product)

En este artículo se explica cómo interactuar con el rastreador de eventos de Simla mediante la API de JavaScript.

Primeros pasos: objeto ocapi

Para interactuar con el rastreador se utiliza la API de JavaScript, disponible mediante el objeto global ocapi.

¡Importante!

El objeto ocapi y sus métodos solo están disponibles después de que la página se haya cargado por completo, cuando se produce el evento window.load. Por lo tanto, todo el código que interactúe con el rastreador debe ejecutarse desde el controlador de este evento.

Ejemplo: configuración del ID externo del cliente para vincular su perfil del sitio con el perfil de Simla.

window.addEventListener('load', () => {
  // Se presupone que la variable externalId ya está definida.
  ocapi.setCustomerSystemId(externalId);
});

La vinculación de los visitantes se describe con más detalle en la documentación principal.

Envío de eventos

Para enviar eventos personalizados manualmente se utiliza el método ocapi.event().

Sintaxis:

ocapi.event('eventName', { /* parámetros del evento */ });

• eventName (string): nombre del evento. Es un parámetro obligatorio.
• parameters (object): objeto con los parámetros del evento. Es un parámetro opcional.

Datos transmitidos automáticamente

En cada llamada a ocapi.event(), el rastreador recopila y transmite automáticamente los siguientes datos:

• La página actual en la que se encuentra el usuario.
• La URL de la página desde la que llegó el usuario (Referrer), incluidas las etiquetas UTM.
• La cookie del cliente de Google Analytics, si se utiliza.

Creación de un nuevo cliente al enviar un evento

Es posible crear un cliente en Simla en el momento de enviar un evento. Para ello, se debe añadir el indicador create_customer: true al objeto con los parámetros.

Para que el cliente se cree correctamente, deben cumplirse las siguientes condiciones:

1. Los parámetros del evento no deben contener system_customer_id.
2. Debe cumplirse una de estas condiciones:
   • los parámetros contienen system_external_customer_id;
   • los parámetros contienen create_customer_by_email: true y customer_email.
3. Los parámetros deben contener al menos uno de estos datos identificativos del cliente: customer_firstname, customer_lastname, customer_patronymic, customer_email o customer_phone.

Por lo tanto, el cliente puede crearse no solo cuando existe un ID en el sitio, sino también a partir de su correo electrónico cuando no se dispone de un ID externo.

Ejemplo de creación de un cliente por correo electrónico sin un ID del sitio:

ocapi.event('register', {
  create_customer_by_email: true,
  create_customer: true,
  customer_email: 'test@example.com'
});

En los eventos preconfigurados, el comportamiento depende de la opción «Crear cliente por correo electrónico»:

• Si la opción está desactivada, solo se guardan los eventos de usuarios que tienen un ID en el sitio.
• Si la opción está activada, también pueden guardarse eventos de usuarios sin un ID en el sitio, siempre que se indique al menos su correo electrónico.

El correo electrónico de un evento preconfigurado se establece como un parámetro normal del evento. Por ejemplo, puede obtenerse del valor de un elemento de la página mediante un selector.

Uso de parámetros en la segmentación

Los parámetros transmitidos con los eventos pueden utilizarse para aplicar filtros adicionales al crear segmentos de clientes en Simla. Por ejemplo, permiten seleccionar a todos los clientes que hayan visto productos de una marca determinada.

Tipos de eventos y sus parámetros

A continuación se presenta la lista completa de eventos que pueden rastrearse, junto con sus parámetros y ejemplos de uso.

Vista de la página (page_view)

Registra las páginas o los productos que ha visto el cliente. Estos datos permiten determinar sus intereses con mayor precisión.

Parámetros:

• offer_id (int): ID interno de la variante de producto en Simla.
• offer_external_id (string): ID externo de la variante.
• offer_xml_id (string): ID de la variante en el sistema de almacén.
• offer_brand (string): marca del producto.

Para vincular correctamente la vista con el producto, se debe enviar al menos uno de estos identificadores: offer_id, offer_external_id u offer_xml_id. Si se envían varios, se procesan en este orden: offer_id, offer_external_id, offer_xml_id.

Ejemplos:

• Vista de una página normal sin vinculación con un producto:

  ocapi.event('page_view');

• Vista de la página de un producto con todos los identificadores:

  ocapi.event('page_view', {
  offer_id: 1,
  offer_external_id: '1ext',
  offer_xml_id: '1xml_id',
  offer_brand: 'Mark 42'
  });

• Vista indicando únicamente offer_external_id:

  ocapi.event('page_view', {
  offer_external_id: 'product-123'
  });

Clic en un elemento (click)

Registra los elementos de la página con los que ha interactuado el cliente. Estos datos ayudan a analizar el recorrido del usuario y detectar posibles problemas de la interfaz.

Parámetros:

• el (string): selector o descripción textual del elemento en el que se hizo clic.
• leaving (bool): true si el clic lleva a un sitio externo.

Ejemplos:

• Clic sin indicar el elemento:

  ocapi.event('click');

• Clic en el botón «Ayuda»:

  ocapi.event('click', {
  el: 'Ayuda'
  });

• Clic en un enlace a un recurso externo:

  ocapi.event('click', {
  el: 'Sitio asociado',
  leaving: true
  });

Registro (register)

Permite obtener en Simla los datos de un nuevo cliente en tiempo real, sin esperar a una exportación programada desde el sitio.

Parámetros:

• customer_first_name (string): nombre.
• customer_last_name (string): apellidos.
• customer_patronymic (string): patronímico.
• customer_email (string): correo electrónico.
• customer_phone (string): número de teléfono.
• subscriptions (array): matriz de objetos con información sobre las suscripciones.
  • channel (string): canal de suscripción ('email', 'sms', 'waba').
  • subscription (string): información sobre la suscripción, por ejemplo, el nombre del envío masivo.
  • active (bool): indicador de actividad de la suscripción.

¡Importante!

Al transmitir una suscripción en la matriz subscriptions, se debe indicar expresamente active: true. Si no se especifica, la suscripción se considera inactiva porque el valor predeterminado es false.

Ejemplos:

• Registro con todos los datos:

  ocapi.event('register', {
  customer_first_name: 'Juan',
  customer_last_name: 'Pérez',
  customer_patronymic: 'Ivánovich',
  customer_email: 'test@example.com',
  customer_phone: '79559990101',
  subscriptions: [
    {
      channel: 'email',
      subscription: 'Novedades y promociones',
      active: true
    }
  ]
  });

• Registro del evento sin datos:

  ocapi.event('register');

Acceso a la cuenta (login)

Permite registrar la actividad de los usuarios registrados y diferenciarla de la actividad de los visitantes ocasionales.

Parámetros:

• customer_email (string): correo electrónico del usuario que ha iniciado sesión.

Ejemplos:

// Sin parámetros
ocapi.event('login');

// Con el correo electrónico
ocapi.event('login', {
  customer_email: 'test@example.com'
});

Solicitud de consulta (consult)

Registra las solicitudes de ayuda de los clientes. El análisis de estos datos permite evaluar la experiencia del usuario y automatizar las respuestas a preguntas frecuentes.

Parámetros:

• customer_email (string): correo electrónico de contacto del usuario.

Ejemplos:

// Sin parámetros
ocapi.event('consult');

// Con el correo electrónico
ocapi.event('consult', {
  customer_email: 'test@example.com'
});

Apertura del carrito (open_cart)

Permite determinar con qué frecuencia los clientes consultan el contenido del carrito sin continuar con la formalización del pedido.

Parámetros:

• customer_email (string): correo electrónico del usuario.

Ejemplos:

// Sin parámetros
ocapi.event('open_cart');

// Con el correo electrónico
ocapi.event('open_cart', {
  customer_email: 'test@example.com'
});

Envío del formulario de contacto (contact)

Ayuda a determinar los canales de comunicación que prefieren los clientes y el número de usuarios dispuestos a compartir su opinión.

Parámetros:

• channel (string): tipo de canal ('email', 'waba', 'sms').

Ejemplos:

// Sin parámetros
ocapi.event('contact');

// Con el canal
ocapi.event('contact', {
  channel: "waba"
});

Cambio del estado del carrito (cart)

Transmite a Simla la composición actual del carrito. Esto permite consultar los productos del cliente en el sistema y utilizar mecanismos de marketing para trabajar con carritos abandonados.

Parámetros:

• cart_id (string): identificador actual del carrito en el sitio. Es obligatorio.
• items (array): lista de productos del carrito. Es obligatoria.
  • id (int): ID interno de la variante.
  • external_id (string): ID externo de la variante.
  • xml_id (string): ID de la variante en el sistema de almacén.
  • price (float): precio por unidad. Si no se transmite, se utiliza el precio del catálogo de Simla.
  • quantity (int): cantidad del producto. Es obligatoria.

Para cada producto de items se debe transmitir al menos uno de estos identificadores: id, external_id o xml_id. Se procesan en este orden: id, external_id, xml_id.

Ejemplo:

ocapi.event('cart', {
  cart_id: 'ext_id_12345',
  items: [
    {
      id: 1, // Identificador de Simla
      external_id: 'ext_1',
      xml_id: 'xml_id_1',
      price: 159.00,
      quantity: 2
    },
    {
      external_id: 'product-abc', // Otro producto
      quantity: 1
      // No se indica el precio; se tomará del sistema.
    }
  ]
});

Formalización del pedido (order)

Registra la creación de un pedido en el sitio.

Atención

Actualmente, este evento solo registra el hecho de que el cliente ha formalizado un pedido durante su visita. El pedido y su composición no se transmiten a Simla mediante este método.

Todos los parámetros son opcionales.

Parámetros:

• order_number (string): número del pedido en el sitio.
• order_external_id (string): ID externo del pedido en el sistema.
• total (float): importe total del pedido, incluida la entrega.
• delivery_price (float): coste de la entrega.
• items (array): lista de productos con una estructura análoga a la del evento cart.

Ejemplos:

• Registro del evento sin parámetros:

  ocapi.event('order');

• Transmisión del número y el ID externo del pedido:

  ocapi.event('order', {
  order_number: '100-C',
  order_external_id: '100_E'
  });

Suscripción a envíos masivos (subscription)

Registra las suscripciones a envíos de marketing y permite determinar qué canales de notificación se utilizan con mayor frecuencia.

Parámetros:

• channel (string): canal de suscripción ('email', 'waba', 'sms').
• subscription (string): información sobre la suscripción.
• active (bool): indicador de actividad de la suscripción.

¡Importante!

Al igual que en el evento register, si se indica channel, se debe transmitir expresamente active: true para activar la suscripción.

Ejemplos:

// Registro de la suscripción sin parámetros
ocapi.event('subscription');

// Suscripción por correo electrónico a un envío concreto
ocapi.event('subscription', {
  channel: 'email',
  subscription: 'Envío de la nueva colección',
  active: true
});

Inicio de la cumplimentación del formulario (form_start)

Registra el momento en que el usuario comienza a interactuar con un formulario. En combinación con form_submit, ayuda a detectar problemas: si se registran muchos eventos form_start y pocos form_submit, puede que el formulario sea demasiado complejo.

Parámetros:

• form_selector (string): selector CSS del formulario.

Ejemplos:

// Sin parámetros
ocapi.event('form_start');

// Con el selector del formulario
ocapi.event('form_start', {
  form_selector: 'form.checkout-form'
});

Envío del formulario (form_submit)

Registra el envío correcto de un formulario y permite analizar la conversión y la eficacia de los distintos formularios del sitio.

Parámetros:

• form_selector (string): selector CSS del formulario enviado.

Ejemplos:

// Sin parámetros
ocapi.event('form_submit');

// Con el selector del formulario
ocapi.event('form_submit', {
  form_selector: '#form-checkout'
});

Descarga de un archivo (file_download)

Permite determinar qué contenido descargable, como listas de precios, instrucciones o libros electrónicos, es más popular entre los usuarios.

Parámetros:

• file_name (string): nombre del archivo descargado.

Ejemplos:

// Registro de la descarga sin parámetros
ocapi.event('file_download');

// Descarga de un archivo concreto
ocapi.event('file_download', {
  file_name: 'price-list-2025.pdf'
});

Actualización de productos favoritos (favorite_product)

Registra los cambios en la lista de productos favoritos del cliente. Si está configurada la vinculación de los eventos con el cliente en el sistema, la lista de favoritos se sincroniza con dicho cliente.

Parámetros:

• offer_id (int): ID interno de la variante en Simla.
• offer_external_id (string): ID externo de la variante.
• offer_xml_id (string): ID de la variante en el sistema de almacén.
• removed (bool): true si el producto se ha eliminado de favoritos o false si se ha añadido.

Para vincular correctamente la variante con los favoritos, se debe transmitir al menos uno de estos identificadores: offer_id, offer_external_id u offer_xml_id. Si se transmiten varios, se tienen en cuenta conjuntamente: la variante debe coincidir con todos los identificadores enviados.

Ejemplos:

• Producto añadido a favoritos:

  ocapi.event('favorite_product', {
  offer_external_id: '1ext',
  });

• Producto añadido a favoritos mediante el ID XML y el ID interno de la variante:

  ocapi.event('favorite_product', {
  offer_id: 1,
  offer_xml_id: '1xml_id',
  });