Android MA 功能集成指南
适用版本
本文适用于 5.5.0 及以后版本的独立版 MA SDK。
从 5.5.0 开始，MA 不再依赖 AppPush，可以单独集成和初始化。MA AppKey 与 Push AppKey 相互独立，可以相同，也可以不同。
5.5.0 以前的融合版集成方式请查看5.5.0 以前集成指南。
1. 导入 SDK
手动导入
将发布包中的 mt-sdk-ma-5.5.0.aar 加入应用工程的 libs 目录：
dependencies {
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}
Maven 导入
dependencies {
implementation 'com.engagelab.plugin:oth_ma:5.5.0'
}
如果同时使用 AppPush，再按 AppPush 文档引入 engagelab 主包；仅使用 MA 时不需要引入 AppPush 主包。
2. 权限配置
在 AndroidManifest.xml 中声明网络权限：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
独立版 MA 不需要配置 ENGAGELAB_PRIVATES_APPKEY、ENGAGELAB_PRIVATES_CHANNEL、Push Service 或 Push Receiver。如果同时使用 AppPush，仍需按照 AppPush 集成文档完成对应配置。
3. 初始化 SDK
建议在主进程的 Application.onCreate() 中初始化。初始化使用 MA AppKey，不需要等待 AppPush 初始化或注册成功。
import android.app.Application;
import com.engagelab.privates.push.oth.ma.api.MTMAApi;
import com.engagelab.privates.push.oth.ma.api.MTMAConfig;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResult;
import com.engagelab.privates.push.oth.ma.api.MTMAInitResultCallback;
public class MainApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
MTMAApi.configDebugMode(true);
MTMAConfig config = new MTMAConfig("your MA AppKey");
// 可选（5.5.2 起支持）：需要按用户同意结果控制采集时，传入应用当前记录的同意结果，true 开启、false 关闭，从未设置过则默认开启
// 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();
}
}
});
}
}
初始化说明
- MA AppKey 必填。
- Android MA SDK 只支持在宿主应用主进程初始化。在非主进程调用
start会通过回调返回失败，不会发起网络请求。 - 初始化成功前，除初始化前配置接口外，其他 MA 业务 API 不可用。
- 建议所有 MA 对外 API 均在主进程调用。非主进程不会共享主进程的初始化状态，业务调用不会转发给主进程。
- 初始化成功后也可通过
getEuid()和getMaRid()获取当前值。
运行时切换 MA AppKey
同一进程支持在运行时切换 MA AppKey。请在上一次初始化回调完成后，使用新 AppKey 再次调用 start。
MTMAConfig newConfig = new MTMAConfig("new MA AppKey");
MTMAApi.getInstance(this).start(newConfig, callback);
切换期间其他 MA 业务 API 暂不可用；新 AppKey 初始化成功后，后续事件和用户数据归属新 AppKey。如果新 AppKey 初始化失败，SDK 不会自动回退到旧 AppKey，需要使用有效 AppKey 重新调用 start。
初始化时设置用户标识
UserIdentity identity = new UserIdentity();
identity.setUserId("your user id");
identity.setAnonymousId("your anonymous id");
identity.setEmail("user@example.com");
identity.setPhone("+8613800138000");
MTMAConfig config = new MTMAConfig("your MA AppKey", identity);
MTMAApi.getInstance(this).start(config, callback);
其中 setEmail、setPhone 从 5.5.0 版本开始支持。
用户标识字段规则：user_id 去除首尾空格后不能为空，最长 255 个 Unicode 字符，且不能为 0、null、undefined、nan（忽略大小写）；anonymous_id 去除首尾空格后不能为空，最长 256 个 Unicode 字符；email 不能为空、最长 256 个 Unicode 字符，必须包含且只能包含一个 @，@ 前后均不能为空，且不能包含空格、换行或 Tab；phone 必须符合 E.164 格式，以 + 开头，国家码首位为 1–9，之后包含 1–14 位数字。校验失败时 SDK 不发送身份请求，并通过回调返回 code = -3。
可选：按用户同意控制采集
如应用需要根据用户同意结果控制采集，可使用数据采集开关；不需要时无需任何改动，默认开启，行为与升级前一致。该能力从 MA SDK 5.5.2 开始提供。
开关按 MA AppKey 分别保存。在初始化时，请根据用户的同意状态对 dataCollectionEnabled 动态传值，不要写死配置，避免每次初始化都导致状态被重置为写死的值。运行中用户改变选择时，在初始化成功后调用 setDataCollectionEnabled 接口。均在主进程执行：
// enabled 为应用根据用户同意结果决定的开关状态
MTMAConfig config = new MTMAConfig(maAppKey);
config.dataCollectionEnabled(enabled);
MTMAApi.getInstance(this).start(config, initCallback);
// 运行中用户改变选择时
MTMAApi.getInstance(this).setDataCollectionEnabled(enabled);
接入时需注意：
- 关闭期间，事件、用户属性、UTM 和设备信息停止采集与上报；初始化、用户标识、联系方式和推送通道照常可用，SDK 仍会发送这些必要请求。
- 从开启切换为关闭时，SDK 会立即发送一次切换前已产生的数据，失败不重试，随后清除本地缓存。
- 调用
config.dataCollectionEnabled时须传入true或false，每次start都会生效：与上次状态不同时，本次启动直接按新状态初始化；在已启动的情况下再次调用start改变状态时，会执行一次关闭或开启处理。 - 重新开启后 SDK 自动恢复采集，恢复完成前调用的事件、用户属性和 UTM 不会保留。
接口参数、各接口在关闭期间的行为和错误码，见 API 指南的数据采集开关。
4. 同时使用 AppPush
在 MA 控制台配置移动端数据来源时，请选择同时使用 AppPush，并选择实际接入的 AppPush 应用。初始化 AppPush 时，请使用所选应用的 AppKey。
MA 与 AppPush 分别初始化，不要求固定顺序。AppPush 注册成功并取得 Push RID 后，MA SDK 会自动绑定 AppPush 通道。
AppPush 未集成、尚未注册或通道绑定失败，不影响 MA 初始化、事件采集和上报。
注意：MA RID 与 AppPush RID 是两个独立的设备标识。请分别通过对应 SDK 获取和使用，不要将其中一个作为另一个使用。
5. 设置通道联系ID
如需为第三方 Push 通道设置通道联系ID，请在 MA 初始化成功后调用：
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 表示成功
}
});
channelId：MA 控制台配置的第三方 Push 通道 ID，必须大于 0。values：通道联系ID的值列表（例如 RID 或 Token），不能为空，列表元素也不能为空。- 通道联系ID发生变化后，需要再次调用接口更新。
- 该接口用于设置第三方 Push 通道联系ID；AppPush 通道由 SDK 自动绑定。
6. 旧版升级说明
- 升级到 5.5.0 后，必须使用
MTMAConfig显式传入 MA AppKey。 - 不再需要等待 AppPush 长连接或注册成功后调用 MA
start。 start(CallBack)和start(UserIdentity, CallBack)已废弃，独立版请使用start(MTMAConfig, MTMAInitResultCallback)。- 原来同时使用 AppPush 和 MA 的应用，可继续集成 AppPush，但两者需要分别初始化。
- MA RID 与 AppPush RID 是两个独立的设备标识。请分别通过对应 SDK 获取和使用，不要将其中一个作为另一个使用。
其他业务接口请查看 API 指南。
