Guía de API

Configurar la identificación del usuario

Versiones compatibles

Las identificaciones email y phone son compatibles desde: 2.1.0

Definición de la interfaz

• identifyAccount(user);
  • Descripción de la interfaz:
    • Configurar la identificación del usuario, como un número de tarjeta de socio.
  • Descripción de parámetros
    • identity: el ID de identificación del usuario. La clave admite 4 valores: user_id, anonymous_id, email y phone; proporcionar al menos uno, no es necesario completarlos todos
    • completion: el callback
  • Reglas de identificación del usuario
    • user_id: no vacío tras eliminar los espacios iniciales y finales, máximo 255 caracteres, no puede ser 0, null, undefined ni nan (sin distinguir mayúsculas y minúsculas)
    • anonymous_id: no vacío tras eliminar los espacios iniciales y finales, máximo 256 caracteres
    • email: dirección de correo electrónico del usuario, no vacía tras eliminar los espacios iniciales y finales, máximo 256 caracteres, debe tener un formato de correo electrónico válido, como user@example.com
    • phone: número de teléfono del usuario, debe estar en formato E.164 e incluir el código de país o región, como +8613800000000
    • Si algún campo no cumple las reglas, esta llamada no envía ninguna solicitud, completion devuelve -1 y message indica el motivo concreto

Ejemplo de llamada

              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            

Aquí, email y phone se utilizan para la coincidencia de identidad del usuario y pueden devolver un nuevo EUID; no son intercambiables con la información de contacto configurada mediante «Configurar la información de contacto del usuario» (setUserContact).

Obtener EUID

Definición de la interfaz

• + EUID()
  • Descripción de la interfaz:
    • Obtener el EUID de EngageLab MA

Ejemplo de llamada

              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            

Configurar la información de contacto del usuario

Definición de la interfaz

• setUserContact(user)
  • Descripción de la interfaz:
    • Permite configurar simultáneamente varios métodos de contacto. La clave es el nombre del método de contacto y el valor es su valor correspondiente. Actualmente se admiten 4 métodos de contacto: email, mobile_phone, landline_phone y whatsapp_phone
  • Descripción de parámetros
    • contacts: la información de contacto del usuario
    • completion: el callback

Ejemplo de llamada

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["nombre del método de contacto"] = "valor del método de contacto"   // Por ejemplo: mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

Configurar el ID de contacto del canal

Versiones compatibles

Compatible desde: 2.1.0

Definición de la interfaz

• setChannelValue(channelId, values, completion)
  • Descripción de la interfaz:
    • Configurar el RID o el token para un canal Push configurado en la consola de MA (como WebPush o un Push de terceros).
    • Debe llamarse una vez que el SDK se haya inicializado correctamente; de lo contrario, completion devuelve -1.
    • Cuando cambie el RID o el token, es necesario volver a llamar a la interfaz para actualizarlo.
  • Descripción de parámetros
    • channelId: ID del canal Push configurado en la consola de MA; debe ser un entero mayor que 0
    • values: array de valores del ID de contacto del canal (por ejemplo, RID o token); no puede estar vacío, y sus elementos tampoco pueden ser cadenas vacías
    • completion: el callback; code 0 indica éxito

Ejemplo de llamada

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

            

Interruptor de recopilación de datos

Versiones compatibles

Compatible desde: 2.2.0

Descripción de la función

La aplicación habilita o deshabilita la recopilación de datos del SDK de MA según el resultado del consentimiento del usuario, para cumplir el requisito de conformidad de no reportar datos de comportamiento después de que el usuario rechace o retire su consentimiento.

