Guía de integración del SDK Web

Este documento es la guía de integración estándar del SDK Web de MA.

Descripción del producto

El SDK Web de MA proporciona funciones de recopilación y envío de datos, que se utilizan en escenarios como la generación de EUID, la configuración de propiedades de usuario y el reporte de eventos.

Opciones de integración

El SDK Web de MA admite 2 modos de integración: junto con WebPush o utilizando únicamente el SDK Web de MA.

• Junto con WebPush: al integrar el módulo WebPush de EngageLab, habilitar la función de MA; el SDK de MA se cargará automáticamente.
• Solo el SDK Web de MA: integrar directamente la dirección del SDK de MA en el sitio web, sin funciones de WebPush.

Junto con WebPush

Preparativos antes de la integración

• Es necesario integrar también el módulo WebPush.
• Preparar un nombre de dominio de servicio web HTTPS accesible. Tras la integración, es necesario probar y depurar las páginas bajo este nombre de dominio. El push web sin conexión no admite depuración local ni HTTP.
• Acceder a EngageLab WebPush y, en la página [Ajustes de integración] - [Nombre de dominio del sitio web], completar el nombre de dominio del servicio web HTTPS.

Obtener información de la aplicación

Se debe crear una aplicación en la consola de WebPush. Tras la creación correcta, se generará automáticamente una AppKey para identificar esta aplicación. Para obtener más información, consultar el documento de configuración de la aplicación.

Configuración de la fuente de datos de MA

En el proyecto de MA, ir a Fuentes de datos - Añadir fuente de datos - Web, seleccionar «Usar junto con WebPush», elegir en la lista desplegable la aplicación creada en WebPush y guardar.

Acceso al SDK

Acceder a la consola, descargar el SDK e incluir el JavaScript en cada página:

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

Consejos

Tras importar este JavaScript, pasar la propiedad maOpen con el valor true para habilitar la configuración de MA, lo que permite utilizar las API y funciones correspondientes de MA.

Inicialización del SDK

              
                  //  Inicialización (habilitar MA)
  MTpushInterface.init({
    appkey: "", // Obligatorio, ver «Obtener información de la aplicación» más arriba
    user_str: "adminDemo", // Obligatorio, identificador de usuario, utilizado para identificar al usuario
    swUrl: "url", // Valor predeterminado: "/sw.min." + sdkEnv.version + ".js". Esta opción es la dirección del archivo del service worker; el dominio debe ser el dominio actual y la ruta determina el ámbito del service worker.
    debugMode: true,// Indica si se habilita el modo debug. true imprime más información de registro; false solo muestra los registros de nivel w y e.
    channel: "default-channel",// Nombre del canal, valor predeterminado: default-channel
    appName: "string",// Se utiliza para configurar el nombre del sitio web, usado en el reporte
    maOpen: true, // Activar el interruptor para habilitar la función de MA
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },// Configurar la identificación del usuario al inicializar MA. Compatible desde la versión 3.3.4, aplicable a empresas que ofrecen el servicio de MA únicamente a miembros con sesión iniciada
    maDataCollectionEnabled: false, // Estado inicial de la recopilación de datos de MA; habilitado de forma predeterminada si se omite. Compatible desde WebPush SDK 3.3.9
    maCompletion: (code, msg) => {// Callback de inicialización de MA
                if (code === 0) {
                    console.log("✅¡MA SDK inicializado correctamente!");
                } else {
                    console.error("❌Error al inicializar MA SDK:", msg);
                }
    }
  });

            

Interruptor de recopilación de datos (junto con WebPush)

Compatible desde: MA Web SDK 2.2.0, WebPush SDK 3.3.9

• Al inicializar con MTpushInterface.init, pasar dinámicamente el valor de maDataCollectionEnabled según el estado de consentimiento del usuario; el SDK de WebPush lo transmitirá al SDK de MA. No fijar el valor en el código, para evitar que cada inicialización restablezca el estado al valor fijado.
• Cuando cambie el estado de recopilación de datos del usuario, llamar a window.MAInterface.setDataCollectionEnabled(true/false) después de que se haya ejecutado el callback maCompletion. maCompletion es la señal de que el SDK de MA está disponible; antes de él, es posible que window.MAInterface aún no se haya cargado.
• Mientras la recopilación está deshabilitada, las notificaciones de WebPush siguen pudiendo entregarse y recibir clics, pero la atribución de conversiones de los clics en notificaciones deja de contabilizarse.

Para más detalles, consultar Interruptor de recopilación de datos.

Solo el SDK Web de MA

Configuración de la fuente de datos de MA

En el proyecto de MA, ir a Fuentes de datos - Añadir fuente de datos - Web, seleccionar «No usar» en «¿Usar junto con WebPush?», introducir el nombre de la fuente de datos y el dominio del sitio web; tras guardar se obtiene la AppKey de la fuente de datos Web.

• Preparar un nombre de dominio de servicio web HTTPS accesible. Tras la integración, es necesario probar y depurar las páginas bajo este nombre de dominio.

