Web SDK統合ガイド

このドキュメントは、MA Web SDKの標準統合ガイドです。

製品説明

MA Web SDKは、データ収集および報告機能を提供し、EUID生成、ユーザー属性設定、イベント報告などのシナリオで使用されます

統合方式の選択

MA Web SDKは2種類の接続方式をサポートしています。WebPushと併用する方式と、MA Web SDKのみを単独で使用する方式です

• WebPushと併用：EngageLab WebPushモジュールを統合する際にMA機能を有効に設定すると、MA SDKが自動的に読み込まれます
• MA Web SDKのみを単独使用：MA SDKのアドレスを単独でウェブサイトに統合して使用します。WebPush機能はありません

WebPushと併用

統合前の準備

• 同時にWebPushモジュールを統合する必要があります
• アクセス可能なHTTPSウェブサービスのドメイン名を準備してください。統合後のページは、このドメイン名の下でテストおよびデバッグする必要があります。WebオフラインプッシュはローカルデバッグおよびHTTPをサポートしていません。
• EngageLab WebPushにアクセスし、[統合設定] - [ウェブサイトドメイン名]ページで、HTTPSウェブサービスのドメイン名を入力してください。

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

WebPushコンソールでアプリケーションを作成する必要があります。作成に成功すると、このアプリケーションを識別するためのAppKeyが自動的に生成されます。詳細については、アプリケーション設定ドキュメントを参照してください。

MAデータソースの設定

MAプロジェクトの「データソース」-「データソースを追加」-「Web」で、「WebPushと併用」を選択し、ドロップダウンからWebPushで作成済みのアプリケーションを選択して保存します

SDKアクセス

コンソールにアクセスし、SDKをダウンロードして、各ページでJavaScriptを読み込みます：

              
              <script type="text/javascript" src="./WebSDK.3.3.4.js"></script>

            

ヒント

このJavaScriptを読み込んだ後、maOpenプロパティにtrueを渡してMA構成を有効にすると、MAの関連APIや機能を使用できるようになります

SDK初期化

              
                  //  初期化（MAを有効化）
  MTpushInterface.init({
    appkey: "", // 必須。詳細は上記「アプリケーション情報の取得」を参照
    user_str: "adminDemo", // 必須。ユーザーを識別するためのユーザー識別子
    swUrl: "url", //デフォルトは "/sw.min." + sdkEnv.version + ".js"。この設定項目はserver workerファイルのアドレスで、ドメインは現在のドメインである必要があり、パスによってserver workerのスコープが決まります。
    debugMode: true,// debugモードを有効にするかどうかを設定します。trueの場合はより多くのログ情報を出力します。falseの場合はw、eレベルのログのみ出力します。
    channel: "default-channel",// チャネル名。デフォルト値：default-channel
    appName: "string",// ウェブサイト名の設定に使用し、報告に使用されます
    maOpen: true, //スイッチをオンにして、MA機能を有効にします
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },//MAの初期化と同時にユーザー識別を設定します。3.3.4バージョンから対応。ログイン会員のみにMAサービスを提供する企業に適用
    maDataCollectionEnabled: false, //MAデータ収集の初期状態。渡さない場合はデフォルトで有効。WebPush SDK 3.3.9から対応
    maCompletion: (code, msg) => {//MA初期化コールバック
                if (code === 0) {
                    console.log("✅MA SDK 初期化成功！");
                } else {
                    console.error("❌MA SDK 初期化失敗：", msg);
                }
    }
  });

            

データ収集スイッチ（WebPushと併用）

対応開始バージョン：MA Web SDK 2.2.0、WebPush SDK 3.3.9

• MTpushInterface.initで初期化する際は、ユーザーの同意状態に応じてmaDataCollectionEnabledに動的に値を渡してください。WebPush SDKはこの値をそのままMA SDKに渡します。設定を固定値で書かないよう注意してください。初期化のたびに状態が固定値にリセットされてしまいます
• ユーザーのデータ収集状態が変化した場合は、maCompletionコールバックが呼び出された後にwindow.MAInterface.setDataCollectionEnabled(true/false)を呼び出してください。maCompletionはMA SDKが利用可能になったことを示すシグナルであり、それより前はwindow.MAInterfaceがまだ読み込まれていない可能性があります。
• 無効期間中も、WebPushプッシュの配信とクリックは引き続き可能ですが、プッシュクリックのコンバージョン帰属は集計されなくなります。

詳細はデータ収集スイッチを参照してください。

MA Web SDKのみを単独使用

MAデータソースの設定

MAプロジェクトの「データソース」-「データソースを追加」-「Web」で、「WebPushと併用するかどうか」に「使用しない」を選択し、データソース名とウェブサイトドメイン名を入力して保存すると、WebデータソースのAppKey情報が取得できます

• アクセス可能なHTTPSウェブサービスのドメイン名を準備してください。統合後のページは、このドメイン名の下でテストおよびデバッグする必要があります。

