Guía práctica para trabajar con JS API

Copiar enlace al artículo

Copiado

Contenido

1. Introducción
   • Primeros pasos con JS API: onOcapiReady
2. Suscripción a eventos
   • Eventos con y sin parámetros
   • Eventos de formularios
   • Eventos de mensajes
3. Métodos generales de interacción
   • Comprobación de la actividad del widget y del tracker
   • Establecer el ID del cliente en el sistema y el ID externo
4. Interacción con el widget
   • Apertura y cierre del widget
   • Cambiar el mensaje de bienvenida
   • Rellenar el formulario de contacto y el formulario offline
   • Desactivar completamente el widget
   • Ocultar y mostrar el botón del widget
5. Interacción con el tracker
   • Iniciar el tracker
   • Enviar un evento del tracker
6. Depuración en producción
   • Instalación del script
   • Descifrado de mensajes

JS API (Consultant & Tracker JS API) proporciona una interfaz para que el código del sitio interactúe con el widget del Consultor y con el tracker.

Nota

No debe confundirse con la JS API para módulos JS.

En este artículo se utiliza la forma abreviada JS API para referirse a Consultant & Tracker JS API.

Introducción

JS API permite realizar las siguientes acciones:

• Suscribirse a eventos.
• Abrir y cerrar el widget.
• Cambiar el mensaje de bienvenida del widget.
• Rellenar los formularios de contacto y offline del widget.
• Desactivar el widget.
• Ocultar y mostrar el botón del widget.
• Comprobar la actividad del widget y del tracker.
• Iniciar el tracker si se había detenido.
• Enviar eventos del tracker.
• Establecer el ID del cliente en el sistema.
• Establecer el ID externo del cliente, es decir, su ID en el sitio.
• Usar una función de retorno (callback) para ejecutar acciones después de cargar la API, pero antes de renderizar el botón o enviar eventos.

Eventos disponibles:

• load — se activa cuando el widget termina de cargarse. No recibe parámetros.
• open — se activa al abrir el widget, tanto de forma programática como manual.
• close — se activa al cerrar el widget, tanto de forma programática como manual.
• before_contact_form — se activa antes de enviar el formulario de contacto, pero después de validarlo. Permite modificar el resultado del envío.
• before_offline_form — se activa antes de enviar el formulario offline, pero después de validarlo. Permite modificar el resultado del envío.
• contact_form — se activa después de enviar el formulario de contacto y permite conocer el estado del envío.
• offline_form — se activa después de enviar el formulario offline y permite conocer el estado del envío.
• first_user_message — se activa con el primer mensaje del usuario en el sitio.
• first_message — se activa con el primer mensaje del usuario en la pestaña actual.

Primeros pasos con JS API: onOcapiReady

La API define la propiedad ocapi en el objeto window. Antes de comenzar, es necesario asegurarse de que la API se haya inicializado completamente. Para trabajar de forma fiable con la API, especialmente cuando deben ejecutarse acciones antes de que aparezca el botón del widget, debe utilizarse la función onOcapiReady definida en window.

Esta función se ejecuta inmediatamente después de inicializar la API y antes de que se emita el evento load.

function onOcapiReady() {
    const api = window.ocapi;

    // Trabajar con la API.
}

Suscripción a eventos

La suscripción a eventos permite reaccionar a las distintas etapas del ciclo de vida del Consultor.

function onOcapiReady() {
    window.ocapi.on('load', () => {
        console.log('Consultant has been loaded!');
    });
}

Si un evento transmite parámetros, la función de retorno puede trabajar con ellos. Por ejemplo, es posible bloquear el envío de un formulario si la dirección de correo electrónico no cumple determinados criterios.

// Bloquea el formulario de contacto para direcciones de Proton Mail.
function onOcapiReady() {
    const protonExpr = /protonmail\.com$|proton\.me$|pm\.me$/i;

    window.ocapi.on('before_contact_form', (event) => {
        const data = event.data;

        if (data.email && protonExpr.test(data.email)) {
            event.error('Lo sentimos, Proton Mail no está disponible en este momento.');
        }
    });
}

