使用 SDK
初始化
使用组件前，需要完成的基本初始化操作。
前置条件
若要通过组件初始化，必须先完成 SDK 集成，请参见 集成SDK。
引入头文件
#import "TMFProfile.h"
初始化
由于组件无需特殊初始化，可以考虑直接在使用时调用而无需特别进行初始化操作。
+ (instancetype)defaultReporter;
- (void)initialize;
初始化示例
// AppDelegate
[[TMFProfileReporter defaultReporter] initialize];
数据上报
通过调用上报接口，完成客户端信息同步到后台。
前置条件
若要进行通用上报，必须先完成组件初始化，请参见 集成SDK。
通用上报
单条信息通用上报 API ，可完成 布尔/数字/字符串/二进制数据 等信息上报。
- (void)updateProfileWithID:(TMFProfileID)profileID boolValue:(BOOL)boolValue;
- (void)updateProfileWithID:(TMFProfileID)profileID dataValue:(nullable NSData *)dataValue;
- (void)updateProfileWithID:(TMFProfileID)profileID stringValue:(nullable NSString *)stringValue;
- (void)updateProfileWithID:(TMFProfileID)profileID integerValue:(NSInteger)integerValue;
参数
参数介绍中，必选仅针对于不同的 API 生效：
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| profileID | TMFProfileID |
与后台协定好的上报字段 ID，详情请参见下方“TMFProfileID 枚举” | Y |
| boolValue | BOOL |
上报 布尔 类型数据 | Y |
| dataValue | NSData * |
上报 二进制 类型数据 | N |
| stringValue | NSString * |
上报 字符串 类型数据 | N |
| integerValue | NSInteger |
上报 整形 数据 | Y |
TMFProfileID 枚举
上报的信息需要定义 TMFProfileID 字段，此字段需结合后台进行业务扩展。
typedef NS_ENUM(NSInteger, TMFProfileID) { TMFProfileIDNone = 0, ///< 未知 TMFProfileIDCountry = 5001, ///< 国家 TMFProfileIDProvince = 5002, ///< 省份 TMFProfileIDCity = 5003, ///< 城市 TMFProfileIDDepartment = 5004, ///< 部门 TMFProfileIDUserID = 1033, ///< 用户 UserID TMFProfileIDToken = 10014, ///< 远程推送 Token };
用户信息上报
- (void)updateCustomizedUserID:(nullable NSString *)customizedUserID;
- (void)updateRemoteNotificationToken:(NSString *)deviceToken;
参数
参数介绍中，必选仅针对于不同的 API 生效：
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| customizedUserID | NSString * |
自定义用户 ID 如果为空，解绑操作 如果不为空，绑定操作 |
N |
| deviceToken | NSString * |
远程推送 Token | Y |
自定义标签上报
- (void)updateCustomizedTagWithKey:(NSString *)tagKey value:(nullable NSString *)tagValue;
参数
自定义标签，需要与后台协定后再进行上报，一切标签名/标签值以后台发布为准。
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| tagKey | NSString * |
标签名 | Y |
| tagValue | NSString * |
标签值 如果为空，则为删除标签操作 如果不为空，则为设定标签操作 |
N |
主动上报
可以通过如下接口主动触发上报 （一般用于上报失败后主动重试）：
- (void)reportIfNeeded;
代码示例
下面是部分上报示例：
// 通用上报
// 地理位置可以通过 CLLocationManager 来获取
NSString *country = @"China"; // 国家
NSString *province = @"GuangDong"; // 省份
NSString *city = @"GuangZhou"; // 城市
TMFProfileReporter *profileReporter = [TMFProfileReporter defaultReporter];
[profileReporter updateProfileWithID:TMFProfileIDCountry stringValue:country];
[profileReporter updateProfileWithID:TMFProfileIDProvince stringValue:province];
[profileReporter updateProfileWithID:TMFProfileIDCity stringValue:city];
// 用户信息上报
// 远程推送 Token 需要通过系统方式获取 或通过 TMFPush 获取
// 绑定
NSString *userID = @"x3dsw23lh";
NSString *token = @"xxxx";
[profileReporter updateCustomizedUserID:userID];
[profileReporter updateRemoteNotificationToken:token];
// 解绑
[profileReporter updateCustomizedUserID:nil];
// 自定义标签上报
// 设置标签
NSString *tagKey = @"性别";
NSString *tagValue = @"男";
[profileReporter updateCustomizedTagWithKey:tagKey value:tagValue];
// 删除标签
[profileReporter updateCustomizedTagWithKey:tagKey value:nil];
// 主动上报
// 假设发生了上报失败
[[TMFProfileReporter defaultReporter] reportIfNeeded];
结果通知
组件不直接提供上报反馈，可以通过捕捉通知的方式，来获取到上报结果。
前置条件
若要进行通知监听，必须先完成组件初始化，请参见 集成SDK。
相关通知
// Profile 上报结束通知
extern NSString *const TMFProfileDidReportNotification;
// 通知 userInfo key 用于获取当前上报的所有 Profile 条目 { NSString : id }
extern NSString *const TMFProfileDidReportItemsKey;
// 通知 userInfo key 用于获取当前上报失败的错误信息 { NSString : NSError }
extern NSString *const TMFProfileDidReportErrorKey;
代码示例
下面是注册监听结果并执行弹窗操作的示例：
// init
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(profileDidReport:)
name:TMFProfileDidReportNotification
object:nil];
// handler
- (void)profileDidReport:(NSNotification *)notification
{
dispatch_async(dispatch_get_main_queue(), ^{
NSDictionary *errorInfo = notification.userInfo[TMFProfileDidReportErrorKey];
NSDictionary *reportedInfo = notification.userInfo[TMFProfileDidReportItemsKey];
UIAlertController *alertController = nil;
NSMutableString *reportedResult = [NSMutableString string];
if (errorInfo.count > 0) {
for (NSString *key in errorInfo.allKeys) {
[reportedResult appendFormat:@"【Error】%@\n", errorInfo[key]];
[reportedResult appendFormat:@"【%@】%@\n\n", key, reportedInfo[key]];
}
alertController = [UIAlertController alertControllerWithTitle:@"上报失败" message:reportedResult preferredStyle:UIAlertControllerStyleAlert];
} else if (reportedInfo.count > 0) {
for (NSString *key in reportedInfo.allKeys) {
[reportedResult appendFormat:@"【%@】%@\n", key, reportedInfo[key]];
}
alertController = [UIAlertController alertControllerWithTitle:@"上报成功" message:reportedResult preferredStyle:UIAlertControllerStyleAlert];
}
if (alertController) {
[alertController addAction:[UIAlertAction actionWithTitle:@"知道了" style:UIAlertActionStyleCancel handler:nil]];
[self presentViewController:alertController animated:YES completion:nil];
}
});
}
日志
组件提供日志接口，可供业务黑盒调试。
前提条件
若要查询更新数据，必须先完成组件初始化，请参见 集成SDK。
相关接口
@property (class, nonatomic, assign) TMFProfileLogLevel logLevels;
日志等级
typedef NS_OPTIONS(NSUInteger, TMFProfileLogLevel) {
TMFProfileLogLevelNone = 0, ///< 无日志
TMFProfileLogLevelInfo = 1 << 0, ///< 普通日志
TMFProfileLogLevelWarn = 1 << 1, ///< 警告日志
TMFProfileLogLevelError = 1 << 2, ///< 错误日志
TMFProfileLogLevelAll = 0xFF, ///< 全部日志
};
日志示例
下面是在 AppDelegate.m 中配置组件日志的示例：
// AppDelegate.m
#if DEBUG
[TMFProfileReporter setLogLevels:TMFProfileLogLevelAll];
#elif
[TMFProfileReporter setLogLevels:TMFProfileLogLevelNone];
#endif
下面是只输出警告+错误的日志配置示例：
[TMFProfileReporter setLogLevels:(TMFProfileLogLevelWarn | TMFProfileLogLevelError)];