Android SDK API

SDK 接口说明

• MTMAApi：MA 运行时接口。
• MTMAConfig：传给 start 的初始化配置。

调用前说明

• start 只能在宿主应用主进程调用。
• 除允许在初始化前设置的配置接口外，其他 MA 业务 API 只能在初始化成功后调用。
• 建议所有 MA 对外 API 均在主进程调用。非主进程不共享主进程的初始化状态，调用不会转发给主进程。
• 在非主进程调用业务 API 时，有回调的接口返回 CODE_START_FAIL (-2)，getEuid() 和 getMaRid() 返回空值，无回调的业务接口不会执行。
• configDebugMode、setCollectControl、setReportInterval、setMaxEventCacheCount 和 setNoActiveSessionEndDurationTime 是进程内配置；在非主进程调用不会修改主进程 MA 的配置。

获取 SDK 版本

支持的版本

开始支持的版本：5.5.0

字段定义

• MTMAApi.SDK_VERSION_CODE：MA SDK 数字版本号。
• MTMAApi.SDK_VERSION_NAME：MA SDK 字符串版本号。

              
              int versionCode = MTMAApi.SDK_VERSION_CODE;
String versionName = MTMAApi.SDK_VERSION_NAME;

            

设置调试模式

支持的版本

开始支持的版本：5.5.0

接口定义

• configDebugMode(boolean enable)
  • 开启或关闭 MA SDK 调试日志。
  • 建议在调用 start 前设置，发布版本建议关闭。

              
              MTMAApi.configDebugMode(true);

            

启用MA功能

支持的版本

开始支持的版本：5.5.0

接口定义

• start(MTMAConfig config, MTMAInitResultCallback callback)
  • 接口说明：使用 MA AppKey 初始化独立版 MA SDK。
  • config：初始化配置，类型为 MTMAConfig。
    • MTMAConfig(String appKey)：设置 MA AppKey。
    • MTMAConfig(String appKey, UserIdentity userIdentity)：设置 MA AppKey，并可同时设置用户标识。
    • config.dataCollectionEnabled(boolean enabled)：可选，在 MTMAConfig 对象上调用，设置本次 start 时当前 MA AppKey 的数据采集开关，从 5.5.2 开始支持。
      • true 开启，false 关闭。调用后每次 start 都按传入值生效并保存在本机，请传入用户当前的同意结果，不要写死固定值。
      • 详见数据采集开关。
  • callback：初始化结果回调。
  • MTMAInitResult：
    • isSuccess()：初始化是否成功。
    • getCode()：结果码，0 表示成功。
    • getMessage()：结果描述。
    • getEuid()：初始化成功后取得的 EUID。
    • getMaRid()：初始化成功后取得的 MA RID。

调用示例

              
              MTMAConfig config = new MTMAConfig("your MA AppKey");
// 可选（5.5.2 起支持）：按用户当前的同意结果设置数据采集开关；从未设置过则默认开启
// config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, new MTMAInitResultCallback() {
    @Override
    public void onResult(MTMAInitResult result) {
        if (result.isSuccess()) {
            String euid = result.getEuid();
            String maRid = result.getMaRid();
        } else {
            int code = result.getCode();
            String message = result.getMessage();
        }
    }
});

            

运行时切换 AppKey

上一次初始化回调完成后，可使用新的 MTMAConfig 再次调用 start。切换期间其他 MA 业务 API 暂不可用。新 AppKey 初始化失败时不会自动回退到旧 AppKey。

废弃接口

从 5.5.0 开始，以下接口已废弃：

• start(CallBack callBack)
• start(UserIdentity userIdentity, CallBack callBack)

请改用 start(MTMAConfig config, MTMAInitResultCallback callback)。

设置用户标识

建议在用户登录、提供相关信息时设置该接口，获得与该用户匹配的 EUID

支持的版本

开始支持的版本： 5.0.0

接口定义

