iOS MA SDK 集成指南
适用版本
本文适用于 v5.5.0 及以后版本的独立版 MTMA SDK。目前 SDK 只支持 iOS 10 以上版本的手机系统。
5.5.0 以前的集成方式请查看 5.5.0 以前集成指南。
v5.5.0 开始，MTMA SDK 不需要依赖 AppPush，可以单独集成和初始化。MTMA 与 AppPush 代码独立，正式 SDK 仍通过 Push 组合包发布，开发者可以只集成组合包中的 MTMA，也可以同时集成 MTMA 和 MTPush。
配置工程
导入 SDK
Cocoapods 导入
pod 'MTMA'
注：如果无法导入最新版本，请执行 pod repo update 命令来升级本机的 pod 库，然后重新 pod 'MTMA'
- 如果需要安装指定版本则使用以下方式（以 MTMA 5.5.0 版本为例）：
pod 'MTMA', '5.5.0'
手动导入
- 将 SDK 包解压，在 Xcode 中选择 “Add files to 'Your project name'...”，将 MTMA-ios-x.x.x.xcframework 添加到你的工程目录中。
隐私清单
SDK 包内已提供 PrivacyInfo.xcprivacy。如果打包后的 App 没有自动带入，请参考该文件补充 App 的隐私清单。
初始化 SDK
独立版 MTMA SDK 使用 MA AppKey 进行初始化，不需要等待 AppPush 初始化或注册成功。
初始化前，请在 MA 控制台为当前项目下 MA AppKey 对应的数据源配置与 App 一致的 iOS Bundle ID，并启用数据源。SDK 自动读取 App 的 Bundle Identifier，无须另行设置；未绑定或不一致会导致初始化失败。
若初始化返回 55004，且 message 提示 packageName is not bound，请检查上述绑定配置。
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"your MA AppKey";
config.resultCompletion = ^(MTMAInitResult *result) {
NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];
return YES;
}
部分参数说明
- appKey
- MA AppKey，必填，必须为 24 位字母或数字。
- MA AppKey 与 Push AppKey 相互独立，可以相同，也可以不同。
- resultCompletion
- 初始化结果回调，通过 result.isSuccess 判断是否成功；失败时可提供 result.code 和 result.message 排查原因。
- 返回对象及字段说明见 MTMAInitResult 类。
初始化需要联网。设备离线时，SDK 等待网络恢复后自动继续，不会立即回调失败。
SDK 支持重复初始化和切换 MA AppKey，每次有效调用按顺序执行并分别回调。详细规则见 启动 MA 业务功能。
初始化时设置用户标识
如需在初始化时设置用户标识，可通过 MTMAConfig.userID 传入。userID、anonymousID、email、phone 均为可选字段，以下以 userID 为例：
MTMAUserID *userID = [[MTMAUserID alloc] init];
userID.userID = @"member_10001";
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = @"your MA AppKey";
config.userID = userID;
config.resultCompletion = ^(MTMAInitResult *result) {
if (result.isSuccess) {
NSLog(@"MTMA 初始化成功");
} else {
NSLog(@"MTMA 初始化失败，code=%ld，message=%@", (long)result.code, result.message);
}
};
[MTMAService start:config];
不设置用户标识也可以初始化。初始化成功不代表每个标识都设置成功，字段校验及回调说明见 MTMAUserID 类。
初始化场景
| 场景 | 接入方式 |
|---|---|
| MA 与 AppPush 使用相同 AppKey | 分别初始化 MTMA 和 AppPush，设置相同的 AppKey，初始化顺序不限 |
| 只使用 MTMA | 只集成和初始化 MTMA，不需要集成 AppPush |
| 先使用 MTMA，后来加入 AppPush | 保留 MTMA 集成，加入并初始化 AppPush；AppPush 注册成功后自动设置通道 |
| MA 与 AppPush 使用不同 AppKey | 分别初始化 MTMA 和 AppPush，设置各自的 AppKey，初始化顺序不限 |
| 使用 JPush 或其他第三方 Push | 分别初始化 MTMA 和第三方 Push，待 MTMA 初始化成功且取得第三方 RID 或 Token 后，调用第三方 Push 通道设置接口 |
同时使用 AppPush
在 MA 控制台配置移动端数据来源时，请选择同时使用 AppPush，并选择实际接入的 AppPush 应用。初始化 AppPush 时使用所选应用的 AppKey。
MTMA 和 AppPush 分别初始化，不要求固定的初始化顺序。
// 初始化 Push SDK
[MTPushService setupWithOption:launchOptions
appKey:pushAppKey
channel:channel
apsForProduction:isProduction
advertisingIdentifier:nil];
// 初始化 MTMA SDK
MTMAConfig *config = [[MTMAConfig alloc] init];
config.appKey = maAppKey;
config.resultCompletion = ^(MTMAInitResult *result) {
NSLog(@"result：%ld - %@", result.code, result.message);
};
[MTMAService start:config];
AppPush 注册成功并取得 Push RegistrationID 后，MTMA SDK 会自动设置 AppPush 通道。AppPush 未注册或通道设置失败，不影响 MTMA 初始化、事件采集和上报。
设置通道联系ID
如需使用第三方 Push，请在 MTMA 初始化成功后设置第三方 Push 的 RID 或 Token。
[MTMAService setChannelValueWithChannelId:136
values:@[@"push rid or token"]
completion:^(NSInteger code, NSString *message) {
NSLog(@"result：%ld - %@", code, message);
}];
部分参数说明
- channelId
- MA 控制台中配置的第三方 Push 通道 ID，必须大于 0。
- values
- 第三方 Push 的 RID 或 Token 数组，数组及元素均不能为空。
- RID 或 Token 变化后，需要再次调用接口更新。
该接口只用于第三方 Push，详细约束见 设置通道联系ID。
旧版升级说明
- 正式 SDK 仍通过 Push 组合包发布，原来同时集成 AppPush 和 MTMA 的项目不需要调整手动导入方式。
- 升级到 v5.5.0 后，必须设置 MTMAConfig 的 appKey。
- MTMAConfig.userID 和四个用户标识字段均为可选属性，Swift 接入时请按可选属性处理。
- 旧版 completion 回调继续保留，建议改用 resultCompletion；同时设置时只回调 resultCompletion。
- Push RegistrationID 和 MA RID 是不同的设备身份，不能混用。
