Logo Site EngageLab Full Black
Contact Sales

API Guide

Set User Identity

Supported Versions

email and phone identities are supported since: 2.1.0

Interface Definition

  • identifyAccount(user);
    • Description:
      • Set the user identity, such as a membership card number.
    • Parameters
      • identity: the user identity object. Supports 4 keys: user_id, anonymous_id, email, and phone. Provide at least one; not all are required
      • completion: the callback
    • Identity rules
      • user_id: non-empty after trimming, up to 255 characters, cannot be 0, null, undefined, or nan (case-insensitive)
      • anonymous_id: non-empty after trimming, up to 256 characters
      • email: the user's email address, non-empty after trimming, up to 256 characters, must be a valid email format such as user@example.com
      • phone: the user's phone number in E.164 format including the country or region code, such as +8613800000000
      • If any field violates the rules, no request is sent, completion returns -1, and message gives the specific reason

Call Example

let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}} window.MAInterface.identifyAccount(user)
              
                  let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
    window.MAInterface.identifyAccount(user)

            
This code block in the floating window

Here email and phone are used for user identity matching and may return a new EUID. They are not interchangeable with the contact information set through "Set User Contact Information" (setUserContact).

Get EUID

Interface Definition

  • + EUID()
    • Description:
      • Get the EUID of EngageLab MA

Call Example

window.MAInterface.EUID((code,euid)=>{ console.log(code, euid) })
              
                  window.MAInterface.EUID((code,euid)=>{
        console.log(code, euid)
    })

            
This code block in the floating window

Set User Contact Information

Interface Definition

  • setUserContact(user)
    • Description:
      • Set multiple contact methods at once. The key is the name of the contact method and the value is its value. Currently 4 contact methods are supported: email, mobile_phone, landline_phone, and whatsapp_phone
    • Parameters
      • contacts: the user's contact information
      • completion: the callback

Call Example

let user = { completion: (code, message)=>{ }, contacts: {} } user.contacts["contact method name"] = "contact method value" // For example: mobile_phone=18800000000 window.MAInterface.setUserContact(user)
              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["contact method name"] = "contact method value"   // For example: mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            
This code block in the floating window

Set Channel Contact ID

Supported Versions

Supported since: 2.1.0

Interface Definition

  • setChannelValue(channelId, values, completion)
    • Description:
      • Set the RID or token for a push channel configured in the MA console (such as WebPush or a third-party push).
      • Call it after the SDK is initialized successfully; otherwise completion returns -1.
      • Call the API again when the RID or token changes.
    • Parameters
      • channelId: the ID of the push channel configured in the MA console; must be an integer greater than 0
      • values: an array of channel contact ID values (such as RIDs or tokens); the array cannot be empty, and its elements cannot be empty strings
      • completion: the callback; code 0 means success

Call Example

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

            
This code block in the floating window

Data Collection Switch

Supported Versions

Supported since: 2.2.0

Feature Description

The application enables or disables MA SDK data collection according to the user's consent, to meet compliance requirements that no behavioral data may be reported after the user refuses or withdraws consent.

  • Disabled: stops generating, caching, and reporting events, user properties, UTM, and device information. Initialization, getting EUID/RID, setting user identity, setting contact information, and setting channel contact ID still work.
  • Enabled: resumes collection. Data produced while disabled is not backfilled.
  • Enabled by default: when not set, collection is enabled, consistent with the behavior before upgrading.
  • Stored locally: the state is stored in the browser (localStorage) and persists across refreshes and reopened pages. Clearing site data restores the default.
  • Controlled by the application: the SDK does not detect the user's region, show a consent dialog, or read a consent management platform (CMP).

Interface Definition

  • init({ dataCollectionEnabled })

    • Description: set the switch state for the first launch at initialization.
    • Parameters: true to enable; false to disable; enabled by default when omitted.
  • setDataCollectionEnabled(enabled, completion)

    • Description: enable or disable data collection. Takes effect immediately and is stored locally.
    • Parameters:
      • enabled: true to enable, false to disable
      • completion: the callback; code 0 means success; returns -1 when the argument is not a boolean
    • Notes:
      • 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.
      • When switching from enabled to disabled, the SDK immediately tries once to send the data produced before the switch (including the end event of the current session), does not retry on failure, and then clears the local cache.
      • When switching from disabled to enabled, the SDK reports device information and starts a new session (reporting el_session_start and el_page_view of the current page).
      • While disabled, conversion attribution for WebPush notification clicks is no longer counted.
  • isDataCollectionEnabled()

    • Description: return the current switch state. Reads only the local state and makes no network request.
    • Return value: true enabled, false disabled; returns true when no state has been saved. The return value reflects the SDK switch state, not whether the user has consented.