• _setUserIdentity(UserIdentity userIdentity, CallBack callBack) _
  • 接口说明：
    • 设置用户标识，如：用户会员卡号。
  • 参数说明：
    • userIdentity：调用标识
      • setUserId(String userId)：去除首尾空格后不能为空，最长 255 个 Unicode 字符；不能为 0、null、undefined、nan（忽略大小写）
      • setAnonymousId(String anonymousId)：去除首尾空格后不能为空，最长 256 个 Unicode 字符
      • setEmail(String email)：不能为空，最长 256 个 Unicode 字符；必须包含且只能包含一个 @，@ 前后都不能为空，且不能包含空格、换行或 Tab；5.5.0 开始支持
      • setPhone(String phone)：必须符合 E.164 格式，以 + 开头，国家码首位为 1–9，之后包含 1–14 位数字；5.5.0 开始支持
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见 message 参数描述

调用示例

              
                              UserIdentity userIdentity = new UserIdentity();
                userIdentity.setUserId("您的userId");
                userIdentity.setAnonymousId("您的AnonymousId");
                userIdentity.setEmail("user@example.com");
                userIdentity.setPhone("+8613800138000");
                MTMAApi.getInstance(this).setUserIdentity(userIdentity, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        MTCommonLog.e(TAG, "setUserIdentity code:" + code);
                        MTCommonLog.e(TAG, "setUserIdentity message:" + message);
                    }
                });

            

用户标识字段校验失败时不发送网络请求，并通过回调返回 code = -3。

设置用户联系方式

当用户的联系方式发生变更时，可使用本接口更新用户的「联系方式」。

支持的版本

开始支持的版本： 5.0.0

接口定义

• setUserContact(JSONObject contacts, CallBack callBack)
  • 接口说明：
    • 设置用户的「联系方式」。
  • 参数说明：
    • contacts：设置多个联系方式，Key 为联系方式的名称，value 为联系方式的值，目前支持 email、mobile_phone、landline_phone、whatsapp_phone 这 4 种联系方式
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见 message 参数描述
    • message：原因描述

调用示例

              
                              JSONObject contacts = new JSONObject();
                try {
                    contacts.put("key1", "cc");
                    contacts.put("key2", "dd");
                } catch (JSONException e) {
                    e.printStackTrace();
                }
                MTMAApi.getInstance(this).setUserContact(contacts, new CallBack() {
                    @Override
                    public void onCallBack(int code, String message) {
                        Log.e(TAG, "setUserContact code:" + code);
                        Log.e(TAG, "setUserContact message:" + message);
                    }
                });

            

获取 EUID

支持的版本

开始支持的版本： 5.0.0

接口定义

• getEuid()
  • 接口说明：
    • 获取 EUID，表示用户唯一 ID。仅初始化成功时返回当前值，其他状态返回空值。

调用示例

              
              MTMAApi.getInstance(this).getEuid();

            

获取 MA RID

支持的版本

开始支持的版本：5.5.0

接口定义

• getMaRid()
  • 获取当前 MA RID。仅初始化成功时返回当前值，其他状态返回空值。

              
              String maRid = MTMAApi.getInstance(this).getMaRid();

            

设置通道联系ID

支持的版本

开始支持的版本：5.5.0

接口定义

• setChannelValue(long channelId, List values, CallBack callBack)
  • 接口说明：设置通道联系ID。AppPush 通道由 SDK 自动绑定，不需要调用该接口设置。
  • 参数说明：
    • channelId：MA 控制台配置的第三方 Push 通道 ID，必须大于 0。
    • values：通道联系ID的值列表（例如 RID 或 Token），不能为空，列表元素也不能为空。
    • callBack：结果回调，code == 0 表示成功。

              
              List<String> values = Collections.singletonList("push rid or token");
MTMAApi.getInstance(this).setChannelValue(136L, values, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {
        // code == 0 表示成功
    }
});

            

设置上报数据间隔

和 setMaxEventCacheCount 接口共同生效，只需满足其中一个条件就会上报

支持的版本

开始支持的版本： 5.0.0

接口定义

• setReportInterval(int interval)
  • 接口说明:
    • 设置上报数据间隔，不调用该接口时，默认为 10s 上报一次事件数据
    • 上报间隔内存缓存，需要在应用程序每次生命周期中调用才会生效
  • 参数说明
    • interval 上报间隔，单位 s(秒)

调用示例

              
                  MTMAApi.getInstance(this).setReportInterval(10);

            

设置事件缓存上限条数

和 setReportInterval 接口共同生效，只需满足其中一个条件就会上报

支持的版本

