Guide d'intégration de la version Extension Chrome du SDK Web (pour V3)

Remarque : Ce document sert de guide d'intégration standard pour le SDK Web MTpush dans l'environnement d'extension Chrome (Manifest V3), applicable uniquement aux versions de navigateur prenant en charge l'architecture d'extension V3.

1. Présentation du produit

Le SDK Web MTpush - Version Extension Chrome est un outil d'intégration push conçu pour les développeurs sur la base de l'extension Chrome (Manifest V3). Il exploite les capacités de notification système du navigateur Chrome et le mécanisme de connexion persistante du Service Worker pour fournir des services de notification push stables et efficaces pour les extensions.

Ce SDK prend uniquement en charge les navigateurs Chrome et les navigateurs basés sur Chromium (tels que Edge Chromium), et repose sur l'environnement d'exécution de l'extension du navigateur. Aucune autorisation supplémentaire de l'utilisateur n'est requise ; l'extension peut recevoir des notifications push après l'initialisation.

📦 Fonctionnalités clés

• Notifications au niveau système : Affichez les messages push directement via le centre de notifications du navigateur
• Intégration au niveau de l'extension : Adapté à l'architecture des extensions Chrome, avec abonnement automatique et sans perception utilisateur
• Accès léger : API unifiée pour une initialisation rapide et la réception des messages
• Prise en charge des messages personnalisés : Ciblage flexible des utilisateurs via des tags, alias, etc.

📌 Scénarios d'application

• Envoi de rappels, de notifications marketing, de mises à jour et autres notifications aux utilisateurs de l'extension
• Livraison en temps réel d'informations importantes pour les utilisateurs, telles que le statut logistique et les messages d'activité
• Création d'extensions utilitaires pour navigateur avec capacités de messagerie

2. Contenu du package compressé SDK

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // Fichier principal du SDK
│   ├── swExtension.min.x.x.x.js         // Fichier Service Worker
│   └── push-demo                        // Projet exemple d'extension Chrome

            

3. Processus d'intégration

1. Obtenir les informations de l'application

Créez une nouvelle application dans la console EngageLab. Après création, le système générera automatiquement une AppKey pour identifier l'application. Pour plus de détails : Document Paramètres de l'Application

2. Intégrer l'ID de l'extension

• Récupérez l'ID de votre extension Chrome ;
• Connectez-vous à la console EngageLab WebPush, allez dans [Paramètres d'intégration] - [Intégration Extension Chrome], et renseignez le nom et l'ID de l'extension.

Schéma :

3. Accès au SDK

Étape 1 : Téléchargez le SDK et configurez l'extension

Configurez les éléments suivants dans 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"
  }
}

            

Après avoir intégré webSdkExtension.min.x.x.x.js, vous pouvez appeler les méthodes du SDK via window.MTpushInterfaceExtension.

Étape 2 : Générer le user_str

Il est recommandé d'utiliser l'empreinte du navigateur pour générer un user_str unique afin d'éviter l'enregistrement d'utilisateurs invalides :

              
              // Omission : Code de collecte d'empreinte Canvas, WebGL, extension (inchangé)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

Étape 3 : Initialiser le SDK

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // AppKey générée par la console
    user_str: '',    // Empreinte du navigateur ou identifiant unique de l'utilisateur connecté
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('Initialisation du SDK réussie :', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('Échec de l'initialisation du SDK :', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('Message push reçu :', message.data);
      break;
  }
});

            

MTPUSH_ON_MSG_RECEIVE sera déclenché lorsqu'un message push est reçu, et n'est valable que pour les pages suivantes :

1. Pages nouvellement ouvertes après l'installation de l'extension (ou après son redémarrage) ;
2. Pages actuellement à l'état visible au premier plan.

4. Remarques

1. L'initialisation du SDK doit être effectuée sur une page "nouvellement ouverte après l'installation de l'extension" ; les anciennes pages ne peuvent pas établir de connexion.
2. Si l'extension est désactivée ou supprimée, elle ne pourra plus recevoir de push.
3. Après activation ou rechargement de l'extension, toute page doit être rouverte pour l'initialisation et l'abonnement.
4. Dans un même navigateur, même avec la même AppKey, différentes extensions ou user_str seront considérés comme des utilisateurs différents.
5. L'extension ne nécessite pas d'autorisation utilisateur pour les notifications ; elle s'abonnera automatiquement aux notifications système après une initialisation réussie.

5. Plus d'APIs

Pour plus d'informations sur l'utilisation des interfaces du SDK, veuillez consulter le document officiel : API SDK Web

6. Exécution de l'exemple de démonstration

Le package compressé inclut un projet exemple d'extension Chrome push-demo, qui peut être utilisé pour tester rapidement la fonction push :

1. Remplacez le répertoire lib par le SDK le plus récent ;
2. Configurez le bon appkey et user_str dans init-sdk.js ;
3. Ouvrez chrome://extensions, activez le mode développeur et importez la démo décompressée ;
4. Ouvrez n'importe quelle page web pour terminer le processus d'initialisation et d'abonnement ;
5. Connectez-vous à la console EngageLab et envoyez des messages de test ;
6. Cliquez sur l'icône Push en bas à droite de la page pour voir le regid, l'historique des push et définir des tags/alias ;
7. Si Chrome retourne une erreur de type "session timeout", l'extension se réabonnera automatiquement.