Eventos con y sin parámetros

Entre los eventos que reciben información se distinguen las siguientes categorías:

• Eventos que transmiten contexto y permiten modificar el resultado:
  • before_contact_form
  • before_offline_form
• Eventos que transmiten información sobre lo ocurrido, pero no permiten modificarlo:
  • contact_form
  • offline_form
  • first_user_message
  • first_message

Eventos de formularios

Todos los eventos relacionados con formularios reciben un objeto con las siguientes propiedades y métodos:

• done — contiene true si el formulario ya se ha enviado; de lo contrario, contiene false.
• err — contiene una instancia de Error si el envío ha fallado debido a un error, o null si no se han producido errores.
• prevent() — impide enviar el formulario. Solo está disponible para los eventos con el prefijo before_.
• error(String) — impide enviar el formulario y muestra el texto de error indicado. Si se proporciona un valor falsy, se utiliza el texto estándar. Solo está disponible para los eventos con el prefijo before_.
• data — contiene los datos del formulario que se está enviando.

El campo data tiene el siguiente formato:

interface IFormUser {
    name?: string,
    email?: string,
    phone?: string
}

Ejemplo de validación de los datos del campo data:

function onOcapiReady() {
    window.ocapi.on('before_offline_form', (event) => {
        const data = event.data;

        if (data.name && data.name === 'Stalin') {
            alert('¡Lenin!');
            event.prevent();
        }
    });
}

Eventos de mensajes

Esta categoría incluye los eventos first_user_message y first_message.

first_user_message se activa una sola vez para el primer mensaje de un usuario con un ID específico, incluidas sus sesiones anteriores. first_message se activa cuando se escribe el primer mensaje después de abrir el widget en una pestaña nueva o de volver a cargar la página.

Ejemplo de suscripción a first_user_message para enviar datos a Google Analytics 4:

function onOcapiReady() {
    const api = window.ocapi;

    api.on('first_user_message', (event) => {
        const eventParams = {
            event_category: 'User Messages',
            event_label: event.content,
            message_id: event.id,
            from_me: event.fromMe,
            message_status: event.status,
            message_type: event.type,
            message_time: event.time,
            data_id: event.data.id,
            data_time: event.data.time,
            data_updated_at: event.data.updatedAt,
            data_status: event.data.status
        };

        // Evento de Google Analytics 4.
        gtag('event', 'first_user_message', eventParams);
    });
}

Formato del parámetro event:

interface Message {
    id: string;
    content: string;
    fromMe: boolean;
    status: string;
    type: string;
    time: string; // Fecha en formato ISO 8601.
    data: {
        id: string;
        time: string; // Fecha en formato ISO 8601.
        updatedAt: string; // Fecha en formato ISO 8601.
        status: string;
    };
}

Ejemplo del contenido de event:

{
    "id": "uid1761070046528",
    "content": "Hello!",
    "fromMe": true,
    "status": "sent",
    "type": "text",
    "time": "2025-10-21T18:07:26.540608958Z",
    "data": {
        "id": "146",
        "time": "2025-10-21T18:07:26.540608958Z",
        "updatedAt": "2025-10-21T18:07:26.540608958Z",
        "status": "sent"
    }
}

Métodos generales de interacción

Estos métodos afectan tanto al widget como al tracker.

Comprobación de la actividad del widget y del tracker

function onOcapiReady() {
    const api = window.ocapi;

    api.hasWidget(); // Devuelve true si el widget está disponible; de lo contrario, false.
    api.hasTracker(); // Devuelve true si el tracker está disponible; de lo contrario, false.
}

Importante

Después de llamar al método disableWidget() para desactivar completamente el widget, hasWidget() siempre devuelve false, independientemente de que el widget estuviera disponible al cargar la página.

Establecer el ID del cliente en el sistema y el ID externo

