Web SDK Integration Guide

This document is the standard integration guide for the MA Web SDK.

Product Description

The MA Web SDK provides data collection and reporting capabilities for scenarios such as EUID generation, user property setting, and event reporting.

Integration Options

The MA Web SDK supports two integration modes: together with WebPush, or the MA Web SDK on its own.

• Together with WebPush: enable the MA feature when integrating the EngageLab WebPush module, and the MA SDK is loaded automatically.
• MA Web SDK only: integrate the MA SDK script directly into your website, without WebPush features.

Together with WebPush

Preparations before Integration

• You also need to integrate the WebPush module.
• Prepare an accessible HTTPS web service domain. After integration, pages must be tested and debugged under this domain. Web offline push does not support local debugging or HTTP.
• Go to EngageLab WebPush and fill in the HTTPS web service domain on the [Integration Settings] - [Website Domain] page.

Obtain Application Information

Create an application in the WebPush console. An AppKey is generated automatically to identify the application. For details, see Application Settings.

MA Data Source Configuration

In the MA project, go to Data Sources - Add Data Source - Web, select "Use with WebPush", choose the application created in WebPush from the drop-down list, and save.

SDK Access

Go to the Console, download the SDK, and include the script on every page:

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

            

Tips

After importing this script, pass maOpen: true to enable the MA configuration. You can then use the MA APIs and features.

SDK Initialization

              
                  //  Initialization (enable MA)
  MTpushInterface.init({
    appkey: "", // Required, see "Obtain Application Information" above
    user_str: "adminDemo", // Required, user identifier used to mark the user
    swUrl: "url", // Default: "/sw.min." + sdkEnv.version + ".js". The service worker file address. The domain must be the current domain, and the path determines the service worker scope.
    debugMode: true,// Whether to enable debug mode. true prints more logs; false only outputs logs of level w and e.
    channel: "default-channel",// Channel name, default: default-channel
    appName: "string",// Website name, used for reporting
    maOpen: true, // Enable the MA feature
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123" },// Set the user identity while initializing MA. Supported since 3.3.4, for businesses that provide MA services only to logged-in members
    maDataCollectionEnabled: false, // Initial MA data collection state; enabled by default when omitted. Supported since WebPush SDK 3.3.9
    maCompletion: (code, msg) => {// MA initialization callback
                if (code === 0) {
                    console.log("✅MA SDK initialized successfully!");
                } else {
                    console.error("❌MA SDK initialization failed:", msg);
                }
    }
  });

            

Data Collection Switch (together with WebPush)

Supported since: MA Web SDK 2.2.0, WebPush SDK 3.3.9

• When calling MTpushInterface.init, pass maDataCollectionEnabled dynamically according to the user's consent state. The WebPush SDK passes it through to the MA SDK. Do not hardcode the value; otherwise every initialization resets the state to the hardcoded value.
• When the user's data collection state changes, call window.MAInterface.setDataCollectionEnabled(true/false) after the maCompletion callback has fired. maCompletion signals that the MA SDK is available; before it, window.MAInterface may not be loaded yet.
• While collection is disabled, WebPush notifications can still be delivered and clicked, but conversion attribution for notification clicks is no longer counted.

For details, see Data Collection Switch.

MA Web SDK Only

MA Data Source Configuration

In the MA project, go to Data Sources - Add Data Source - Web, select "Not used" under "Use with WebPush", enter the data source name and website domain, and save. You then get the AppKey of the Web data source.

• Prepare an accessible HTTPS web service domain. After integration, pages must be tested and debugged under this domain.

SDK Access

Include the following script on every page:

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

            

After importing this script, the global object MAInterface is available on window.

Note: Use this link directly. Do not download the file into your project; otherwise statistics may break after we update data structures or APIs.

SDK Initialization

              
                window.MAInterface.init({
    appKey: "7ccf93e0950b5e22f4ca2124",  // Required, see "Obtain Application Information" above
    debugMode: true,
    channel: "default-channel22",// Channel name, default: default-channel
    appName: "EngageLab-MA test-appName", // Website name, used as app_name in device properties and event reporting
    userIdentity: { user_id: "1234567890", anonymous_id: "anonymous123", email: "user@example.com", phone: "+8613800000000" }, // Set the user identity while initializing MA. Supports user_id, anonymous_id, email, and phone
      completion: (code, msg) => {
        if (code === 0) {
            console.log("✅ SDK initialized successfully!");
        } else {
            console.error("❌ SDK initialization failed:", msg);
        }
    }
  })
        

            

About User Identity

• userIdentity supports 4 identity types: user_id, anonymous_id, email, and phone (email and phone are supported since 2.1.0). Provide at least one. For the rules of each field, see Set User Identity.
• Fields that do not meet the rules at initialization are ignored with a console warning; the remaining valid fields still take effect.
• email and phone are used for user identity matching, not as contact information. For the email address and phone number used for messaging, use the "Set User Contact Information" (setUserContact) API.

Re-initialization and Switching AppKey

Supported since: 2.1.0

After the SDK is initialized, you can call init again without refreshing the page:

• Same AppKey: the SDK re-fetches the EUID. If a new userIdentity is passed at the same time, the SDK re-fetches the EUID with the new identity. This suits switching accounts after logging out within the same page.
• Different AppKey: the SDK switches to the MA data source of the new AppKey, and subsequent data is reported to the new data source. Data generated before the switch is still reported to the original data source.
• Multiple init calls are executed in call order, and each call returns its result through completion. Use the result of the corresponding callback.
• Switching AppKey is supported only when using the MA Web SDK on its own; it is not supported in the "together with WebPush" integration mode.

              
                // Switch to another MA data source
  window.MAInterface.init({
    appKey: "AppKey of another data source",
    completion: (code, msg) => {
      console.log(code, msg)
    }
  })

            

Set Channel Contact ID

Supported since: 2.1.0

To set the RID or token for WebPush or a third-party push channel, call the following after the SDK is initialized successfully:

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

            

• channelId: the ID of the push channel configured in the MA console; must be greater than 0.
• values: an array of RIDs or tokens; neither the array nor its elements can be empty. Call the API again when the RID or token changes.

For details, see Set Channel Contact ID.

Data Collection Switch

Supported since: 2.2.0

The application controls whether the MA SDK collects data according to the user's consent. When disabled, the SDK does not generate, cache, or report events, user properties, UTM, or device information; initialization, user identity, contact information, and channel contact ID still work. The state is stored locally in the browser and persists across page refreshes.

              
                // Pass dataCollectionEnabled dynamically according to the user's consent state at initialization. Do not hardcode it; otherwise every initialization resets the state to the hardcoded value
  window.MAInterface.init({
    appKey: "your appKey",
    dataCollectionEnabled: false, // Enabled by default when omitted
    completion: (code, msg) => {}
  })

  // After the user grants / withdraws consent
  window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {})
  window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {})

            

• Setting the same value as the current state does not trigger a switch, so syncing the user's choice on every page load has no side effects.
• While collection is disabled, user property APIs return -8 in completion; APIs without callbacks, such as events and UTM, drop the data silently.
• When storage is degraded (localStorage unavailable), the switch state is effective only in the current tab.

For details, see Data Collection Switch.

More APIs

For other APIs, see the API reference: Web SDK API.