• Deshabilitado: se detiene la generación, el almacenamiento en caché y el reporte de eventos, propiedades de usuario, UTM e información del dispositivo. La inicialización, la obtención de EUID/RID, la configuración de la identificación del usuario, la configuración de la información de contacto y la configuración del ID de contacto del canal siguen funcionando con normalidad.
• Habilitado: se reanuda la recopilación; no se reenvían los datos del periodo deshabilitado.
• Habilitado de forma predeterminada: si no se configura, está habilitado de forma predeterminada, en consonancia con el comportamiento anterior a la actualización.
• Guardado en el equipo local: el estado se guarda localmente en el navegador (localStorage) y se conserva tras actualizar o volver a abrir la página. Al borrar los datos del sitio se restablece el valor predeterminado.
• El interruptor lo decide la aplicación: el SDK no determina la región del usuario, no muestra ventanas de consentimiento ni lee ninguna plataforma de gestión del consentimiento (CMP).

Definición de la interfaz

• init({ dataCollectionEnabled })

  • Descripción de la interfaz: configurar el estado del interruptor en el primer arranque durante la inicialización.
  • Descripción de parámetros: true habilita; false deshabilita; si se omite, está habilitado de forma predeterminada.

• setDataCollectionEnabled(enabled, completion)

  • Descripción de la interfaz: habilitar o deshabilitar la recopilación de datos; surte efecto de inmediato y se guarda en el equipo local.
  • Descripción de parámetros:
    • enabled: true habilita, false deshabilita
    • completion: el callback; code 0 indica éxito; devuelve -1 cuando el parámetro no es un valor booleano
  • Notas de llamada:
    • Si el valor configurado coincide con el estado actual, no se activa el procesamiento de cambio, por lo que sincronizar la elección del usuario en cada carga de página no produce efectos adicionales.
    • Al pasar de habilitado a deshabilitado, el SDK intenta de inmediato enviar una sola vez los datos generados antes del cambio (incluido el evento de fin de la sesión actual); si falla, no reintenta, y a continuación borra la caché local.
    • Al pasar de deshabilitado a habilitado, el SDK reporta la información del dispositivo e inicia una nueva sesión (reporta el_session_start y el el_page_view de la página actual).
    • Mientras está deshabilitado, la atribución de conversiones de los clics en notificaciones de WebPush deja de contabilizarse.

• isDataCollectionEnabled()

  • Descripción de la interfaz: devuelve el estado actual del interruptor; solo lee el estado local y no realiza solicitudes de red.
  • Descripción del valor devuelto: true habilitado, false deshabilitado; devuelve true si nunca se ha guardado un estado. El valor devuelto representa el estado del interruptor del SDK, no indica que el usuario haya dado su consentimiento.

Comportamiento de cada interfaz mientras está deshabilitado

Ejemplo de llamada

              
                // 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,
    completion: (code, msg) => {}
  })

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

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

  // Consultar
  const enabled = window.MAInterface.isDataCollectionEnabled()

            

Configurar propiedades UTM

Definición de la interfaz

• setUtmProperties(attrs:any)
  • Descripción de la interfaz:
    • Las propiedades UTM son propiedades estándar de eventos. Si los desarrolladores pueden identificar qué anuncio dirigió al usuario a la App, se recomienda configurar la información UTM; este parámetro se incluirá al reportar eventos. Actualmente, las propiedades UTM que se pueden configurar son:
      • utm_source: la fuente de la campaña publicitaria
      • utm_medium: el medio de la campaña publicitaria
      • utm_term: el término de la campaña publicitaria
      • utm_content: el contenido de la campaña publicitaria
      • utm_campaign: el nombre de la campaña publicitaria
      • utm_id: el ID de la campaña publicitaria

Ejemplo de llamada

              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            

Configurar propiedades del usuario

Configurar los valores de las propiedades del usuario. Si una propiedad del usuario no existe, se creará automáticamente en el backend.

Sobrescribir y actualizar propiedades del usuario

• setProperty(user, completion)
  • Descripción de la interfaz:
    • Sobrescribir y actualizar los valores de las propiedades del usuario.
    • Solo se guarda el último dato reportado, sustituyendo los datos históricos, como el nivel de socio del usuario.
    • El contenido de estas propiedades del usuario se almacena en un object. La clave es el nombre de la propiedad del usuario y debe ser un string; el valor es el contenido de la propiedad del usuario y admite los tipos string, number, Array, object y object_array.
    • Actualmente, los elementos de un valor de tipo Array solo pueden ser strings; un array cuyos elementos sean todos object se trata como object_array; un array que mezcle object con otros tipos no es válido.
    • Si una determinada propiedad del usuario ya existía previamente, en esta ocasión se sobrescribirá; si no existe, se creará. Las reglas de actualización de object y object_array se describen más abajo.
  • Ejemplo de llamada:

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

