使用 SDK
初始化
使用组件前，需要完成的基本初始化操作。
前置条件
- 若要通过组件初始化，必须先完成 SDK 集成，详情请参见 集成 SDK。
- 请确保启动后在云指令组件
TMFInstruction初始化之前初始化本组件。
引入头文件
#import "TMFDistribution.h"
初始化
早期版本应用发布任务推拉是依赖数据同步组件来完成的，从公有云版本起，应用发布支持直接使用移动网关来实现任务推拉，可以解除任务推拉对数据同步组件的依赖。不过本次协议调整对新版服务有依赖，考虑到私有化客户不同的服务版本，SDK侧做了兼容，同时保留了两套协议实现，客户在初始化时根据自身服务情况指定协议版本即可。
+ (instancetype)sharedManager;
- (void)initialize;
/**
@brief 应用发布推送协议
*/
typedef NS_ENUM(NSInteger, TMFDistributionPushPassagePolicy) {
TMFDistributionPushPassagePolicyConch = 0, // default 旧协议
TMFDistributionPushPassagePolicyShark = 1,
};
/**
* @brief 使新协议传入回调
*
* @note 初始化时SDK未拉取更新单，需要App调用自动/手动检查更新
*/
- (void)initWithDistributionHandler:(TMFDistributionHandler)handler
TMFDistributionPushMsg:(TMFDistributionPushPassagePolicy)pushMsg;
初始化示例
// AppDelegate.m
[[TMFDistributionManager sharedManager] initialize];
// 新协议
[[TMFDistributionManager sharedManager] initWithDistributionHandler:nil TMFDistributionPushMsg:TMFDistributionPushPassagePolicyShark];
发布监听
对发布更新监听，弹出更新推送弹窗。 主动拉取支持两种方式：
- 自动检查更新：该方式会检查弹窗频率限制，更新结果通过初始化传入的TMFDistributionHandler回调给开发者。
- 手动检查更新：该方式不会检查弹窗评率限制，检查更新结果会通过独立设置的TMFDistributionSharkCallBack回调给开发者。使用场景是应用内的检查更新菜单，由用户触发。
前置条件
若要执行发布监听，必须先完成组件初始化，详情请参见 初始化。
监听设置
通过实现监听接口，通过接口回调，监听应用发布更新。
接口定义
- (void)setDidReceiveDistributionHandler:(TMFDistributionHandler)handler;
其中，TMFDistributionHandler 的定义如下：
typedef void (^TMFDistributionHandler)(
TMFDistributionInfo * _Nullable info,
TMFDistributionCompletionBlock completionHandler
);
其中，TMFDistributionCompletionBlock 的定义如下：
typedef void (^TMFDistributionCompletionBlock)(
BOOL updated
);
- 参数
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| handler | TMFDistributionHandler(block) |
监听回调，详见下方“handler 回调” | Y |
- handler 回调
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| info | TMFDistributionInfo * |
更新数据对象，用于储存当次更新的数据信息，请参见 数据对象 | N |
| completionHandler | TMFDistributionCompletionBlock(block) |
业务操作回调，通知组件是否同意发起更新，详见下方“completionHandler 回调” | Y |
- completionHandler 回调
| 参数 | 类型 | 描述 | 必选 |
|---|---|---|---|
| updated | BOOL |
自定义 Handler 的完成回调，在自定义 Handler 中调用，通知组件是否同意发起更新 | Y |
数据对象
数据对象支持复制，序列化。
@interface TMFDistributionInfo : NSObject <NSCoding, NSCopying>
@property (nonatomic, assign) BOOL updatesForcibly; ///< 是否强制更新
@property (nonatomic, assign) NSInteger noticeTimeInterval; ///< 更新提示周期
@property (nonatomic, retain) NSURL *appStoreURL; ///< 更新的 App Store 链接
@property (nonatomic, copy) NSString *buildNumberString; ///< 更新 Build 号
@property (nonatomic, copy, nullable) NSString *distributionTitle; ///< 更新标题
@property (nonatomic, copy, nullable) NSString *featureDescription; ///< 更新的功能描述
@end
- 属性
| 属性 | 类型 | 描述 | 权限 |
|---|---|---|---|
| updatesForcibly | BOOL |
是否强制更新 | readwrite |
| noticeTimeInterval | NSInteger |
更新提示周期 | readwrite |
| appStoreURL | NSURL * |
更新的 app store 链接 | readwrite |
| buildNumberString | NSString * |
更新版本号 | readwrite |
| distributionTitle | NSString * |
更新标题 | readwrite |
| featureDescription | NSString * |
更新的功能描述 | readwrite |
监听示例
下面是开启并自定义发布处理的示例：
// 注册自定义 Handler
[[TMFDistributionManager sharedManager] setDidReceiveDistributionHandler:^(TMFDistributionInfo * _Nullable info,
TMFDistributionCompletionBlock _Nonnull completionHandler) {
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:info.distributionTitle
message:info.featureDescription
preferredStyle:UIAlertControllerStyleAlert];
UIAlertAction *cancelAction = [UIAlertAction actionWithTitle:@"取消" style:UIAlertActionStyleCancel
handler:^(UIAlertAction * _Nonnull action) {
completionHandler(NO);
}];
UIAlertAction *updateAction = [UIAlertAction actionWithTitle:@"更新" style:UIAlertActionStyleDefault
handler:^(UIAlertAction * _Nonnull action) {
if ([[UIApplication sharedApplication] canOpenURL:info.appStoreURL]) {
[[UIApplication sharedApplication] openURL:info.appStoreURL];
}
completionHandler(YES);
}];
[alertController addAction:updateAction];
if (!info.updatesForcibly) {
[alertController addAction:cancelAction];
}
// 弹出弹窗
UIViewController *rootController = [UIApplication sharedApplication].keyWindow.rootViewController;
[rootController presentViewController:alertController animated:YES completion:nil];
}];
新协议下的自动检查更新：
// 注册自动拉取弹窗处理 并且使用SDK默认弹窗
[[TMFDistributionManager sharedManager] autoCheckForUpdatesDistributionHandler:nil];
新协议下的主动检查更新：
// 注册自动拉取弹窗处理 并且使用自定义弹窗
[[TMFDistributionManager sharedManager] drivingCheckForUpdatesDistributionHandler:^(TMFDistributionInfo * _Nullable distributionInfo, NSError * _Nullable error, TMFDistributionCompletionBlock _Nullable completionHandler) {
if (error) {
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:@"TMFDistribution"
message:[NSString stringWithFormat:@"没有获取到更新单失败\n error = %@",error]
preferredStyle:UIAlertControllerStyleAlert];
[alertController addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:nil]];
[self presentViewController:alertController animated:YES completion:nil];
return;
}
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:distributionInfo.distributionTitle
message:distributionInfo.featureDescription
preferredStyle:UIAlertControllerStyleAlert];
UIAlertAction *cancelAction = [UIAlertAction actionWithTitle:@"取消" style:UIAlertActionStyleCancel
handler:^(UIAlertAction * _Nonnull action) {
}];
UIAlertAction *updateAction = [UIAlertAction actionWithTitle:@"更新" style:UIAlertActionStyleDefault
handler:^(UIAlertAction * _Nonnull action) {
[self _jumpAppStoreWithURL:distributionInfo.appStoreURL];
}];
[alertController addAction:updateAction];
if (!distributionInfo.updatesForcibly) {
[alertController addAction:cancelAction];
}
// 弹出弹窗
[[UIApplication sharedApplication].keyWindow.rootViewController presentViewController:alertController animated:YES completion:nil];
}];
下面是默认和自定义的监听到发布更新后的弹窗，其中左侧为强制更新，右侧为非强制更新。
数据查询
组件提供数据查询属性，可供业务查询最近一次更新信息
前提条件
若要查询更新数据，必须先完成组件初始化，详情请参见 初始化。
相关接口
@property (nonatomic, readonly, nullable) TMFDistributionInfo *distributionInfo;
使用示例
下面是获取上一次更新数据并弹窗展示的示例：
TMFDistributionInfo *distributionInfo = [TMFDistributionManager sharedManager].distributionInfo;
NSMutableString *message = [NSMutableString string];
[message appendFormat:@"【更新 Build 号】 %@\n", distributionInfo.buildNumberString];
[message appendFormat:@"【App Store 链接】 %@\n", distributionInfo.appStoreURL.absoluteString];
[message appendFormat:@"【更新标题】 %@\n", distributionInfo.distributionTitle];
[message appendFormat:@"【更新描述】 %@\n", distributionInfo.featureDescription];
[message appendFormat:@"【更新提示周期】 %ld秒\n", (long)distributionInfo.noticeTimeInterval];
[message appendFormat:@"【是否强制更新】 %@\n", distributionInfo.updatesForcibly ? @"是" : @"否"];
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:@"TMFDistribution"
message:message
preferredStyle:UIAlertControllerStyleAlert];
[alertController addAction:[UIAlertAction actionWithTitle:@"OK"
style:UIAlertActionStyleDefault
handler:nil]];
[self presentViewController:alertController animated:YES completion:nil];
日志
组件提供日志接口，可供业务黑盒调试
前提条件
若要配置日志，必须先完成组件初始化，详情请参见 初始化。
相关接口
@property (class, nonatomic, assign) TMFDistributionLogLevel logLevels;
日志等级
typedef NS_OPTIONS(NSUInteger, TMFDistributionLogLevel) {
TMFDistributionLogLevelNone = 0, ///< 无日志
TMFDistributionLogLevelInfo = 1 << 0, ///< 普通日志
TMFDistributionLogLevelWarn = 1 << 1, ///< 警告日志
TMFDistributionLogLevelError = 1 << 2, ///< 错误日志
TMFDistributionLogLevelAll = 0xFF, ///< 全部日志
};
日志示例
下面是在 AppDelegate.m 中配置组件日志的示例：
// AppDelegate.m
#if DEBUG
[TMFDistribution setLogLevels:TMFDistributionLogLevelAll];
#elif
[TMFDistribution setLogLevels:TMFDistributionLogLevelNone];
#endif
下面是只输出警告+错误的日志配置示例：
[TMFDistribution setLogLevels:(TMFDistributionLogLevelWarn | TMFDistributionLogLevelError)];