API del Web SDK

El SDK obtiene automáticamente las URL de conexión y de envío de estadísticas del centro de datos correspondiente al AppKey, incluidos Fráncfort y Virginia. No es necesario configurar manualmente baseUrl, report_url ni webSocketUrl.

Autenticación

Cuando el desarrollador realiza la inicialización, debe proporcionar la información necesaria. Esta estructura de datos la genera el servidor del desarrollador y se envía al navegador; se utiliza para la inicialización de MTpush, mediante la cual el desarrollador autoriza al navegador a ejecutarse. Los desarrolladores deben garantizar que todos los usuarios que puedan llamar para obtener estos datos sean usuarios legítimos.

Estructura de datos de inicialización

              
              interface MTInitInfo {
  website_push_id: string;
  code: number;
  master_secret: string;
  passwd: string;
  pull: number;
  regid: string;
  sess: string;
  tagalias: number;
  uid: number;
  vapid_pubkey: string;
}

type dataType = {
  code: number,
  content?: string | { code: number; [key: string]: unknown },
  message: string,
};

interface InitType {
  report_url?: string; // Report URL, used for private cloud or custom deployments
  baseUrl?: string; // Server domain; when used together with report_url, the private cloud or custom deployment logic is used
  userLang?: string; // Defaults to navigator.language and must be a language value supported by the browser
  safari_url?: string; // Safari push test field
  appkey: string; // AppKey of the application registered on the EngageLab platform, required
  user_str: string; // Unique user identifier, required
  swUrl?: string; // Default: "/sw" + sdkEnv.prefix
  is_temporary?: "n" | "t"; // Default: "n"
  debugMode?: boolean; // Default: false
  webSocketUrl?: string; // If not provided, baseUrl will be used
  fail?: (data: dataType | undefined) => void; // Initialization failure callback
  success?: (data: dataType | undefined) => void; // Initialization success callback
  webPushcallback?: def;
  canGetInfo?: (d: MTInitInfo) => void;
  custom?: (Callback: () => void) => void; // Callback for custom prompts; call Callback to request notification permission
  maOpen?: boolean; // Whether to enable the ma-sdk module
  maChannel?: string; // Channel name used by ma-sdk; default: default-channel
  appName?: string; // Website name used by ma-sdk for reporting
  userIdentity?: { userId?: string; anonymousId?: string }; // User identity used by ma-sdk
  maCompletion?: (code: number, msg: string) => void; // ma-sdk initialization completion callback
  openUrl?: string; // Redirect link when clicking a notification
  encodeSwUrl?: boolean; // Whether to encode swUrl
  regidSearchPath?: string; // Page path for querying Registration ID
}

            

• Descripción de parámetros:
  • openUrl: URL que se abre al hacer clic en una notificación
    • Si no se especifica URL al enviar la notificación, se usa este valor como enlace de redirección;
    • Si no se define, por defecto se redirige al dominio de integración;
    • En integración multi-dominio, este parámetro permite redirigir a la URL correspondiente;
  • encodeSwUrl: Si se debe codificar swUrl
    • Útil cuando swUrl contiene caracteres especiales (p. ej. @) y el servidor restringe el acceso a esa URL, lo que puede hacer fallar el registro del Service Worker; añadir mecanismo de re-registro y codificar swUrl en los reintentos.
  • regidSearchPath: Ruta de la página para consultar el Registration ID; por defecto /engagelab/regid. Ver Guía de consulta del Registration ID.

Solo se puede registrar un service worker dentro del mismo ámbito (scope). Cuando, al informar de una inicialización correcta, se muestre un error similar a "Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker", se deben comprobar posibles conflictos con otros service workers. Es posible que sea necesario fusionar los service workers o resolver el ámbito (scope) del service worker.

Inicialización del SDK

Descripción de la interfaz

Inicializar la interfaz.

              
              window.MTpushInterface.init(Object:InitType)

            

Descripción de parámetros

• Para obtener más información, consulte Descripción de InitType.
• Descripción de los datos del objeto de callback:

Ejemplo de llamada

              
              const appkey = "your_appkey";
const userStr = "adminDemo";

MTpushInterface.init({
  appkey: appkey,
  user_str: userStr,
  fail(data) {
    console.log("Online push setup failed", data);
  },
  success(data) {
    console.log("Online push setup successful", data);
  },
  webPushcallback(code, tip) {
    console.log("Status code and message", code, tip);
  },
  canGetInfo(data) {
    // RegId is available here, and initialization config data can also be read from data.
    console.log("Obtained RegId", MTpushInterface.getRegistrationID(), data);
    // MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
  },
  custom: (requestPermission) => {
    // For custom prompt settings, call requestPermission during an appropriate user action to request notification permission.
    document.getElementById("subscribe")?.addEventListener("click", () => {
      if (Notification.permission === "default") {
        requestPermission();
      } else if (Notification.permission === "denied") {
        console.log("Notification permission is denied and cannot be requested");
      } else {
        console.log("Notification permission has already been granted");
      }
    });
  },
});

            

