Guía de integración de la versión de extensión de Chrome del Web SDK (para V3)

Nota: Este documento sirve como guía de integración estándar del Web SDK de MTpush en el entorno de extensiones de Chrome (Manifest V3), aplicable únicamente a versiones de navegador que admitan la arquitectura de extensiones V3.

1. Introducción del producto

El Web SDK de MTpush - versión de extensión de Chrome es una herramienta de integración de push diseñada para desarrolladores basada en extensiones de Chrome (Manifest V3). Aprovecha las capacidades de notificaciones del sistema del navegador Chrome y el mecanismo de conexión persistente de Service Worker para proporcionar servicios push estables y eficientes para extensiones.

Este SDK solo admite navegadores Chrome y navegadores basados en Chromium (como Edge Chromium) y depende del entorno de ejecución de extensiones del navegador. No se requiere ninguna autorización adicional del usuario; la extensión puede recibir notificaciones push tras la inicialización.

📦 Características principales

• Notificaciones a nivel del sistema: mostrar mensajes push directamente a través del centro de notificaciones del navegador
• Integración a nivel de extensión: adaptada a la arquitectura de extensiones de Chrome, con suscripción automática y sin percepción por parte del usuario
• Acceso ligero: API unificada para inicialización rápida y recepción de mensajes
• Compatibilidad con mensajes personalizados: segmentación flexible de usuarios mediante etiquetas, alias, etc.

📌 Escenarios de aplicación

• Envío de recordatorios, marketing, actualizaciones y otras notificaciones a usuarios de la extensión
• Entrega en tiempo real de información de interés para el usuario, como el estado logístico y mensajes de actividad
• Creación de extensiones de utilidades del navegador con capacidades de mensajería

2. Contenido del paquete comprimido del SDK

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // Main SDK file
│   ├── swExtension.min.x.x.x.js         // Service Worker file
│   └── push-demo                        // Chrome extension sample project

            

3. Proceso de integración

1. Obtener información de la aplicación

Crear una nueva aplicación en la consola de EngageLab. Tras crearse correctamente, el sistema generará automáticamente un AppKey para identificar la aplicación.
Para más información: Documento de configuración de la aplicación

2. Integrar el ID de la extensión

• Obtener el ID de la extensión de su extensión de Chrome;
• Iniciar sesión en la consola WebPush de EngageLab, ir a [Integration Settings (Ajustes de integración)] - [Chrome Extension Integration (Integración de extensión de Chrome)] y completar el nombre de la extensión y el ID de la extensión.

Diagrama esquemático:

3. Acceso al SDK

Paso 1: Descargar el SDK y configurar la extensión

Configurar lo siguiente en manifest.json:

              
              {
  "manifest_version": 3,
  "permissions": [
    "storage",
    "notifications",
    "tabs",
    "activeTab"
  ],
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["webSdkExtension.min.x.x.x.js"],
      "run_at": "document_end"
    },
    {
      "matches": ["<all_urls>"],
      "js": ["init-sdk.js"],
      "run_at": "document_end"
    }
  ],
  "background": {
    "service_worker": "swExtension.min.x.x.x.js"
  }
}

            

Tras incorporar webSdkExtension.min.x.x.x.js, se pueden llamar los métodos del SDK mediante window.MTpushInterfaceExtension.

Paso 2: Generar user_str

Se recomienda utilizar la huella digital del navegador para generar un user_str único y evitar el registro de usuarios no válidos:

              
              // Omitted: Canvas, WebGL, extension fingerprint collection code (remains unchanged)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

Paso 3: Inicializar el SDK

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // AppKey generated by the console
    user_str: '',    // Browser fingerprint or unique identifier of the logged-in user
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('SDK initialization successful:', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('SDK initialization failed:', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('Push message received:', message.data);
      break;
  }
});

            

MTPUSH_ON_MSG_RECEIVE se activará cuando se reciba un mensaje push y solo es válido para las siguientes páginas:

1. Páginas abiertas recientemente tras instalar la extensión (o reiniciar la extensión);
2. Páginas que se encuentren actualmente en estado visible en primer plano.

4. Notas

1. La inicialización del SDK debe realizarse en una página «abierta recientemente tras instalar la extensión»; las páginas antiguas no pueden establecer una conexión.
2. Si la extensión se deshabilita o se elimina, no podrá recibir ningún push.
3. Tras habilitar o recargar la extensión, se debe volver a abrir cualquier página para la inicialización y la suscripción.
4. En el mismo navegador, incluso con el mismo AppKey, extensiones diferentes o user_str distintos se tratarán como usuarios diferentes.
5. La extensión no requiere autorización del usuario para los permisos de notificación; se suscribirá automáticamente a las notificaciones del sistema tras una inicialización correcta.

5. Más API

Para obtener más información sobre el uso de las interfaces del SDK, consulte el documento oficial: API del Web SDK

6. Ejecutar el ejemplo de demo

El paquete comprimido incluye un proyecto de ejemplo de extensión de Chrome push-demo, que se puede utilizar para realizar pruebas rápidas de la función push:

1. Sustituir el directorio lib por el SDK más reciente;
2. Configurar el appkey y el user_str correctos en init-sdk.js;
3. Abrir chrome://extensions, habilitar el modo de desarrollador e importar la demo descomprimida;
4. Abrir cualquier página web aleatoria para completar el proceso de inicialización y suscripción;
5. Iniciar sesión en la consola de EngageLab y enviar mensajes de prueba;
6. Hacer clic en el icono de Push en la esquina inferior derecha de la página web para ver regid, registros de push y establecer etiquetas/alias;
7. Si Chrome devuelve un error como «session timeout», la extensión se volverá a suscribir automáticamente.