iOS SDK 使用说明

最后更新时间：2020年09月03日

1.集成SDK

云图SDK当前提供Cocoapods安装SDK方式（应用工厂项目默认集成）

Cocoapods 安装完成后，在你的项目根目录创建一个 Podfile 文件，添加如下内容：

pod 'cloudatlas_ios_component', '1.4.29'

2.基本功能集成

2.1 初始化 iOS SDK

在应用启动时，需要初始化云图SDK，SDK通过CloudAtlas的start``WithAppkey方法。

代码示例如下：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    // 设置AppKey与渠道方式
    [CloudAtlas startWithAppkey:@"YOUR_APP_KEY" isDebugMode:NO channelId:@"YOUR_CHANNEL_ID"];

    // 默认渠道方法，选择上面接口或本接口其一即可
    //[CloudAtlas startWithAppkey:@"YOUR_APP_KEY" isDebugMode:NO];

    // 日志是否开启，默认关闭
    [CloudAtlas setLogEnabled:YES];

    // 设置云图的数据上传环境，环境参数：生产环境（FORMAL），预生产环境（PRE_FORMAL），默认生产环境(FORMAL)
    // [CloudAtlas switchEnv:FORMAL];

    ...
    return YES;
}

参数说明： 1、YOUR_APP_KEY：初始化时配置AppKey,将 @"YOUR_APP_KEY" 中的YOUR_APP_KEY 替换为您在云图项目组中申请的应用AppKey。

2、isDebugMode：是否开启调试模式，默认为关闭，具体参数为：: YES：在调试模式下,云图的内部异常将被抛出；NO：为关闭状态。

3、ChannelId：渠道ID，配置应用发布的渠道，默认为空，即为Default。可将 @"YOUR_CHANNEL_ID" 中的YOUR_CHANNEL_ID替换为您定义的渠道ID。

ChannelId的填写规则：

3.1 首尾字符不可以为空格，当首尾出现空格时将会自动过滤空格； 3.2 不要使用纯数字或者纯数字和空格混合的字符作为渠道ID； 3.3 最多200个字符，当渠道ID多于200字符时将自动截断； 3.4 "unknown" 和"app store" 及其各种大小写形式，作为云图保留的字段，不可以作为渠道名；

2.2 会话的统计

在应用被激活时，调用 applicationDidBecomeActive，退出激活状态时，调用 applicationWillResignActive。 在iOS中，当应用重新回到激活状态时，作为一个新的会话进行统计。 以上两个方法，在AppDelegate的相应生命周期方法中调用。

- (void)applicationDidBecomeActive:(UIApplication *)application {
    ...
    [CloudAtlas applicationDidBecomeActive];
    ...

- (void)applicationWillResignActive:(UIApplication *)application {
    ...
    [CloudAtlas applicationWillResignActive];
  ...
}

2.3 账号的统计

云图在统计时，提供了账号与设备两种统计方式，如采用账号统计方式，请用户登录后将账号登录后返回的用户ID profileSignInWithPUID:(NSString *)puid 接口：

[CloudAtlas profileSignInWithPUID:@"803370"];

当账号登出时，请使用 profileSignOff接口：

[CloudAtlas profileSignOff];

另外，当用户切换（新用户登录、旧用户登出）时，也会开启一次新的会话。

3、自定义事件的统计

自定义事件，目前支持以下三种多态方法，分别应用于不同的场景：

/** 自定义事件
 * @param eventId    事件Id
*/
+ (void)event:(NSString *)eventId;

/** 自定义事件
 * @param eventId    事件Id
 * @param attributes 事件属性集
*/
+ (void)event:(NSString *)eventId attributes:(NSDictionary *)attributes;

/** 自定义事件
 * @param eventId    事件Id
 * @param attributes 事件属性集
 * @param number     整数属性值
 */
+ (void)event:(NSString *)eventId attributes:(NSDictionary *)attributes counter:(int)number;

如果只需要统计某个事件发生的次数，可以只传一个事件id，如：

[CloudAtlas event:@"{领域}_{组件}_{页面}_{操作}"];

考虑到某些情况下，对于一个事件，我们有一些属性要统计。如购买事件，可能有水果的类型、门店等需要统计，可以使用带NSDictionary的接口：

NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"apple", @"type", @"0AD056SDSD00AS", @"store", nil];
[CloudAtlas event:@"{领域}_{组件}_{页面}_{操作}" attributes:dictionary];

而在此基础上，如果还要扩展统计购买的金额，同时需要对金额做一些数值上的计算分析，则需要调用带int类型value的接口：

NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:@"apple", @"type", @"0AD056SDSD00AS", @"store", nil];
[CloudAtlas event:@"{领域}_{组件}_{页面}_{操作}" attributes:dictionary counter:20];

4、环境切换

设置云图的数据上传环境，环境参数：生产环境（FORMAL），：预生产环境（PRE_FORMAL），集成环境（INTEGRATION），默认生产环境(FORMAL)

[CloudAtlas switchEnv:FORMAL];

5、日志输出

在集成云图SDK的过程中，为了测试云图SDK是否运行正常，可以通过打开日志输出来使得云图SDK输出运行过程中产生的一些日志。 目前的日志包括但不限于：底层初始化结果、AppKey解析失败、调用参数无效、调用顺序错乱、采集数据发送内容与结果等。

[CloudAtlas setLogEnabled:YES];