Obtener RegistrationID

Descripción de la interfaz

Se debe llamar a esta API para obtener el RegistrationID correspondiente a la cuenta actual. El valor correspondiente solo se devuelve después de que la firma de inicialización sea correcta; de lo contrario, se devuelve una cadena vacía. Este método debe llamarse después de que se active el callback canGetInfo.

              
              window.MTpushInterface.getRegistrationID()

            

Ejemplo de llamada

              
              var rid = window.MTpushInterface.getRegistrationID();

            

Detener push

Se debe llamar a esta API para desconectar la conexión push persistente establecida con el backend y dejar de recibir mensajes push.

              
              window.MTpushInterface.mtPush.stopPush()

            

Monitorización de mensajes push

Descripción de la interfaz

Se recomienda llamar al listener de mensajes antes de la inicialización.

              
              window.MTpushInterface.onMsgReceive(fn)

            

Descripción de parámetros

Ejemplo de llamada

              
              window.MTpushInterface.onMsgReceive(function (res) {
   if(res.type===0){
    // res.data.messages[]
    // res.data.messages[].msg_id
    // res.data.messages[].title
    // res.data.messages[].content
    // res.data.messages[].extras
   }else{
    // res.data.title
   }
});

            

Datos devueltos

Array de mensajes del canal de Engagelab (messages)

Datos de mensajes del canal del sistema

Se admite la interfaz w3c NotificationOptions; para más información, consulte MDN Web Docs.

Comprobar el estado del servicio push

              
              window.MTpushInterface.getPushAuthority()

            

La estructura de datos devuelta es la siguiente:

              
              {
   mtPush: {
     code:1, //1 is successful, -1 is in initialization, 0 is failed
     msg:'success'
   },
   webPush: {
     code:1, // 0 webpush is not available (browser does not support it) 1 is available 2 permission is disabled 3 permission is not confirmed
     msg:'success'
   }
}

            

Códigos de error del objeto WebPush

Los siguientes códigos de estado corresponden a getPushAuthority().webPush.code y webPushcallback(code, tip). Son independientes de los códigos del callback de inicialización fail.

Obtener permisos de notificación del navegador

              
              window.MTpushInterface.getWebPermission()

            

Descripción de parámetros devueltos

• granted : Disponible
• denied : Deshabilitado
• default: Permiso no confirmado

Reporte de mensajes personalizados

Si es necesario realizar estadísticas de mensajes personalizados, utilice las API de reporte personalizado.

Reporte de visualización:

              
              window.MTpushInterface.customDisplayReport('msg_id'); // msg_id es el msg_id del mensaje personalizado

            

Reporte de clic:

              
              window.MTpushInterface.customClickReport('msg_id'); // msg_id es el msg_id del mensaje personalizado

            

Monitorización de desconexión

Descripción de la interfaz

Si se produce una desconexión después de una inicialización correcta, el SDK intentará automáticamente volver a conectarse y firmar.
Se recomienda llamar a este listener de eventos antes de la inicialización y volver a llamar a la inicialización después de recibir este evento.

              
              window.MTpushInterface.mtPush.onDisconnect(fn)

            

Ejemplo de llamada

              
              window.MTpushInterface.mtPush.onDisconnect(function () {
});

            

Cancelar la suscripción del navegador

Cancelar la suscripción a las notificaciones. Este método puede utilizarse cuando no se necesita recibir notificaciones al cerrar sesión en una cuenta o cuando el nivel de privacidad de algunas cuentas es alto.

              
              MTpushInterface.unSubscribe();

            

Establecer TagsAlias

              
              MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });

            

Descripción de parámetros

Descripción de la interfaz

Los desarrolladores pueden establecer tags y alias a través de esta interfaz. Tenga en cuenta que esta interfaz utiliza una lógica de sobrescritura: establecer una cadena vacía eliminará los tags y alias existentes.

Establecer idioma de notificación

MTpushInterface.setLan(lan)

              
              MTpushInterface.setLan(lan, (err) => {
  alert(err ? "Error al establecer el idioma de notificación: " + err : "Idioma de notificación establecido correctamente");
});

            

Descripción de parámetros

Descripción de la interfaz

Los desarrolladores pueden usar esta API para establecer manualmente el idioma de notificación. Una vez establecida correctamente, el SDK guarda el idioma. Si no se pasa userLang durante la siguiente inicialización, se usará primero el idioma guardado localmente.

Visualización múltiple de indicaciones por categoría

              
              window.MTpushInterface.promptPushCategories();

            

Descripción de la interfaz

Tras suscribirse el usuario a las notificaciones push, los desarrolladores pueden mostrar las indicaciones por categoría varias veces según sea necesario. Esto debe llamarse después de que el SDK esté inicializado.

Compatibilidad de callbacks en Safari