function onOcapiReady() {
    const api = window.ocapi;

    // Establece customer.id en el sistema.
    api.setCustomerSystemId(1);

    // Establece customer.externalId en el sistema.
    api.setCustomerSiteId('external_1');
}

Características de estos métodos:

• setCustomerSystemId y setCustomerSiteId pueden recibir un número, una cadena o una función.
• La función proporcionada a setCustomerSystemId debe devolver un número.
• La función proporcionada a setCustomerSiteId debe devolver una cadena.
• Cuando se proporciona una función a setCustomerSiteId, el widget y el tracker la procesan de forma diferente:
  • En el widget, la función se ejecuta una vez y se guarda el resultado.
  • El tracker ejecuta la función cada vez que necesita obtener customer.externalId.
• setCustomerSiteId afecta tanto al widget como al tracker.
• setCustomerSystemId afecta únicamente al tracker.

Importante

Se recomienda utilizar setCustomerSiteId o proporcionar customer.externalId mediante _rcco.

Interacción con el widget

Estos métodos gestionan únicamente el widget.

Apertura y cierre del widget

function onOcapiReady() {
    const api = window.ocapi;

    if (!api.hasWidget()) {
        return;
    }

    // Abre el widget.
    api.openWidget();

    // Cierra el widget.
    api.closeWidget();
}

Nota

No es obligatorio comprobar la disponibilidad del widget mediante hasWidget(). Si no está disponible, estos métodos no realizan ninguna acción.

Cambiar el mensaje de bienvenida

El método setWelcomeMessage permite establecer o quitar el mensaje de bienvenida del widget. Solo admite texto.

function onOcapiReady() {
    const api = window.ocapi;

    // Establece el mensaje de bienvenida.
    api.setWelcomeMessage('¡Hola!');

    // Quita el mensaje de bienvenida.
    api.setWelcomeMessage(null);
}

Rellenar el formulario de contacto y el formulario offline

El método setWelcomeFormUser permite rellenar previamente los campos del formulario de contacto y del formulario offline. No envía el formulario automáticamente, por lo que el cliente puede revisar y modificar los datos antes de enviarlos.

function onOcapiReady() {
    window.ocapi.setWelcomeFormUser({
        name: 'Arturo',
        email: 'arthur@example.com',
        phone: '78000000000'
    });
}

Características del método:

• Los datos se rellenan tanto en el formulario de contacto como en el formulario offline.
• El método solo completa los datos existentes y no permite borrar campos que ya se hayan rellenado.

Desactivar completamente el widget

El método disableWidget desactiva completamente el widget en la página. Como resultado, el script pasa al modo «solo tracker» o deja de funcionar por completo si el tracker tampoco está disponible.

function onOcapiReady() {
    const currentPage = window.location.pathname;

    const isOrderPage = currentPage.includes('/order') || currentPage.includes('/cart');
    const isCheckoutPage = currentPage.includes('/checkout');

    if (isOrderPage || isCheckoutPage) {
        window.ocapi.disableWidget();
    }
}

Ocultar y mostrar el botón del widget

function onOcapiReady() {
    const api = window.ocapi;

    if (!api.hasWidget()) {
        return;
    }

    // Oculta el botón del widget.
    api.hideWidgetButton();

    // Muestra el botón del widget.
    api.showWidgetButton();
}

Interacción con el tracker

Estos métodos gestionan únicamente el tracker.

Iniciar el tracker

La función startTracking resulta útil cuando se utilizan formularios para obtener el consentimiento, por ejemplo, banners de cookies para cumplir el Reglamento General de Protección de Datos (RGPD). Si la compatibilidad con estos formularios está habilitada en la configuración, el tracker no enviará eventos hasta que el usuario otorgue su consentimiento.

Ejemplo de uso con un cuadro de diálogo confirm:

function onOcapiReady() {
    const api = window.ocapi;

    api.on('load', () => {
        if (confirm('¿Acepta la recopilación de telemetría anonimizada?')) {
            api.startTracking();
        }
    });
}