API Behavior While Disabled

API While disabled How the application knows
All user property APIs Intercepted, no request sent completion returns -8, "data collection disabled"
Report event (onEvent), set UTM properties (setUtmProperties) Dropped silently No callback. Check with isDataCollectionEnabled() before calling
Initialization (init), set user identity (identifyAccount), get EUID, set user contact information (setUserContact), set channel contact ID (setChannelValue), set session timeout (setSessionTimeout), set page stay time (setPageStayTime) Not intercepted Unchanged; values set by setSessionTimeout and setPageStayTime take effect after collection is enabled

Call Example

// 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, completion: (code, msg) => {} }) // After the user grants consent window.MAInterface.setDataCollectionEnabled(true, (code, msg) => {}) // After the user withdraws consent window.MAInterface.setDataCollectionEnabled(false, (code, msg) => {}) // Query const enabled = window.MAInterface.isDataCollectionEnabled()
              
                // 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,
    completion: (code, msg) => {}
  })

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

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

  // Query
  const enabled = window.MAInterface.isDataCollectionEnabled()

            
This code block in the floating window

Set UTM Properties

Interface Definition

  • setUtmProperties(attrs:any)
    • Description:
      • UTM properties are standard event properties. If you can identify which advertisement brought the user to the app, we recommend setting the UTM information; it is passed along when events are reported. The UTM properties that can be set are:
        • utm_source: campaign source
        • utm_medium: campaign medium
        • utm_term: campaign term
        • utm_content: campaign content
        • utm_campaign: campaign name
        • utm_id: campaign ID

Call Example

window.MAInterface.setUtmProperties({"utm_source":"value1"})
              
                 window.MAInterface.setUtmProperties({"utm_source":"value1"})

            
This code block in the floating window

Set User Properties

Set the values of user properties. If a user property does not exist, it is created automatically on the server.

Overwrite User Properties

  • setProperty(user, completion)
    • Description:
      • Overwrite the values of user properties.
      • Only the latest reported data is kept, replacing historical data, such as the user's membership level.
      • The user properties are stored in an object. The key is the user property name and must be a string; the value is the property content and supports string, number, Array, object, and object_array types.
      • Elements of an Array value currently must be strings; an array whose elements are all objects is treated as object_array; an array mixing objects with other types is invalid.
      • If a user property already exists, it is overwritten; otherwise it is created. See below for the update rules of object and object_array.
    • Call Example:
window.MAInterface.setProperty({key:"value"}, (code, message)=>{})
              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            
This code block in the floating window

object / object_array Rules

Supported since: 2.1.0

  • object is a non-empty plain object, such as { city: "Singapore", score: 100 }; object_array is an array whose elements are all non-empty plain objects.
  • Sub-field names must be non-empty strings and cannot contain . or $; sub-field values support string, number, and string arrays, and cannot nest object or object_array further.
  • object uses sub-field merge semantics: setting it again updates only the sub-fields passed this time, and sub-fields not passed stay unchanged; passing null as a sub-field value removes that sub-field.
  • object_array uses whole-replacement semantics: setting it again replaces the whole array with the new one and keeps the array order. Pass a non-empty array of objects when creating an object_array for the first time.
  • Sub-field types must match the definition of the user property in the MA console; otherwise the server returns a failure.
window.MAInterface.setProperty({ profile: { city: "Singapore", score: 100 }, addresses: [ { id: "home", city: "Singapore" }, { id: "office", city: "Tokyo" } ] }, (code, message)=>{}) // Update only profile.score; profile.city stays unchanged window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})
              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // Update only profile.score; profile.city stays unchanged
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            
This code block in the floating window

Increment User Properties

  • increaseProperty(user, completion)
    • Description:
      • Increment the values of user properties.
      • Add values to multiple numeric user properties. All reported data is accumulated, such as the cumulative purchase amount.
      • Only number-type user properties can be used with this API; other types are ignored. If the user property did not exist before, the initial value is treated as 0.
    • Call Example:
window.MAInterface.increaseProperty({key:1}, (code, message)=>{})
              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            
This code block in the floating window

Append User Properties

  • addProperty(key, content completion)
    • Description:
      • Append values to a user property.
      • Elements can be added to the set continuously and are deduplicated when stored. If ABC already exists and CD is appended, the result is ABCD, for example news liked by the user.
      • Add values to an Array-type property. The Array elements must be strings; otherwise they are ignored. If the property to append to did not exist before, an empty Array is initialized.
    • Call Example:
window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})
              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            
This code block in the floating window