开始支持的版本： 5.0.0

接口定义

• setMaxEventCacheCount(int count)
  • 接口说明:
    • 设置事件缓存上限条数，默认50条，最高不能超过500条
    • 当超出缓存数量时会上报报全部数据
  • 参数说明
    • count 事件缓存条数上限

调用示例

              
                  MTMAApi.getInstance(this).setMaxEventCacheCount(50);

            

设置会话超时时间

支持的版本

开始支持的版本： 5.0.0

接口定义

• setNoActiveSessionEndDurationTime(int duration)
  • 接口说明:
    • 当 App 置于后台时，开始计算会话超时时间，超过所设置的时间（默认 30 分钟）后将会结束本次会话。
  • 参数说明
    • duration 超时时长，单位s(秒)

调用示例

              
                  MTMAApi.getInstance(this).setNoActiveSessionEndDurationTime(5*60);

            

设置 UTM 属性

支持的版本

开始支持的版本： 5.0.0

接口定义

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

调用示例

              
                              UtmProperties utmProperties = new UtmProperties();
                utmProperties.setUtmSource("你的utm_source");
                utmProperties.setUtmCampaign("您的utm_campaign");
                utmProperties.setUtmContent("您的utm_content");
                utmProperties.setUtmId("您的utm_id" );
                utmProperties.setUtmMedium("您的utm_medium");
                utmProperties.setUtmTerm("您的utm_term");
                MTMAApi.getInstance(this).setUtmProperties(utmProperties);

            

数据采集开关

支持的版本

开始支持的版本：5.5.2

如应用需要根据用户同意结果控制采集，可使用数据采集开关；不需要时无需任何改动，默认开启，行为与升级前一致。

开关按 MA AppKey 分别保存。在初始化时，请根据用户的同意状态对 dataCollectionEnabled 动态传值，不要写死配置，避免每次初始化都导致状态被重置为写死的值。运行中用户改变选择时，在初始化成功后调用 setDataCollectionEnabled 接口。均在主进程执行。

设置数据采集开关

接口定义

• setDataCollectionEnabled(boolean enabled)
  • 接口说明：
    • 设置当前 MA AppKey 的数据采集开关，在主进程、初始化成功后调用。
    • 立即生效并保存在本机，不等待网络完成。
    • 设置的值与当前状态相同时，不会重复执行关闭或恢复处理，也不影响启动和会话统计。
    • 重新开启后 SDK 自动恢复采集，恢复完成前调用的事件、用户属性和 UTM 不会保留，有回调的接口返回 -2。
    • 关闭后各接口的行为见关闭期间的行为。
  • 参数说明：
    • enabled：true 开启，false 关闭。

调用示例

              
              // enabled 为应用根据用户同意结果决定的开关状态
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);

            

查询数据采集开关

接口定义

• isDataCollectionEnabled()
  • 接口说明：
    • 查询当前 MA AppKey 的数据采集开关；不发网络请求，不触发切换或恢复。
  • 返回说明：
    • true 开启，false 关闭。
    • start 之前还没有确定 AppKey：返回默认值 true，不代表任何 AppKey 的状态，请在 start 之后查询。
    • 非主进程返回 false，只表示该进程不采集，不代表主进程的开关状态。

调用示例

              
              boolean enabled = MTMAApi.getInstance(this).isDataCollectionEnabled();

            

关闭期间的行为

关闭期间停止

关闭期间照常可用

关闭时

• 切换前已产生的数据会立即发送一次，失败不重试，随后清除本地缓存。
• 已上报的数据不会被删除。

关闭期间仍会发送的请求

• 初始化、身份注册（不含设备特征）、配置拉取、推送通道绑定、开关状态同步。

推送与消息

• 推送照常送达，可打开 App。
• 不产生推送点击等 MA 事件，依赖 MA 行为事件的旅程条件不会命中。
• 点击推送或应用内消息不计入 MA 消息转化；关闭前的点击记录会被清除，开启后不再归因。

不受本开关控制

• 推送通道自身的送达、点击回执。
• 独立集成的 AppPush SDK 自身的上报。
• 应用后端调用的 MA REST 接口。
• 本开关不代替推送退订。

控制台与分群

