API 指南

设置用户标识

支持的版本

email、phone 标识开始支持的版本：2.1.0

接口定义

• identifyAccount(user);
  • 接口说明:
    • 设置用户标识，如：用户会员卡号。
  • 参数说明
    • identity用户标识 ID，Key 支持 user_id、anonymous_id、email、phone 4个值，至少提供一个，无需全部填写
    • completion 回调
  • 用户标识规则
    • user_id：去除首尾空格后非空，最长 255 个字符，不能是 0、null、undefined、nan（忽略大小写）
    • anonymous_id：去除首尾空格后非空，最长 256 个字符
    • email：用户的邮箱地址，去除首尾空格后非空，最长 256 个字符，需为合法的邮箱格式，如 user@example.com
    • phone：用户的手机号码，需为包含国家或地区代码的 E.164 格式，如 +8613800000000
    • 任一字段不符合规则时，本次调用不会发送请求，completion 返回 -1，message 为具体原因

调用示例

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

            

email、phone 在这里用于用户身份匹配，可能返回新的 EUID，与「设置用户联系方式」（setUserContact）设置的联系方式不能互相替代。

获取 EUID

接口定义

• + EUID()
  • 接口说明:
    • 获取 EngageLab MA 的 EUID

调用示例

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

            

设置用户联系方式

接口定义

• setUserContact(user)
  • 接口说明:
    • 支持同时设置多个联系方式的值。，Key为联系方式的名称，value为联系方式的值，目前支持email、mobile_phone、landline_phone、whatsapp_phone 这 4 种联系方式
  • 参数说明
    • contacts用户联系方式
    • completion 回调

调用示例

              
                    let user = {
          completion: (code, message)=>{ },
          contacts: {}
       }
      user.contacts["联系方式的名称"] = "联系方式的值"   //例如：mobile_phone=18800000000
      window.MAInterface.setUserContact(user)

            

设置通道联系ID

支持的版本

开始支持的版本：2.1.0

接口定义

• setChannelValue(channelId, values, completion)
  • 接口说明:
    • 为 MA 控制台中配置的 Push 通道（如 WebPush、第三方 Push）设置 RID 或 Token。
    • 需在 SDK 初始化成功后调用，否则 completion 返回 -1。
    • RID 或 Token 变化后，需要再次调用接口更新。
  • 参数说明
    • channelId：MA 控制台中配置的 Push 通道 ID，必须为大于 0 的整数
    • values：通道联系ID的值数组（例如 RID 或 Token），不能为空，数组元素也不能为空字符串
    • completion 回调，code 为 0 表示成功

调用示例

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

            

设置 UTM 属性

接口定义

• setUtmProperties(attrs:any)
  • 接口说明:
    • UTM 属性为标准事件属性，若开发者能识别用户是从哪一个广告跳转访问 App ，建议设置 UTM 信息，我们将在事件上报时传递该参数。目前能够设置 UTM 属性为：
      • utm_source 广告系列来源
      • utm_medium 广告系列媒介
      • utm_term 广告系列字词
      • utm_content 广告系列内容
      • utm_campaign 广告系列名称
      • utm_id 广告系列ID

调用示例

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

            

设置用户属性

设置用户属性的值，若用户属性不存在，后台会自动创建。

覆盖更新用户属性

• setProperty(user, completion)
  • 接口说明:
    • 覆盖更新用户属性的值
    • 仅保存最新上报的数据，覆盖历史数据，如：用户会员等级。
    • 这些用户属性的内容用一个 object 来存储，其中的 key 是用户属性的名称，必须是 string，Value 则是用户属性的内容，支持 string、number、Array、object 和 object_array 类型。
    • Array 类型的 value 中目前只支持其中的元素是 string；元素全部为 object 的数组按 object_array 处理，object 与其他类型混合的数组无效。
    • 如果某个用户属性之前已经存在了，则这次会被覆盖掉；不存在，则会创建。object 与 object_array 的更新规则见下文。
  • 调用示例:

              
                 window.MAInterface.setProperty({key:"value"}, (code, message)=>{})

            

object / object_array 规则

开始支持的版本：2.1.0

• object 为非空的普通对象，如 { city: "Singapore", score: 100 }；object_array 为元素均为非空普通对象的数组。
• 子字段名必须是非空 string，不能包含 . 或 $；子字段值支持 string、number 和 string 数组，不支持继续嵌套 object 或 object_array。
• object 使用子字段合并语义：再次设置时只更新本次传入的子字段，未传的子字段保持不变；子字段值传 null 表示移除该子字段。
• object_array 使用整体替换语义：再次设置时用新数组整体替换原数组，并保持数组顺序。首次创建 object_array 请传入非空对象数组。
• 子字段类型需与 MA 控制台中该用户属性的定义一致，不符合时由服务端返回失败。

              
                 window.MAInterface.setProperty({
       profile: { city: "Singapore", score: 100 },
       addresses: [
           { id: "home", city: "Singapore" },
           { id: "office", city: "Tokyo" }
       ]
   }, (code, message)=>{})

   // 只更新 profile.score，profile.city 保持不变
   window.MAInterface.setProperty({ profile: { score: 200 } }, (code, message)=>{})

            

累加更新用户属性