Remove User Property Values

  • removeProperty(key, content completion)
    • Description:
      • Remove one or more values from an array-type property.
      • Remove some values from an Array-type property. The Array elements must be strings; otherwise they are ignored. If the property did not exist before, nothing happens.
    • Call Example:
window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})
              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            
This code block in the floating window

Operate on object_array Elements

Supported Versions

Supported since: 2.1.0

The following usages apply only to object_array user properties and locate an element in the array through a unique identifier sub-field. When addProperty and removeProperty receive a string array, they still operate on string arrays and their behavior is unchanged.

  • addProperty(key, object, completion)
    • Description:
      • When the second argument is a single object (not an array), append one element to the end of the object_array without affecting existing elements.
      • The object must be non-empty. Sub-field rules are the same as for the object type; nested object or object_array is not supported.
      • If the property is not defined in the MA console yet, the server automatically creates it as an object_array property and writes this element; if it is defined but the current user has no value yet, the array is created with this single element.
    • Call Example:
window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})
              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            
This code block in the floating window
  • updateProperty(key, content, completion)
    • Description:
      • Locate one element in the object_array through a unique identifier sub-field and merge-update the element's sub-fields.
      • content has the structure { $identifier_key, $identifier_value, $new_object }:
        • $identifier_key: the name of the sub-field used to locate the element; it must already be defined in the MA console with type string or number
        • $identifier_value: the value to match, of type string or number; if multiple elements match, the update applies to all of them
        • newobject:thesub−fieldstoupdate;mustbeanon−emptyobjectandcannotcontainthesub−fieldnamedbynew_object: the sub-fields to update; must be a non-empty object and cannot contain the sub-field named by identifier_key; sub-fields not passed stay unchanged, and passing null as a sub-field value removes that sub-field
      • If no element matches or sub-fields do not match the property definition, the server returns a failure and does not modify other elements; if multiple elements match, the same update is applied to all matching elements.
      • If the property is not defined yet, the server returns a failure (55004); if it is defined but the current user has no value for it, the server returns code=0 without making changes.
    • Call Example:
// Update city of the element whose id is home to Tokyo, and remove the zip sub-field window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})
              
               // Update city of the element whose id is home to Tokyo, and remove the zip sub-field
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            
This code block in the floating window
  • removeProperty(key, content, completion)
    • Description:
      • When the second argument is { $identifier_key, $identifier_value }, remove the matching element from the object_array as a whole (all matching elements are removed when several match). content can contain only these two fields.
      • The requirements for identifierkeyandidentifier_key and identifier_value are the same as for updateProperty.
      • If the property is not defined yet, the server returns a failure (55004); if the current user has no value for it or no element matches, the server ignores the request and returns code=0; if multiple elements match, all matching elements are removed.
    • Call Example:
// Remove the element whose id is office window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})
              
               // Remove the element whose id is office
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            
This code block in the floating window

Delete User Properties

Interface Definition

  • deleteProperty(key, completion)
    • Description:
      • Delete all values of a user property.
      • If the user property did not exist before, the call is ignored.

Call Example

window.MAInterface.deleteProperty("key", (code, message)=>{})
              
               window.MAInterface.deleteProperty("key", (code, message)=>{})

            
This code block in the floating window

Set Session Timeout

Interface Definition

  • setSessionTimeout(time)
    • Description:
      • Set the session timeout. When the page goes to the background, the timeout starts counting. The session ends once the configured time (default 30 minutes) is exceeded.

Call Example

window.MAInterface.setSessionTimeout(60)
              
               window.MAInterface.setSessionTimeout(60)

            
This code block in the floating window

Set Page Stay Time

Interface Definition

  • setPageStayTime(time)
    • Description:
      • Set the duration for the page stay time.
      • Timing starts when the page is visited. If the user stays on the page for time seconds without leaving, the event is reported.
      • By default the event is reported at 6 points: 5 seconds, 30 seconds, 60 seconds, 2 minutes, 5 minutes, and 10 minutes. Call this API to add more points.

Call Example

window.MAInterface.setPageStayTime(60)
              
               window.MAInterface.setPageStayTime(60)

            
This code block in the floating window

Report Events

If an event does not exist, report it directly and the server creates it automatically.

Interface Definition

  • onEvent(event)
    • Description:
      • Report an event
    • Parameters
      • event: the event to report. name is the event name and properties contains the event properties, where the key is the property name and the value is the property value

Call Example

let event = {name:"name", properties:{key:"value"}} window.MAInterface.onEvent(event)
              
                 let event = {name:"name", properties:{key:"value"}}
    window.MAInterface.onEvent(event)

            
This code block in the floating window
Icon Solid Transparent White Qiyu
Contact Sales