Web SDK Chrome Extension Version Integration Guide (for V3)

Note: This document serves as the standard integration guide for the MTpush Web SDK in the Chrome extension (Manifest V3) environment, applicable only to browser versions supporting the V3 extension architecture.

1. Product Introduction

The MTpush Web SDK - Chrome Extension Version is a push integration tool designed for developers based on the Chrome extension (Manifest V3). It leverages the Chrome browser's system notification capabilities and Service Worker persistent connection mechanism to provide stable and efficient push services for extensions.

This SDK only supports Chrome browsers and Chromium-based browsers (such as Edge Chromium), and relies on the browser's extension runtime environment. No additional user authorization is required; the extension can receive push notifications after initialization.

📦 Key Features

• System-level notifications: Display push messages directly through the browser notification center
• Extension-level integration: Adapted to the Chrome extension architecture, with automatic subscription and no user perception
• Lightweight access: Unified API for quick initialization and message reception
• Support for custom messages: Flexible targeting of users via tags, aliases, etc.

📌 Application Scenarios

• Pushing reminders, marketing, updates, and other notifications to extension users
• Real-time delivery of information that users care about, such as logistics status and activity messages
• Building browser utility extensions with messaging capabilities

2. SDK Compressed Package Content

              
              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. Integration Process

1. Obtain Application Information

Create a new application in the EngageLab console. Upon successful creation, the system will automatically generate an AppKey to identify the application. For details: Application Settings Document

2. Integrate Extension ID

• Obtain the extension ID of your Chrome extension;
• Log in to the EngageLab WebPush console, go to [Integration Settings] - [Chrome Extension Integration], and fill in the extension name and extension ID.

Schematic diagram:

3. SDK Access

Step 1: Download the SDK and configure the extension

Configure the following in 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"
  }
}

            

After introducing webSdkExtension.min.x.x.x.js, you can call the SDK methods through window.MTpushInterfaceExtension.

Step 2: Generate user_str

It is recommended to use browser fingerprinting to generate a unique user_str to prevent invalid user registration:

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

            

Step 3: Initialize the 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 will be triggered when a push message is received, and is only valid for the following pages:

1. Pages newly opened after installing the extension (or restarting the extension);
2. Pages currently in the foreground visible state.

4. Notes

1. SDK initialization must be performed on a page "newly opened after installing the extension"; old pages cannot establish a connection.
2. If the extension is disabled or deleted, it will be unable to receive any pushes.
3. After enabling or reloading the extension, any page must be reopened for initialization and subscription.
4. In the same browser, even with the same AppKey, different extensions or user_str will be treated as different users.
5. The extension does not require user authorization for notification permissions; it will automatically subscribe to system notifications after successful initialization.

5. More APIs

For more usage of SDK interfaces, please refer to the official document: Web SDK API

6. Running the Demo Example

The compressed package includes a Chrome extension sample project push-demo, which can be used for quick push function testing:

1. Replace the lib directory with the latest SDK;
2. Configure the correct appkey and user_str in init-sdk.js;
3. Open chrome://extensions, enable developer mode, and import the unzipped demo;
4. Open any webpage at random to complete the initialization subscription process;
5. Log in to the EngageLab console and push test messages;
6. Click the Push icon in the lower-right corner of the webpage to view regid, push records, and set tags/aliases;
7. If Chrome returns an error such as "session timeout", the extension will automatically resubscribe.