使用 SDK

初始化

使用组件前，需要完成的基本初始化操作。

前置条件

若要通过组件初始化，必须先完成 SDK 集成，请参见 集成SDK。

引入头文件

#import "TMFInstructionCenter.h"

初始化

+ (instancetype)defaultCenter;

建议：云指令组件的初始化应该尽可能早地完成，但在 TMFShark TMFDistribution 之后即可。

检查更新

// 强制更新
- (void)checkForUpdates;

// 普通更新
- (void)checkForUpdatesIfNeeded;

初始化示例

// AppDelegate.m

// 初始化云指令配置并检查更新
[[TMFInstructionCenter defaultCenter] checkForUpdatesIfNeeded];

云指令查询

使用接口查询特定云指令的内容。

前置条件

若要进行云指令查询，必须先完成组件初始化，详情请参见 初始化。

相关接口

组件提供多种云指令接口，涵盖了 NSString / NSInteger / float / double / BOOL / NSURL 等多种类型：

- (nullable NSString *)stringForID:(TMFInstructionID)ID;
- (NSInteger)integerForID:(TMFInstructionID)ID;
- (float)floatForID:(TMFInstructionID)ID;
- (double)doubleForID:(TMFInstructionID)ID;
- (BOOL)boolForID:(TMFInstructionID)ID;
- (nullable NSURL *)URLForID:(TMFInstructionID)ID;
  • 参数
参数 类型 描述 必选
ID TMFInstructionID 后台与客户端协定好的云指令 ID Y

  • 返回值

    返回值介绍中，类型仅针对于不同的 API 生效：

类型 描述
NSString * 查询的 字符型 云指令
NSInteger 查询的 整型 云指令
float 查询的 浮点型 云指令
double 查询的 双精度浮点型 云指令
BOOL 查询的 布尔型 云指令
NSURL * 查询的 URL 链接 云指令

代码示例

// 比如，申请了 8022 指令，是一个字符型，可参考下面的用法读取该指令
NSString *valueString = [[TMFInstructionCenter defaultCenter] stringForID:8022];
NSLog(@"TMFInstruction valueString(%@)", valueString);

云指令监听

使用接口，针对特定的云指令进行监听，当发生变化时及时进行处理。

前置条件

若要进行云指令监听，必须先完成组件初始化，详情请参见 初始化。

相关接口

- (void)observeID:(TMFInstructionID)ID handler:(TMFInstructionHandler)handler;
  • 参数
参数 类型 描述 必选
handler TMFInstructionHandler(block) 监听云指令变化后的回调 Y

  • TMFInstructionHandler 回调

    typedef void (^TMFInstructionHandler)(TMFInstruction *instruction);

    参数

参数 类型 描述 必选
instruction TMFInstruction * 云指令数据模型，详情请参见 云指令数据模型 Y

代码示例

下面是模拟监听发布更新的示例：

const long long TMFInstructionIDSoftUpdate = 200; // 软件发布更新云指令 ID

NSURL *appStoreURL = [NSURL urlWithString:@""]; // 此处为软件的 app store 地址
[[TMFInstructionCenter defaultCenter] observeID:TMFInstructionIDSoftUpdate handler:^(TMFInstruction * _Nonnull instruction) {
    // 发起更新请求
      [[UIApplication sharedApplication] openURL:appStoreURL];
}];

当监听到后台下发更新云指令时，则会调用 Handler 方法，执行更新请求。

云指令数据模型

云指令数据对象支持复制，序列化。

@interface TMFInstruction : NSObject <NSCoding, NSCopying>

@property (nonatomic, assign) TMFInstructionID instructionID;           ///< 云指令id

@property (nonatomic, retain, nullable) NSArray<NSString *> *values;    ///< 下发云指令的值
@property (nonatomic, assign) TMFInstructionAction action;              ///< 云指令行为

@property (nonatomic, assign) long long taskID;                         ///< 任务ID
@property (nonatomic, assign) long long taskSeqNo;                      ///< 任务序号
@property (nonatomic, assign) NSInteger conchSeqNo;                     ///< 指令序号

@property (nonatomic, assign) NSInteger validEndTime;                   ///< 指令失效时间

@end
  • 属性
属性 类型 描述 权限
instructionID TMFInstructionID 云指令 ID readwrite
values NSArray<NSString *> * 云指令值 readwrite
action TMFInstructionAction 云指令行为 (更新/撤销)，详情请参见下方“TMFInstructionAction 枚举” readwrite
taskID long long 任务 ID readwrite
taskSeqNo long long 任务序号 readwrite
conchSeqNo NSInteger 指令序号 readwrite
validEndTime NSInteger 指令失效时间 readwrite

  • TMFInstructionAction 枚举

    typedef NS_ENUM(NSInteger, TMFInstructionAction) {
    TMFInstructionActionUpdate      = 0,    ///< 云指令有更新
    TMFInstructionActionRevoke      = 1,    ///< 云指令有撤销
};

云指令上报

用来上报云指令的执行结果，用于用户状态反馈。

前置条件

若要进行云指令上报，必须先完成组件初始化，详情请参见 初始化。

上报接口

- (BOOL)reportInstructionResult:(TMFInstructionResult *)instructionResult;
  • 参数
参数 类型 描述 必选
instructionResult TMFInstructionResult * 云指令执行结果 Y
  • 返回值
类型 描述
BOOL 是否上报成功

数据对象

@interface TMFInstructionResult : NSObject

@property (nonatomic, retain) TMFInstruction *instruction;          ///< 云指令内容
@property (nonatomic, assign) TMFInstructionPhase phase;            ///< 云指令执行阶段
@property (nonatomic, assign) TMFInstructionStatus status;          ///< 云指令执行状态

