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
- Description:
Call Example
let user = {completion: (code, message)=>{}, identity:{"user_id":"value","anonymous_id":"value","email":"user@example.com","phone":"+8613800000000"}}
window.MAInterface.identifyAccount(user)
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
- Description:
Call Example
window.MAInterface.EUID((code,euid)=>{
console.log(code, euid)
})
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
- Description:
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)
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
- Description:
Call Example
window.MAInterface.setChannelValue(136, ["push rid or token"], (code, message)=>{})
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:
trueto enable;falseto disable; enabled by default when omitted.
setDataCollectionEnabled(enabled, completion)
- Description: enable or disable data collection. Takes effect immediately and is stored locally.
- Parameters:
- enabled:
trueto enable,falseto disable - completion: the callback; code 0 means success; returns -1 when the argument is not a boolean
- enabled:
- 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_startandel_page_viewof 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:
trueenabled,falsedisabled; returnstruewhen 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()
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
- 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:
- Description:
Call Example
window.MAInterface.setUtmProperties({"utm_source":"value1"})
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:
- Description:
window.MAInterface.setProperty({key:"value"}, (code, message)=>{})
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
nullas 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)=>{})
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:
- Description:
window.MAInterface.increaseProperty({key:1}, (code, message)=>{})
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:
- Description:
window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})
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:
- Description:
window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})
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:
- Description:
window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})
- 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
- 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:
- Description:
// 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)=>{})
- 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 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.
- When the second argument is
- Call Example:
- Description:
// Remove the element whose id is office
window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})
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.
- Description:
Call Example
window.MAInterface.deleteProperty("key", (code, message)=>{})
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.
- Description:
Call Example
window.MAInterface.setSessionTimeout(60)
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.
- Description:
Call Example
window.MAInterface.setPageStayTime(60)
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
- Description:
Call Example
let event = {name:"name", properties:{key:"value"}}
window.MAInterface.onEvent(event)