A partir del SDK v3.3.8, el canal push se selecciona según el tipo de suscripción actual de Safari. La disponibilidad de los callbacks depende del tipo de suscripción, del estado de la página cuando ocurre el evento y del momento en que se registra el listener:

Los callbacks de la página, la visualización de la notificación del sistema y las estadísticas del servidor son mecanismos independientes. La ausencia de un callback en la página no significa que la notificación no se haya mostrado ni que el servidor no haya registrado datos de entrega, visualización o clic.

Callback de visualización de mensajes push

Descripción de la interfaz

Se recomienda llamar al listener de mensajes antes de la inicialización.

Ejemplo de llamada

              
              window.MTpushInterface.onMsgDisplay((msgData) => {});

            

Descripción de parámetros

Descripción del parámetro de callback de mensajes de notificación msgData:

              
              {
  engagelab_ntf_or_msg: number;
  engagelab_appkey: string;
  engagelab_passwd: string;
  engagelab_uid: number;
  engagelab_m_str: string;
  engagelab_a_str: string;
  type: number;
  title: string;
  content: string;
  msg_id: string;
}

            

Descripción del parámetro de callback de mensajes in-app msgData:

              
              {
  title: string;
  content: string;
  msg_id: string;
  ntf_or_msg: number;
  type: number;
}

            

Estos tipos corresponden a la plantilla estándar de mensajes dentro de la aplicación de la consola, donde type es el número 0. Una plantilla HTML personalizada define sus propios datos de callback.

Nota:

1. En el modo de edición HTML para mensajes in-app, los parámetros de callback title y content son cadenas vacías.
2. Los callbacks de Safari están sujetos a las condiciones de compatibilidad anteriores. Registra el listener antes de inicializar el SDK y asegúrate de que exista una página controlada por el Service Worker cuando ocurra el evento.

Callback de clic de mensajes push

Descripción de la interfaz

Se recomienda llamar al listener de mensajes antes de la inicialización.

Ejemplo de llamada

              
              window.MTpushInterface.onMsgClick((msgData) => {});

            

Descripción de parámetros

Descripción del parámetro de callback de mensajes de notificación msgData:

              
              {
  engagelab_ntf_or_msg: number;
  engagelab_appkey: string;
  engagelab_passwd: string;
  engagelab_uid: number;
  engagelab_m_str: string;
  engagelab_a_str: string;
  type: number;
  title: string;
  content: string;
  msg_id: string;
  target_event: string | null;
  position: string; // Click position, 'msgBody' | Button ID
}

            

Descripción del parámetro de callback de mensajes in-app msgData:

              
              {
  position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
  msg_id: number;
  title: string;
  content: string;
  extras: object | null;
  ntf_or_msg: number;
  strategy: object | null;
  target_event: unknown[];
  type: number;
  icon: string;
}

            

Nota:

1. En el modo de edición HTML para mensajes in-app, el valor de position lo determina el desarrollador y los parámetros de callback title y content son cadenas vacías.
2. Los callbacks de Safari están sujetos a las condiciones de compatibilidad anteriores. Si ninguna página puede recibir mensajes cuando se hace clic en la notificación, abrir la página de destino no reproduce el callback de clic.

Código de error

La tabla siguiente muestra los valores externos de data.code en los callbacks de inicialización. Los fallos específicos del servidor aparecen en data.content.code. Un mismo número puede tener significados diferentes en estos dos campos.

Códigos de error de inicialización del servidor

Si falla la inicialización, el SDK devuelve un código externo mediante fail, por ejemplo data.code === 1003. Cuando data.content es un objeto, data.content.code contiene el código específico del servidor y data.content.desc contiene la descripción, si está disponible.

Validación de inicialización y errores del servicio

Por ejemplo, data.code === 1003 junto con data.content.code === 4008 indica que la inicialización falló porque caducó el servicio VIP. Revise tanto el code externo como el motivo específico en content.

Códigos transmitidos por el servicio de registro

Cuando la inicialización requiere registrar al usuario, el servidor también transmite los códigos del servicio de registro. La tabla enumera las correspondencias de compatibilidad conservadas por el servidor; las respuestas concretas dependen de la versión del servicio de registro.

Por ejemplo, el valor externo data.code === 1008 indica una restricción regional, mientras que el código externo 1003 con el valor interno data.content.code === 1008 indica que la aplicación no existe.

Fallos de autenticación

Si falla la API de autenticación, el SDK copia message de la respuesta en la cadena data.content. No devuelve el code original como content.code. Consulte los códigos originales siguientes en la respuesta de la solicitud de autenticación (/v1/auth) desde las herramientas de desarrollo del navegador.

Notificación de suscripción caducada

El servidor envía 4107 (subscribe expired) mediante el comando WebSocket expired cuando caduca la suscripción push del navegador. Es una notificación del sistema posterior a la inicialización; no es un error del callback de inicialización fail. El listener mtPush.onExpired del SDK recibe la notificación, pero su callback no incluye el código de error.