Enviar un evento del tracker

Para enviar eventos personalizados al tracker se utiliza el método event.

function onOcapiReady() {
    const api = window.ocapi;

    api.on('load', () => {
        api.event('page_view');
    });
}

Hay más ejemplos de envío y una lista de tipos de eventos con sus parámetros en la sección correspondiente de la guía de JS API para rastrear eventos en el sitio.

Depuración en producción

Para depurar los eventos del tracker y supervisar las llamadas a los métodos de la API puede utilizarse un script de usuario especial. Este añade a la consola del navegador un registro de todas las llamadas a la API, de forma similar al depurador de Google Tag Manager (GTM).

Importante

El script de usuario debe desactivarse después de utilizarlo para evitar que se ejecute en todos los sitios visitados.

Instalación del script

1. Instale un gestor de scripts de usuario para el navegador:
   • Chrome: Tampermonkey
   • Firefox: Violentmonkey o Greasemonkey
   • Microsoft Edge: Tampermonkey
   • Opera: Tampermonkey
   • Safari: Userscripts
2. Instale el script de usuario para depuración o copie su contenido e instálelo manualmente.
3. Si es necesario, siga las instrucciones del gestor. Por ejemplo, Tampermonkey puede solicitar que se active el modo de desarrollador.

En navegadores basados en Chromium, como Chrome, Microsoft Edge o Brave, Tampermonkey puede requerir un permiso adicional para ejecutar scripts de usuario:

1. Abra la lista de extensiones instaladas, normalmente en Configuración → Extensiones.
2. Active «Modo de desarrollador» en la esquina superior derecha.
3. Busque Tampermonkey y seleccione «Detalles» en su tarjeta.
4. Active «Permitir scripts de usuario».
5. Reinicie el navegador.

Después de completar estos pasos, los scripts de usuario comenzarán a ejecutarse correctamente. En todos los sitios que utilicen JS API, su actividad se registrará en la consola del navegador.

Descifrado de mensajes

Todos los mensajes del depurador tienen el prefijo [OCAPI], que permite filtrarlos en la pestaña Console.

• window.ocapi detected, verbose logging has been enabled.

  Se ha detectado la API y se ha activado el script.

• window.ocapi not found after 30000ms

  No se ha detectado la API en el sitio.

• _rcct was not defined as window property but rather as a global scope variable...

  La variable indicada, _rcct o _rcco, no se ha declarado como propiedad de window, sino en el ámbito global, por ejemplo, mediante const o let. Esto puede afectar al funcionamiento del Consultor. Se recomienda cambiar la declaración a var.

• Found site token in window._rcct: 0

  Muestra el valor del token del sitio que utilizarán el widget o el tracker.

• Found widget settings in window._rcco: {}

  Muestra el contenido de window._rcco.

• _rcco has non-falsy customer.customer_id but it was NOT set in the tracker.

  Se ha indicado customer_id en window._rcco, pero no se ha establecido en el script del tracker. Como resultado, los eventos no se vincularán con los clientes.

• Incorrect onOcapiReady definition, should be available on window:

  La función onOcapiReady se ha definido de forma incorrecta.

• dispatched event 'load'

  Se ha emitido un evento al que es posible suscribirse mediante ocapi.on. El evento puede contener contexto.

• tracker event 'page_view'

  Se ha enviado un evento del tracker, incluidos los eventos estándar. El mensaje puede expandirse para consultar los datos del evento.

• flushing tracker events

  Se están enviando los eventos acumulados. El mensaje puede expandirse para consultar los datos enviados.

Los demás mensajes corresponden al registro de llamadas a los métodos de ocapi. Entre los más útiles se encuentran:

• on() — suscripción a un evento.
• event() — envío programático de un evento del tracker.

La mayoría de los mensajes aparecen contraídos. Para expandirlos, selecciónelos en la consola del navegador.