SDKアクセス

各ページで以下のJavaScriptを読み込みます：

              
              <script type="text/javascript" src="https://websdk-res.engagelab.com/lib/ma-web.min.js"></script>
        

            

このJavaScriptを読み込んだ後、Window上のグローバルオブジェクトMAInterfaceを使用できます。

特記事項：このリンクを直接使用してください。このファイルをプロジェクトにダウンロードしないでください。ダウンロードした場合、弊社がデータ構造やAPIインターフェースを更新した後に統計が無効になる可能性があります。

SDK初期化

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // 必須。詳細は上記「アプリケーション情報の取得」を参照
    debugMode: true,
    channel: "default-channel22",// チャネル名。デフォルト値：default-channel
    appName: "EngageLab-MA test-appName", //ウェブサイト名。デバイス属性およびイベント報告のapp_nameの設定に使用
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, //MAの初期化と同時にユーザー識別を設定します。user_id、anonymous_id、email、phoneに対応
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK 初期化成功！");
        } else {
            console.error("❌ SDK 初期化失敗：", msg);
        }
    }
  })
        

            

ユーザー識別の説明

• userIdentityは、user_id、anonymous_id、email、phoneの4種類のユーザー識別をサポートしています（email、phoneは2.1.0バージョンから対応）。少なくとも1つを指定してください。各フィールドのルールの詳細はユーザー識別を設定するを参照してください。
• 初期化時にルールに適合しないフィールドは無視され、コンソールに警告が出力されます。その他の有効なフィールドは引き続き有効です。
• email、phoneはユーザー身元のマッチングに使用されるものであり、連絡先ではありません。メッセージ送信に使用するメールアドレスや電話番号は、「ユーザー連絡先を設定する」（setUserContact）インターフェースで設定してください。

再初期化とAppKeyの切り替え

対応開始バージョン：2.1.0

SDKの初期化後、ページを更新せずに再度initを呼び出すことができます：

• 同じAppKeyを渡す場合：SDKはEUIDを再取得します。同時に新しいuserIdentityを渡した場合、SDKは新しいユーザー識別でEUIDを再取得します。同一ページ内でログアウト後にアカウントを切り替えるシナリオに適しています。
• 異なるAppKeyを渡す場合：SDKは新しいAppKeyに対応するMAデータソースに切り替わり、以降のデータは新しいデータソースに報告されます。切り替え前に発生したデータは引き続き元のデータソースに報告されます。
• initを複数回呼び出した場合は呼び出し順に順次実行され、各呼び出しの結果はcompletionで返されます。今回のコールバック結果を基準にしてください。
• AppKeyの切り替えはMA Web SDKのみを単独使用する場合にのみサポートされます。「WebPushと併用」の接続方式ではサポートされません。

              
                // 別のMAデータソースに切り替える
  window.MAInterface.init({
    appKey: "別のデータソースのAppKey",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

チャネル連絡先 ID を設定する

対応開始バージョン：2.1.0

WebPushまたはサードパーティPushチャネルにRIDまたはTokenを設定する必要がある場合は、SDKの初期化成功後に呼び出してください：

              
                window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message) => { })

            

• channelId：MAコンソールで設定したPushチャネルID。0より大きい値である必要があります。
• values：RIDまたはTokenの配列。配列および要素はいずれも空にできません。RIDまたはTokenが変化した場合は、再度インターフェースを呼び出して更新する必要があります。

詳細はチャネル連絡先 ID を設定するを参照してください。

データ収集スイッチ

対応開始バージョン：2.2.0

アプリケーションは、ユーザーの同意結果に応じてMA SDKがデータを収集するかどうかを制御します。無効にすると、SDKはイベント、ユーザー属性、UTM、デバイス情報を生成・キャッシュ・報告しません。初期化、ユーザー識別、連絡先、チャネル連絡先IDは通常どおり使用できます。状態はブラウザのローカルに保存され、更新後も保持されます。

              
                // 初期化時は、ユーザーの同意状態に応じてdataCollectionEnabledに動的に値を渡してください。設定を固定値で書かないでください。初期化のたびに状態が固定値にリセットされてしまいます
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // 渡さない場合はデフォルトで有効
    completion: (code, msg) => {}
  })

  // ユーザーが同意 / 同意を撤回した後
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• 設定する値が現在の状態と同じ場合は切り替え処理は発生しないため、ページ読み込みごとにユーザーの選択を同期しても追加の影響はありません。
• 無効期間中にユーザー属性インターフェースを呼び出すと、completionは-8を返します。イベント、UTMなどのコールバックのないインターフェースは静かに破棄されます。
• ストレージが縮退（localStorageが利用不可）している場合、スイッチの状態は現在のタブでのみ有効です。

詳細はデータ収集スイッチを参照してください。

その他のAPIインターフェース

他のAPIの使用方法については、インターフェースドキュメント：Web SDK APIを参照してください。