Acceso al SDK

Incluir el siguiente JavaScript en cada página:

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

Tras importar este JavaScript, se puede utilizar el objeto global MAInterface disponible en Window.

Nota especial: utilizar este enlace directamente. No descargar este archivo en el proyecto; de lo contrario, las estadísticas podrían dejar de funcionar cuando actualicemos la estructura de datos o las interfaces de la API.

Inicialización del SDK

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // Obligatorio, ver «Obtener información de la aplicación» más arriba
    debugMode: true,
    channel: "default-channel22",// Nombre del canal, valor predeterminado: default-channel
    appName: "EngageLab-MA test-appName", // Nombre del sitio web, utilizado como app_name en las propiedades del dispositivo y en el reporte de eventos
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, // Configurar la identificación del usuario al inicializar MA; admite user_id, anonymous_id, email y phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ ¡SDK inicializado correctamente!");
        } else {
            console.error("❌ Error al inicializar el SDK:", msg);
        }
    }
  })
        

            

Acerca de la identificación del usuario

• userIdentity admite 4 tipos de identificación del usuario: user_id, anonymous_id, email y phone (email y phone son compatibles desde la versión 2.1.0). Proporcionar al menos uno. Las reglas de cada campo se detallan en Configurar la identificación del usuario.
• Los campos que no cumplan las reglas durante la inicialización se ignorarán y se imprimirá una advertencia en la consola; el resto de campos válidos seguirán aplicándose.
• email y phone se utilizan para la coincidencia de identidad del usuario, no como información de contacto. Para el correo electrónico y el número de teléfono utilizados en el envío de mensajes, utilizar la interfaz «Configurar la información de contacto del usuario» (setUserContact).

Reinicialización y cambio de AppKey

Compatible desde: 2.1.0

Una vez inicializado el SDK, se puede volver a llamar a init sin necesidad de actualizar la página:

• Pasar la misma AppKey: el SDK vuelve a obtener el EUID. Si al mismo tiempo se pasa un nuevo userIdentity, el SDK vuelve a obtener el EUID con la nueva identificación del usuario, lo que resulta útil para cambiar de cuenta tras cerrar sesión dentro de la misma página.
• Pasar una AppKey distinta: el SDK cambia a la fuente de datos de MA correspondiente a la nueva AppKey, y los datos posteriores se reportan a la nueva fuente de datos; los datos generados antes del cambio se siguen reportando a la fuente de datos original.
• Las llamadas múltiples a init se ejecutan en el orden en que se invocan, y cada llamada devuelve su resultado mediante completion; tomar como referencia el resultado del callback correspondiente.
• El cambio de AppKey solo se admite cuando se utiliza únicamente el SDK Web de MA; el modo de integración «junto con WebPush» no lo admite.

              
                // Cambiar a otra fuente de datos de MA
  window.MAInterface.init({
    appKey: "AppKey de otra fuente de datos",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

Configurar el ID de contacto del canal

Compatible desde: 2.1.0

Si es necesario configurar el RID o el token para WebPush o para un canal Push de terceros, llamar a lo siguiente una vez que el SDK se haya inicializado correctamente:

              
                window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })

            

• channelId: ID del canal Push configurado en la consola de MA; debe ser mayor que 0.
• values: array de RID o tokens; ni el array ni sus elementos pueden estar vacíos. Cuando cambie el RID o el token, es necesario volver a llamar a la interfaz para actualizarlo.

Para más detalles, consultar Configurar el ID de contacto del canal.

Interruptor de recopilación de datos

Compatible desde: 2.2.0

La aplicación controla si el SDK de MA recopila datos según el resultado del consentimiento del usuario. Una vez deshabilitado, el SDK no genera, almacena en caché ni reporta eventos, propiedades de usuario, UTM ni información del dispositivo; la inicialización, la identificación del usuario, la información de contacto y el ID de contacto del canal siguen funcionando con normalidad. El estado se guarda localmente en el navegador y se conserva tras actualizar la página.

              
                // Al inicializar, pasar dinámicamente el valor de dataCollectionEnabled según el estado de consentimiento del usuario; no fijarlo en el código, para evitar que cada inicialización restablezca el estado al valor fijado
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // Habilitado de forma predeterminada si se omite
    completion: (code, msg) => {}
  })

  // Después de que el usuario otorgue / retire el consentimiento
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• Si el valor configurado coincide con el estado actual, no se activa el procesamiento de cambio; sincronizar la elección del usuario en cada carga de página no produce efectos adicionales.
• Si se llama a las interfaces de propiedades de usuario mientras la recopilación está deshabilitada, completion devuelve -8; las interfaces sin callback, como eventos y UTM, descartan los datos de forma silenciosa.
• Cuando el almacenamiento está degradado (localStorage no disponible), el estado del interruptor solo es válido en la pestaña actual.

Para más detalles, consultar Interruptor de recopilación de datos.

Más interfaces de API

Para el uso de otras API, consultar la documentación de la interfaz: Web SDK API.