• 用户详情显示“数据采集”状态，即最近一次同步到服务端的值，可能有延迟；从未设置过开关的 AppKey 下显示为空。
• 分群中可按“数据采集 = 关闭”圈选用户：任一设备为关闭即匹配，未上报状态的设备不匹配。

数据采集控制

setCollectControl 设置具体设备字段的采集许可；整体停止事件、用户属性、UTM 和设备采集使用数据采集开关。重新开启整体采集后，原字段许可继续生效。

支持的版本

开始支持的版本： 5.0.0

接口定义

• setCollectControl(MTMACollectControl control)
  • 接口说明：
    • 设置采集权限，如果需要开启/关闭某些数据采集，请调用本接口
  • 参数说明：
    • control：采集权限设置；未显式设置的属性使用以下默认值
      • setCarrier(boolean enable)：是否采集运营商信息，默认开启
      • setMacAddress(boolean enable)：是否采集 MAC 地址，默认关闭
      • setGAID(boolean enable)：是否采集 GAID，默认关闭
      • setOAID(boolean enable)：是否采集 OAID，默认关闭
      • setAAID(boolean enable)：是否采集 AAID，默认关闭
      • setIMEI(boolean enable)：是否采集 IMEI，默认关闭；仅 Android 9 及以下支持，宿主应用需自行声明并获取 READ_PHONE_STATE 权限

调用示例

              
              try {
MTMACollectControl mtmaCollectControl = new MTMACollectControl();
        mtmaCollectControl.setCarrier(true);
        mtmaCollectControl.setMacAddress(true);
        mtmaCollectControl.setGAID(true);
        mtmaCollectControl.setOAID(true);
        mtmaCollectControl.setIMEI(true);
        mtmaCollectControl.setAAID(true);
    MTMAApi.getInstance(this).setCollectControl(mtmaCollectControl);
} catch (Throwable e) {e.printStackTrace();
}

            

设置用户属性

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

覆盖更新用户属性

• propertySet(final JSONObject properties, final CallBack callBack)
  • 接口说明：
    • 批量覆盖更新用户属性的值
    • 仅保存最新上报的数据，覆盖历史数据，如：用户会员等级。
    • Value 支持字符串、数字、布尔值、字符串数组、JSONObject，以及元素全部为 JSONObject 的 JSONArray。
  • 参数说明：
    • properties: 用户属性
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              try {JSONObject properties = new JSONObject();
    properties.put("你的用户属性名","你的属性值");
    properties.put("你的用户属性名 2","你的属性值 2");
    properties.put("你的用户属性名 3","你的属性值 3");
    MTMAApi.getInstance(this).propertySet(properties, new CallBack() {
        @Override
        public void onCallBack(int code, String message) {}});
} catch (Throwable e) {e.printStackTrace();
}

            

