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 服務域名,集成後的頁面需在該域名下進行測試與調試。web 離線推送不支援本地調試、不支援 http。
  • 訪問 Engagelab WebPush,在【集成設定】-【 網站域名】頁面,填寫 https web 服務域名。

截屏2022-11-29 11.08.16.png

獲取應用信息

需要在 WebPush 控制台上創建應用,創建成功後自動生成 AppKey 用以標識該應用,詳情參考 應用設置文檔。

MA 數據源配置

在 MA 專案-數據來源-添加數據來源-Web,選擇「同時使用 WebPush」,下拉選擇在 WebPush 創建好的應用,並儲存 alt text

SDK 接入

進入 控制台,下載 SDK,在每個頁面接入 js:

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

            
此代碼塊在浮窗中顯示

tips

引入該 js 後,傳入 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); } } });
              
                  //  初始化(開啟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 web 服務域名,集成後的頁面需在該域名下進行測試與調試。

alt text

SDK 接入

每個頁面接入下面 js:

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

            
此代碼塊在浮窗中顯示

引入該 JS 後,就可以使用 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); } } })
              
                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 版本開始支援),至少提供一個,各欄位規則詳見 設置用戶標識。
  • 初始化時不符合規則的欄位會被忽略並在控制台列印告警,其餘合法欄位繼續生效。
  • email、phone 用於用戶身份匹配,不是聯繫方式;觸達用的信箱、手機號碼請使用「設置用戶聯繫方式」(setUserContact)接口設置。

重複初始化與切換 AppKey

開始支援的版本:2.1.0

SDK 初始化後,可以再次調用 init,無需刷新頁面:

  • 傳入相同的 AppKey:SDK 會重新獲取 EUID。同時傳入新的 userIdentity 時,SDK 使用新的用戶標識重新獲取 EUID,適用於同一頁面內登出後切換帳號的場景。
  • 傳入不同的 AppKey:SDK 切換到新 AppKey 對應的 MA 數據源,之後的數據上報到新數據源;切換前產生的數據仍上報到原數據源。
  • 多次調用 init 會按調用順序依次執行,每次調用都會透過 completion 返回結果,請以本次回調結果為準。
  • 僅單獨使用 MA Web SDK 時支援切換 AppKey,「同時使用 WebPush」的接入方式不支援。
// 切換到另一個 MA 數據源 window.MAInterface.init({ appKey: "另一個數據源的 AppKey", completion: (code, msg) => { console.log(code, msg) } })
              
                // 切換到另一個 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) => { })
              
                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) => {})
              
                // 在初始化時,請根據用戶的同意狀態對 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。

Icon Solid Transparent White Qiyu
聯繫銷售