• increaseProperty(user, completion)
  • 接口说明:
    • 对用户属性的值设置累加。
    • 给多个数值类型的用户属性增加数值。累加所有上报的数据，如累计消费金额。
    • 只能对 number 类型的用户属性调用这个接口，否则会被忽略, 如果这个用户属性之前不存在，则初始值当做 0 来处理。
  • 调用示例：

              
               window.MAInterface.increaseProperty({key:1}, (code, message)=>{})

            

追加用户属性

• addProperty(key, content completion)
  • 接口说明:
    • 对用户属性的值进行追加。
    • 可持续增加该集合元素，元素入库去重处理，若已存在ABC，追加CD，最终为ABCD，如用户点赞的新闻。
    • 向一个 Array 类型的属性添加一些值，这个 Array 的元素必须是 string，否则，会忽略, 同时，如果要 append 的用户属性之前不存在，会初始化一个空的 Array。
  • 调用示例：

              
               window.MAInterface.addProperty("key",["value1", "value2"], (code, message)=>{})

            

移除用户属性

• removeProperty(key, content completion)
  • 接口说明:
    • 删除数组类型的属性其中的一个或多个值。
    • 删除一个 Array 类型的属性中的一些值，这个 Array 的元素必须是 string，否则，会忽略, 同时，如果要 removeEventListAttrValue的用户属性之前不存在，则不会有效果。
  • 调用示例：

              
               window.MAInterface.removeProperty("key",["value1", "value2"], (code, message)=>{})

            

操作 object_array 元素

支持的版本

开始支持的版本：2.1.0

以下用法仅用于 object_array 类型的用户属性，通过唯一标识子字段定位数组中的元素。addProperty、removeProperty 传入字符串数组时仍用于字符串数组，行为保持不变。

• addProperty(key, object, completion)
  • 接口说明:
    • 第二个参数传入单个 object（而非数组）时，向 object_array 末尾追加一个元素，不影响已有元素。
    • object 需为非空对象，子字段规则与 object 类型一致，不支持嵌套 object 或 object_array。
    • 该属性需已在 MA 控制台定义为 object_array 类型，尚未定义时服务端返回 code=0 但不产生修改；属性已定义但当前用户还没有值时，会用这一个元素创建数组。
  • 调用示例：

              
               window.MAInterface.addProperty("addresses", { id: "school", city: "Osaka" }, (code, message)=>{})

            

• updateProperty(key, content, completion)
  • 接口说明:
    • 通过唯一标识子字段定位 object_array 中的一个元素，并合并更新该元素的子字段。
    • content 结构为 { $identifier_key, $identifier_value, $new_object }：
      • $identifier_key：用于定位元素的子字段名，该子字段需已在 MA 控制台定义，类型为 string 或 number
      • $identifier_value：定位值，类型为 string 或 number，且在当前数组中只能匹配一个元素
      • $new_object：要更新的子字段，需为非空对象，不能包含$identifier_key 对应的子字段；未传的子字段保持不变，子字段值传 null 表示移除该子字段
    • 数组中没有匹配元素、匹配多个元素或子字段不符合属性定义时，服务端返回失败，不会修改其他元素。
    • 该属性尚未定义，或当前用户还没有该属性值时，服务端返回 code=0 但不产生修改。
  • 调用示例：

              
               // 把 id 为 home 的元素的 city 更新为 Tokyo，并移除 zip 子字段
 window.MAInterface.updateProperty("addresses", {$identifier_key:"id", $identifier_value:"home", $new_object:{city:"Tokyo", zip:null}}, (code, message)=>{})

            

• removeProperty(key, content, completion)
  • 接口说明:
    • 第二个参数传入 { $identifier_key, $identifier_value } 时，移除 object_array 中唯一匹配的整个元素，content 只能包含这两个字段。
    • $identifier_key、$identifier_value 的要求与 updateProperty 一致。
    • 该属性尚未定义、当前用户没有该属性值或没有匹配元素时，服务端忽略本次请求并返回 code=0；匹配多个元素时服务端返回失败，不会误删其他元素。
  • 调用示例：

              
               // 移除 id 为 office 的元素
 window.MAInterface.removeProperty("addresses", {$identifier_key:"id", $identifier_value:"office"}, (code, message)=>{})

            

删除用户属性

接口定义

• deleteProperty(key, completion)
  • 接口说明:
    • 删除某个用户属性的全部 value 内容。
    • 如果这个用户属性之前不存在，则直接忽略。

调用示例

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

            

设置会话超时时间

接口定义

• setSessionTimeout(time)
  • 接口说明:
    • 设置会话超时时间，页面置于后台时，开始计算会话超时时间，超过所设置的时间（默认30分钟）后将会结束本次会话。

调用示例

              
               window.MAInterface.setSessionTimeout(60)

            

设置页面停留时间

接口定义

• setPageStayTime(time)
  • 接口说明:
    • 设置页面停留时间的持续时间。
    • 访问页面后开始计时，在该页面停留 time 秒没有跳走则上报该事件。
    • 默认在 5 秒、30 秒、60 秒、2 分钟、5 分钟、10 分钟这 6 个时间点上报，开发者可以调用本接口增加更多的时间点

调用示例

              
               window.MAInterface.setPageStayTime(60)

            

上报事件

如果事件不存在时直接上报，后台会自动创建该事件

接口定义

• onEvent(event)
  • 接口说明:
    • 上报事件
  • 参数说明
    • event 上报的事件，name为事件名称，properties为事件属性信息，其中Key为属性名称，value为属性值

调用示例

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