Reglas de object / object_array

Compatible desde: 2.1.0

• object es un objeto plano no vacío, como { city: "Singapore", score: 100 }; object_array es un array cuyos elementos son todos objetos planos no vacíos.
• Los nombres de los subcampos deben ser strings no vacíos y no pueden contener . ni $; los valores de los subcampos admiten string, number y arrays de string, y no se admite anidar object ni object_array.
• object utiliza la semántica de fusión de subcampos: al configurarlo de nuevo, solo se actualizan los subcampos pasados en esta ocasión y los subcampos no pasados se mantienen sin cambios; pasar null como valor de un subcampo indica que se elimina ese subcampo.
• object_array utiliza la semántica de sustitución completa: al configurarlo de nuevo, el nuevo array sustituye por completo al array original y se conserva el orden del array. Al crear un object_array por primera vez, pasar un array de objetos no vacío.
• El tipo de los subcampos debe coincidir con la definición de esa propiedad de usuario en la consola de MA; si no coincide, el servidor devuelve un error.

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // Solo se actualiza profile.score; profile.city se mantiene sin cambios
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

Incrementar y actualizar propiedades del usuario

• increaseProperty(user, completion)
  • Descripción de la interfaz:
    • Configurar un incremento para los valores de las propiedades del usuario.
    • Añadir valores a varias propiedades numéricas del usuario. Acumular todos los datos reportados, como el importe de consumo acumulado.
    • Esta interfaz solo se puede usar para propiedades del usuario de tipo number; de lo contrario, se ignorará. Si esta propiedad del usuario no existía previamente, el valor inicial se considera 0.
  • Ejemplo de llamada:

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

Añadir propiedades del usuario

• addProperty(key, content completion)
  • Descripción de la interfaz:
    • Añadir valores a los valores de las propiedades del usuario.
    • Añadir elementos continuamente a este conjunto. Los elementos duplicados se eliminan al almacenarse en la base de datos. Si ya existe ABC y se añade CD, el resultado final será ABCD, como las noticias que le gustan al usuario.
    • Añadir valores a una propiedad de tipo Array. Los elementos del Array deben ser strings; de lo contrario, se ignorarán. Al mismo tiempo, si la propiedad del usuario a la que se va a añadir no existía previamente, se inicializará un Array vacío.
  • Ejemplo de llamada:

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

Eliminar valores de propiedades del usuario

• removeProperty(key, content completion)
  • Descripción de la interfaz:
    • Eliminar uno o más valores de una propiedad de tipo array.
    • Eliminar algunos valores de una propiedad de tipo Array. Los elementos de este Array deben ser strings; de lo contrario, se ignorarán. Al mismo tiempo, si la propiedad del usuario de la que se va a eliminar no existía previamente, no tendrá efecto.
  • Ejemplo de llamada:

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

Operar sobre elementos de object_array

Versiones compatibles

Compatible desde: 2.1.0

Los siguientes usos se aplican únicamente a propiedades de usuario de tipo object_array y localizan un elemento del array mediante un subcampo identificador único. Cuando addProperty y removeProperty reciben un array de strings, siguen operando sobre arrays de strings y su comportamiento no cambia.