• propertySet(String property, Object value, CallBack callBack)
  • 接口说明：
    • 单个覆盖更新用户属性的值
    • 仅保存最新上报的数据，覆盖历史数据，如：用户会员等级。
    • Value 类型规则与批量 propertySet 一致。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              MTMAApi.getInstance(this).propertySet("你的用户属性名","你的属性值", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

累加更新用户属性

• propertyIncrease(final Map<String, ? extends Number> properties, CallBack callBack)
  • 接口说明：
    • 对用户属性的值设置累加，批量请求
    • 累加所有上报的数据，如累计消费金额。
    • 只能对数值类型的用户属性调用这个接口，否则会被忽略, 如果这个用户属性之前不存在，则初始值当做 0 来处理。
  • 参数说明：
    • properties: 用户属性
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              Map<String,Number> properties = new HashMap();
properties.put("你的用户属性名",1);
properties.put("你的用户属性名 2",2);
properties.put("你的用户属性名 3",3);
MTMAApi.getInstance(this).propertyIncrease(properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyIncrease(final String property, final Number value, CallBack callBack)
  • 接口说明：
    • 对用户属性的值设置累加，单次请求
    • 累加所有上报的数据，如累计消费金额。
    • 只能对数值类型的用户属性调用这个接口，否则会被忽略, 如果这个用户属性之前不存在，则初始值当做 0 来处理。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              MTMAApi.getInstance(this).propertyIncrease("你的用户属性名",1, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

追加用户属性

• propertyAdd(final String property, final String value, CallBack callBack)
  • 接口说明：
    • 对用户属性的值进行追加，单次请求
    • 可持续增加该集合元素，元素入库去重处理，若已存在ABC，追加CD，最终为ABCD。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              MTMAApi.getInstance(this).propertyAdd("你的用户属性名","你的用户属性值", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyAdd(final String property, final Set values, CallBack callBack)
  • 接口说明：
    • 对用户属性的值进行追加，一次添加多个值
    • 可持续增加该集合元素，元素入库去重处理，若已存在ABC，追加CD，最终为ABCD。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              Set<String> properties = new HashSet<>();
properties.add("你的用户属性值");
properties.add("你的用户属性值 2");
properties.add("你的用户属性值 3");
MTMAApi.getInstance(this).propertyAdd("你的用户属性名",properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

操作 object_array 元素

以下接口从 5.5.0 开始支持，仅用于 object_array 用户属性。原有 propertyAdd、propertyRemove 仍用于字符串数组，行为保持不变。

• updateObjectArrayProperty(String property, String identifierKey, Object identifierValue, JSONObject values, CallBack callBack)
  • 根据唯一标识更新一个对象元素的子字段。
  • identifierValue 支持字符串或有限数字；values 不能修改标识字段。
  • values 中使用 JSONObject.NULL 可删除对应子字段。

              
              JSONObject values = new JSONObject().put("enabled", false);
MTMAApi.getInstance(this).updateObjectArrayProperty(
        "devices", "device_id", "device_1", values, callBack);

            

• addObjectArrayProperty(String property, JSONObject object, CallBack callBack)
  • 向 object_array 追加一个非空对象元素。

              
              JSONObject device = new JSONObject()
        .put("device_id", "device_2")
        .put("year", 2026);
MTMAApi.getInstance(this).addObjectArrayProperty("devices", device, callBack);

            

• removeObjectArrayProperty(String property, String identifierKey, Object identifierValue, CallBack callBack)
  • 根据唯一标识删除整个对象元素。

              
              MTMAApi.getInstance(this).removeObjectArrayProperty(
        "devices", "device_id", "device_2", callBack);

            

移除用户属性

• propertyRemove(final String property, String values, final CallBack callBack)
  • 接口说明：
    • 对用户属性的值操作移除。
    • 该值为集合元素，元素入库去重处理，若已存在 ABCD，删除 D，最终为 ABC。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              MTMAApi.getInstance(this).propertyRemove("你的用户属性名","你的用户属性值", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

• propertyRemove(final String property, Set values, final CallBack callBack)
  • 接口说明：
    • 对用户属性的值操作移除，一次移除多个值。
    • 该值为集合元素，元素入库去重处理，若已存在 ABCD，删除 CD，最终为 AB。
  • 参数说明：
    • property: 用户属性名
    • value: 用户属性值
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述
  • 调用示例：

              
              Set<String> properties = new HashSet<>();
properties.add("你的用户属性值");
properties.add("你的用户属性值 2");
properties.add("你的用户属性值 3");
MTMAApi.getInstance(this).propertyRemove("你的用户属性名",properties, new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

删除用户属性

支持的版本

开始支持的版本： 5.0.0

接口定义

• propertyDelete(final String property, final CallBack callBack)
  • 接口说明：
    • 删除某个用户属性的所有 value 值
  • 参数说明：
    • property: 用户属性名
    • callBack：接口回调
  • 返回说明：
    onCallBack(int code, String message)
    • code: 返回码，0 代表获取成功，-1 为失败，详见错误码描述
    • message：原因描述

调用示例

              
              MTMAApi.getInstance(this).propertyDelete("你的用户属性名", new CallBack() {
    @Override
    public void onCallBack(int code, String message) {}});

            

事件上报

支持的版本

开始支持的版本： 5.0.0

接口定义

• onEvent(String eventKey, JSONObject properties)
  • 接口说明：
    • 事件上报
  • 参数说明：
    • eventKey: 事件名称
    • properties：事件属性，Key为属性名称，value为属性值

调用示例

              
              JSONObject properties = new JSONObject();
properties.put("key1","v1");
properties.put("key2","v2");
MTMAApi.getInstance(this).onEvent("你的事件名称",properties );

            

错误码