Web SDK Chrome Extension Version 統合ガイド（V3向け）

注記: このドキュメントは、Chrome拡張機能（Manifest V3）環境におけるMTpush Web SDKの標準的な統合ガイドであり、V3拡張機能アーキテクチャをサポートするブラウザバージョンにのみ適用されます。

1. 製品紹介

MTpush Web SDK - Chrome Extension Versionは、Chrome拡張機能（Manifest V3）を基盤として開発者向けに設計されたプッシュ統合ツールです。Chromeブラウザのシステム通知機能とService Workerの永続的な接続メカニズムを活用し、拡張機能に安定的かつ効率的なプッシュサービスを提供します。

このSDKはChromeブラウザとChromiumベースのブラウザ（Edge Chromiumなど） のみをサポートし、ブラウザの拡張機能ランタイム環境に依存しています。追加のユーザー認可は必要ありません。初期化後、拡張機能はプッシュ通知を受信できるようになります。

📦 主な機能

• システムレベルの通知: ブラウザの通知センターを通じて直接プッシュメッセージを表示
• 拡張機能レベルの統合: Chrome拡張機能アーキテクチャに適応し、自動的にサブスクリプションを行い、ユーザーに感知されません
• 軽量なアクセス: 統一されたAPIにより、クイックに初期化とメッセージ受信が可能
• カスタムメッセージのサポート: タグ、エイリアスなどを通じて柔軟にユーザーをターゲティング

📌 アプリケーションシナリオ

• 拡張機能ユーザーにリマインダー、マーケティング、更新情報などの通知をプッシュ
• 物流状況、イベントメッセージなど、ユーザーが関心を持つ情報をリアルタイムで配信
• メッセージング機能を備えたブラウザユーティリティ拡張機能の構築

2. SDK圧縮パッケージの内容

              
              webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│   ├── webSdkExtension.min.x.x.x.js     // メインSDKファイル
│   ├── swExtension.min.x.x.x.js         // Service Workerファイル
│   └── push-demo                        // Chrome拡張機能サンプルプロジェクト

            

3. 統合手順

1. アプリケーション情報の取得

EngageLabコンソールで新しいアプリケーションを作成します。作成が成功すると、システムは自動的にアプリケーションを識別するためのAppKeyを生成します。 詳細: アプリケーション設定ドキュメント

2. 拡張機能IDの統合

• 自分のChrome拡張機能の拡張機能IDを取得します。
• EngageLab WebPushコンソールにログインし、[統合設定] - [Chrome拡張機能統合]に移動し、拡張機能名と拡張機能IDを入力します。

模式図:

3. SDKアクセス

ステップ1: SDKをダウンロードし、拡張機能を設定する

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"
  }
}

            

webSdkExtension.min.x.x.x.jsを導入した後、window.MTpushInterfaceExtensionを通じてSDKメソッドを呼び出すことができます。

ステップ2: user_strを生成する

無効なユーザー登録を防ぐため、ブラウザのフィンガープリントを使用して一意のuser_strを生成することを推奨します:

              
              // 省略: Canvas、WebGL、拡張機能のフィンガープリント収集コード（変更なし）
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            

ステップ3: SDKを初期化する

              
              if (window.MTpushInterfaceExtension) {
  window.MTpushInterfaceExtension.initSdk({
    appkey: '',      // コンソールで生成されたAppKey
    user_str: '',    // ブラウザのフィンガープリントまたはログインユーザーの一意の識別子
  });
}

chrome.runtime.onMessage.addListener((message) => {
  switch (message.type) {
    case 'MTPUSH_INIT_SDK_SUCCESS':
      console.log('SDKの初期化が成功しました:', message.data);
      break;
    case 'MTPUSH_INIT_SDK_FAIL':
      console.log('SDKの初期化が失敗しました:', message.data);
      break;
    case 'MTPUSH_ON_MSG_RECEIVE':
      console.log('プッシュメッセージを受信しました:', message.data);
      break;
  }
});

            

プッシュメッセージを受信するとMTPUSH_ON_MSG_RECEIVEがトリガーされます。これは以下のページに対してのみ有効です:

1. 拡張機能をインストールした後（または拡張機能を再起動した後）に新しく開かれたページ
2. 現在フォアグラウンドで表示されている状態のページ

4. 注意事項

1. SDKの初期化は、「拡張機能をインストールした後に新しく開かれた」ページで実行する必要があります。古いページでは接続を確立できません。
2. 拡張機能が無効にされたり削除されたりした場合、どのようなプッシュも受信できなくなります。
3. 拡張機能を有効にしたりリロードしたりした後は、初期化とサブスクリプションを行うために必ずページを再開する必要があります。
4. 同じブラウザ内で、同じAppKeyであっても、異なる拡張機能またはuser_strは異なるユーザーとして扱われます。
5. 拡張機能は通知権限のユーザー認可を必要としません。初期化が成功すると自動的にシステム通知をサブスクライブするようになります。

5. その他のAPI

SDKインターフェースの詳細な使用方法については、公式ドキュメントを参照してください: Web SDK API

6. デモ例の実行

圧縮パッケージにはChrome拡張機能のサンプルプロジェクトpush-demoが含まれており、これを使用してプッシュ機能のクイックテストを行うことができます:

1. libディレクトリを最新のSDKに置き換えます。
2. init-sdk.jsで正しいappkeyとuser_strを設定します。
3. chrome://extensionsを開き、開発者モードを有効にして、解凍したデモをインポートします。
4. 任意のウェブページを開いて、初期化サブスクリプションプロセスを完了します。
5. EngageLabコンソールにログインし、テストメッセージをプッシュします。
6. ウェブページの右下隅にあるプッシュアイコンをクリックして、regid、プッシュ履歴を表示したり、タグ/エイリアスを設定したりします。
7. Chromeから「セッションタイムアウト」などのエラーが返された場合、拡張機能は自動的に再サブスクリプションを行います。