• addProperty(key, object, completion)
  • Descripción de la interfaz:
    • Cuando el segundo parámetro es un único object (no un array), añade un elemento al final del object_array sin afectar a los elementos existentes.
    • El object debe ser un objeto no vacío; las reglas de los subcampos son las mismas que para el tipo object, y no se admite anidar object ni object_array.
    • Si la propiedad aún no está definida en la consola de MA, el servidor la crea automáticamente como propiedad de tipo object_array y escribe este elemento; si está definida pero el usuario actual aún no tiene valor, se crea el array con este único elemento.
  • Ejemplo de llamada:

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • Descripción de la interfaz:
    • Localizar un elemento del object_array mediante un subcampo identificador único y actualizar por fusión los subcampos de ese elemento.
    • La estructura de content es { $identifier_key, $identifier_value, $new_object }:
      • $identifier_key: nombre del subcampo utilizado para localizar el elemento; este subcampo debe estar ya definido en la consola de MA, con tipo string o number
      • $identifier_value: valor de localización, de tipo string o number; si coinciden varios elementos, la actualización se aplica a todos ellos
      • $new_object: subcampos a actualizar; debe ser un objeto no vacío y no puede contener el subcampo correspondiente a$identifier_key; los subcampos no pasados se mantienen sin cambios, y pasar null como valor de un subcampo indica que se elimina ese subcampo
    • Si no hay ningún elemento coincidente en el array o si los subcampos no se ajustan a la definición de la propiedad, el servidor devuelve un error y no modifica los demás elementos; si coinciden varios elementos, se aplica la misma actualización a todos los elementos coincidentes.
    • Si la propiedad aún no está definida, el servidor devuelve un error (55004); si está definida pero el usuario actual aún no tiene valor para esa propiedad, el servidor devuelve code=0 sin realizar cambios.
  • Ejemplo de llamada:

              
               // Actualizar city a Tokyo en el elemento cuyo id es home, y eliminar el subcampo zip
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • Descripción de la interfaz:
    • Cuando el segundo parámetro es { $identifier_key, $identifier_value }, elimina por completo el elemento coincidente del object_array (si coinciden varios, se eliminan todos los elementos coincidentes); content solo puede contener estos dos campos.
    • Los requisitos de $identifier_key y$identifier_value son los mismos que en updateProperty.
    • Si la propiedad aún no está definida, el servidor devuelve un error (55004); si el usuario actual no tiene valor para esa propiedad o no hay ningún elemento coincidente, el servidor ignora esta solicitud y devuelve code=0; si coinciden varios elementos, se eliminan todos los elementos coincidentes.
  • Ejemplo de llamada:

              
               // Eliminar el elemento cuyo id es office
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

Eliminar propiedades del usuario

Definición de la interfaz

• deleteProperty(key, completion)
  • Descripción de la interfaz:
    • Eliminar todo el contenido de valores de una determinada propiedad del usuario.
    • Si esta propiedad del usuario no existía previamente, se ignorará directamente.

Ejemplo de llamada

              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            

Configurar el tiempo de espera de la sesión

Definición de la interfaz

• setSessionTimeout(time)
  • Descripción de la interfaz:
    • Configurar el tiempo de espera de la sesión. Cuando la página pasa a segundo plano, se inicia el conteo del tiempo de espera de la sesión. Si se supera el tiempo configurado (predeterminado: 30 minutos), la sesión finalizará.

Ejemplo de llamada

              
               window.MAInterface.setSessionTimeout(60)

            

Configurar el tiempo de permanencia en la página

Definición de la interfaz

• setPageStayTime(time)
  • Descripción de la interfaz:
    • Configurar la duración del tiempo de permanencia en la página.
    • El conteo se inicia tras acceder a la página. Si el usuario permanece en la página durante time segundos sin salir, se reportará este evento.
    • De forma predeterminada, se reporta en 6 puntos de tiempo: 5 segundos, 30 segundos, 60 segundos, 2 minutos, 5 minutos y 10 minutos. Los desarrolladores pueden llamar a esta interfaz para añadir más puntos de tiempo

Ejemplo de llamada

              
               window.MAInterface.setPageStayTime(60)

            

Reportar eventos

Si un evento no existe, se reporta directamente y el backend creará automáticamente el evento

Definición de la interfaz

• onEvent(event)
  • Descripción de la interfaz:
    • Reportar un evento
  • Descripción de parámetros
    • event: el evento que se va a reportar. name es el nombre del evento y properties es la información de propiedades del evento, donde la clave es el nombre de la propiedad y el valor es el valor de la propiedad

Ejemplo de llamada

              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)