@end
  • 属性
属性 类型 描述 权限
instruction TMFInstruction * 云指令内容对象，详情请参见 云指令数据模型 readwrite
phase TMFInstructionPhase 云指令执行阶段，详情请参见“TMFInstructionPhase 枚举” readwrite
status TMFInstructionStatus 云指令执行状态，详情请参见“TMFInstructionStatus 枚举” readwrite

  • TMFInstructionPhase 枚举

    typedef NS_ENUM(NSInteger, TMFInstructionPhase) {
    TMFInstructionPhaseNone             = 0,
    TMFInstructionPhaseShown            = 1,  ///< 云指令显示上报
    TMFInstructionPhaseUserConfirmed    = 2,  ///< 云指令用户确认上报
    TMFInstructionPhaseExecuted         = 3,  ///< 云指令执行上报
};

  • TMFInstructionStatus 枚举

    typedef NS_ENUM(NSInteger, TMFInstructionStatus) {
    TMFInstructionStatusNone = 0,           ///< 默认
    TMFInstructionStatusSuccessful = 1,     ///< 云指令执行成功
    TMFInstructionStatusFailed = 2,         ///< 云指令执行失败
    TMFInstructionStatusInvalid = 3,        ///< 云指令无效
    TMFInstructionStatusExpired = 4,        ///< 云指令过期失效
    TMFInstructionStatusCancelled = 10,     ///< 云指令取消
    TMFInstructionStatusRevoked = 11,       ///< 云指令撤销
};

上报示例

下面是模拟云指令结果上报的示例：

// 当云指令执行到某个阶段，云指令由于用户拒接导致执行失败
// 此处省略对云指令对象的处理过程
TMFInstruction *instruction = xxx; // 需要上报的云指令对象

// 构建结果上报对象
TMFInstructionResult *result = [[TMFInstructionResult alloc] init];
result.instruction = instruction;
result.phase = TMFInstructionPhaseUserConfirmed;
result.status = TMFInstructionStatusFailed; // 云指令执行失败

// 上报
[[TMFInstructionCenter defaultCenter] reportInstructionResult:result];

云指令通知

当发生云指令更新时，组件会发出通知，业务可以接受通知后选择性进行处理。

前置条件

若要进行云指令通知监听，必须先完成组件初始化，详情请参见 初始化。

相关通知

// 云指令更新结束通知
extern NSString *const TMFInstructionCenterDidUpdateNotification;

// 通知 userInfo key 用于获取当前更新的云指令 ID NSIndexSet<NSInteger>
extern NSString *const TMFInstructionCenterUpdatedIDsKey;

  • 工具宏

    SDK 提供了处理通知的便捷宏，可以直接用来判断当前更新中是否包含需要的云指令：

    #define TMFInstructionNotificationContainsID(__notification__, __instructionID__) ({                    \
    NSIndexSet *IDs = [__notification__.userInfo objectForKey:TMFInstructionCenterUpdatedIDsKey];   \
    ([IDs isKindOfClass:[NSIndexSet class]] && [IDs containsIndex:__instructionID__]);              \
})

通知示例

下面是通过通知监听云指令更新的示例：

  • 使用宏：
// 8022 是需要监听的云指令

// 添加通知监听
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(instructionCenterDidUpdate:) name:TMFInstructionCenterDidUpdateNotification object:nil];

// 监听到更新后的回调方法
- (void)instructionCenterDidUpdate:(NSNotification *)notification
{
    if (TMFInstructionNotificationContainsID(notification, 8022)) {
        // 在此处理 8022 云指令的更新
    }
}
  • 不使用宏：
// 8022 是需要监听的云指令

// 添加通知监听
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(instructionCenterDidUpdate:) name:TMFInstructionCenterDidUpdateNotification object:nil];

// 监听到更新后的回调方法
- (void)instructionCenterDidUpdate:(NSNotification *)notification
{
      NSIndexSet *IDs = notification.userInfo[TMFInstructionCenterUpdatedIDsKey];
      if ([IDs isKindOfClass:[NSIndexSet class]] && [IDs containsIndex:8022]) {
          // 在此处理 8022 云指令的更新
    }
}

日志

组件提供日志接口，可供业务黑盒调试。

前提条件

若要查询更新数据，必须先完成组件初始化，详情请参见 初始化。

相关接口

@property (class, nonatomic, assign) TMFInstructionLogLevel logLevels;

日志等级

typedef NS_OPTIONS(NSUInteger, TMFInstructionLogLevel) {
    TMFInstructionLogLevelNone  = 0,        ///< 无日志
    TMFInstructionLogLevelInfo  = 1 << 0,   ///< 普通日志
    TMFInstructionLogLevelWarn  = 1 << 1,   ///< 警告日志
    TMFInstructionLogLevelError = 1 << 2,   ///< 错误日志

    TMFInstructionLogLevelAll   = 0xFF,     ///< 全部日志
};

日志示例

下面是在 AppDelegate.m 中配置组件日志的示例：

// AppDelegate.m

#if DEBUG
[TMFInstructionCenter setLogLevels:TMFInstructionLogLevelAll];
#elif
[TMFInstructionCenter setLogLevels:TMFInstructionLogLevelNone];
#endif

下面是只输出警告+错误的日志配置示例：

[TMFInstructionCenter setLogLevels:(TMFInstructionLogLevelWarn | TMFInstructionLogLevelError)];
Copyright © 2013-2023 Tencent Cloud. all right reserved，powered by GitbookUpdate Time 2023-08-31 14:46:07

results matching ""

    No results matching ""