iOS SDK API

SDK 接口说明

1. JOPERATEService，包含 SDK 所有接口。
2. JOPERATEConfig，应用配置信息类。
3. JOPERATEUserID，用户标识模型。
4. JOPERATEEventObject, 自定义事件对象。
5. JOPERATEUserChannel, 用户通道模型。
6. JOperateCollectControl, 数据采集配置类。

SDK 初始化

支持的版本

开始支持的版本：2.0.7

接口定义

• + initializeSDK;
  • 接口说明:
    • 初始化接口。

调用示例

          
   [JOPERATEService initializeSDK];

        

SDK 初始化 (失效)

支持的版本

开始支持的版本： 2.0.0 开始失效的版本：2.0.7

接口定义

• + setupWithConfig:(JOPERATEConfig * )config;
  • 接口说明:
    • 初始化接口
  • 参数说明
    • config 配置类

调用示例

          
    JOPERATEConfig *config = [[JOPERATEConfig alloc] init];
    config.appKey = @"your appkey";
    config.advertisingId = idfaStr;
    [JOPERATEService setupWithConfig:config];

        

启动业务功能

支持的版本

开始支持的版本： 2.0.7

接口定义

• + operationStart:(JOPERATEConfig * )config;
  • 接口说明:
    • 启动行为分析及用户画像接口。
    • 调用该接口前请先调用 初始化接口 initializeSDK。
    • operationStart接口是其他接口的开始接口，所以必须先调用operationStart接口，才能调用其他接口
  • 参数说明
    • config 配置类

调用示例

          
    JOPERATEConfig *config = [[JOPERATEConfig alloc] init];
    config.appKey = @"your appkey";
    config.advertisingId = idfaStr;
    [JOPERATEService operationStart:config];

        

设置 Debug 模式

支持的版本

开始支持的版本： 2.0.0

接口定义

• +  (void)setDebug:(BOOL)enable;
  • 接口说明:
    • 开启 debug 模式
  • 参数说明
    • enable 是否开启 debug 模式

调用示例

              [JOPERATEService setDebug:YES];

        

自定义事件统计

调用该接口前，需要先在控制台创建元事件，详情参考 创建元事件。

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)eventRecord:(JOPERATEEventObject * )event;
  • 接口说明:
    • 自定义事件统计
  • 参数说明
    • event 上报的自定义事件模型

调用示例

              JOPERATEEventObject *e = [[JOPERATEEventObject alloc] init];
    e.eventName = @"eventID1";
    e.property = @{@"key":@"key", @"user":@"user", @"add":@1};
    [JOPERATEService eventRecord:e];

        

设置用户联系方式

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)setUserChannel:(JOPERATEUserChannel * )channel;
  • 接口说明:
    • 为指定「通道ID」下的「联系标签」设置用户的「联系方式」。
    • 初始联系标签名称为「默认联系」，若要设置自定义的名称则需要先在平台界面上添加 联系标签。
    • 支持同时设置多个「联系标签」的值。
    • 设置「APP通知」的「联系标签」时，其值须为该用户的 Registration ID。
    • 设置「短信」的「联系标签」时，其值须为11位数字（手机号码格式）
  • 参数说明
    • channel 用户触达通道 ID
    • 结构为 {通道 id:{ 联系标签: 联系方式}}

调用示例

              JOPERATEUserChannel *channel = [[JOPERATEUserChannel alloc] init];
      channel.channels = @{@"通道ID": @{@"联系标签":@"联系方式"}};
      channel.completion = ^(NSInteger errcode, NSString * _Nonnull msg) { };
    [JOPERATEService setUserChannel:channel];

        

设置用户标识

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)identifyAccount:(JOPERATEUserID * )userID;
  • 接口说明:
    • 设置用户标识
  • 参数说明
    • userID 用户标识模型

调用示例

              JOPERATEUserID *userID = [[JOPERATEUserID alloc] init];
    userID.userIDs = @{@"loginID": @"value"};
    [JOPERATEService identifyAccount:userID];

        

获取 CUID

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (NSString * )CUID;
  • 接口说明:
    • 获取运营增长 CUID

调用示例

              [JOPERATEService CUID];

        

设置 UTM 属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)setUtmProperties:(NSDictionary * )property;
  • 接口说明:
    • UTM 属性为预置属性，目前能够设置 UTM 属性为：
      • utm_source 广告系列来源
      • utm_medium 广告系列媒介
      • utm_term 广告系列字词
      • utm_content 广告系列内容
      • utm_campaign 广告系列名称

调用示例

                 [JOPERATEService setUtmProperties:@{@"utm_source":@"value"}];

        

设置静态公共属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)setCommonProperties:(NSDictionary * )property;
  • 接口说明:
    • 设置静态公有属性，后面所有上报事件数据都会包含该属性，该属性保存在本地，设置长期有效。
    • 当事件属性和公共属性重复时，事件属性会覆盖公共属性。
    • key 为 NSString，只能包含数字小写字母下划线，以及以字母开头。
    • value 可以是 NSString/NSNumber/NSSet、NSArray。
    • NSSet、NSArray 中的所有元素必须为 NSString。

调用示例

                 [JOPERATEService setCommonProperties:@{@"key":@"value"}];

        

设置动态公共属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)setDynamicCommonProperties:(NSDictionary<NSString *, id> *(^)(void)) dynamicProperties;
  • 接口说明:
    • 设置动态公有属性，后面所有上报事件数据都会包含该接口返回的属性，该属性仅当次设置有效。
    • 当事件属性和公共属性和动态公共属性三者重复时会按如下优先级进行覆盖，事件属性 > 动态公共属性 > 静态公共属性。
    • key 为 NSString，只能包含数字小写字母下划线，以及以字母开头。
    • value 可以是 NSString/NSNumber/NSSet、NSArray。
    • NSSet、NSArray 中的所有元素必须为 NSString。
    • dynamicProperties block 用来返回事件的动态公共属性。

调用示例

                 [JOPERATEService setDynamicCommonProperties:^NSDictionary<NSString *,id> * _Nonnull{
       return @{@"key":@"value"};
   }];

        

删除某个静态公共属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)unregisterCommonProperty:(NSString * )key;
  • 接口说明:
    • 删除某个静态公共属性

调用示例

                 [JOPERATEService unregisterCommonProperty:@"key"];

        

删除所有的静态公共属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)clearCommonProperties;
  • 接口说明:
    • 删除当前所有的静态公共属性

调用示例

                 [JOPERATEService clearCommonProperties];

        

获取静态公共属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (NSDictionary * )currentCommonProperties;
  • 接口说明:
    • 当前的静态公共属性的副本

调用示例

              NSDictionary* properties = [JOPERATEService currentCommonProperties];

        

设置用户属性

调用该接口前，需要先在控制台创建用户属性，详情参考 创建用户属性。

设置覆盖方式的用户属性

• + (void)set:(NSDictionary * )userinfo completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 这些用户属性的内容用一个 NSDictionary 来存储，其中的 key 是用户属性的名称，必须是 NSString，Value 则是用户属性的内容，只支持 NSString、NSNumber，NSSet、NSArray 这些类型。
    • NSSet 或者 NSArray 类型的 value 中目前只支持其中的元素是 NSString。
    • 如果某个用户属性之前已经存在了，则这次会被覆盖掉；不存在，则会创建。如：用户会员等级。
  • 调用示例:

             [JOPERATEService set:@{@"key":@"value"} completion:^(NSInteger errcode, NSString * _Nonnull msg) {
       
   }];

        

• + (void)set:(NSString * )key to:(id)value completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 设置用户的单个用户属性的内容。
    • 这些用户属性的内容用一个 NSDictionary 来存储，其中的 key 是用户属性的名称，必须是 NSString，Value 则是用户属性的内容，只支持 NSString、NSNumber，NSSet、NSArray 这些类型。
    • NSSet 或者 NSArray 类型的 value 中目前只支持其中的元素是 NSString。
    • 如果某个用户属性之前已经存在了，则这次会被覆盖掉；不存在，则会创建。如：用户会员等级。
  • 调用示例:

             [JOPERATEService set:@"key" to:@"value" completion:^(NSInteger errcode, NSString * _Nonnull msg) {
       
   }];

        

设置仅首次生效的用户属性

• + (void)setOnce:(NSDictionary * )userinfo completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 与 set 接口不同的是，如果该用户的某个用户属性之前已经存在了，会被忽略；不存在，则会创建。如：首次付费时间。
  • 调用示例:

              [JOPERATEService setOnce:@{@"key":@"value"} completion:^(NSInteger errcode, NSString * _Nonnull msg) {
        
    }];

        

设置累加方式的用户属性

• + (void)increment:(NSString * )key by:(NSNumber * )amount completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 给一个数值类型的用户属性增加一个数值，累加所有上报的数据，如累计消费金额。
    • 只能对 NSNumber 类型的用户属性调用这个接口，否则会被忽略, 如果这个用户属性之前不存在，则初始值当做 0 来处理。
  • 调用示例:

              [JOPERATEService setOnce:@{@"key":@"value"} completion:^(NSInteger errcode, NSString * _Nonnull msg) {
        
    }];

        

• + (void)increment:(NSDictionary * )userinfo completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 给多个数值类型的用户属性增加数值，累加所有上报的数据，如累计消费金额。
    • 只能对 NSNumber 类型的用户属性调用这个接口，否则会被忽略, 如果这个用户属性之前不存在，则初始值当做 0 来处理。
  • 调用示例:

              [JOPERATEService increment:@{@"key":@1} completion:^(NSInteger errcode, NSString * _Nonnull msg) {
        
    }];

        

设置追加方式的用户属性

• + (void)append:(NSString * )key by:(NSObject * )content completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 向一个 NSSet 或者 NSArray 类型的属性添加一些值。
    • 如前面所述，这个 NSSet 或者 NSArray 的元素必须是 NSString，否则，会忽略, 同时，如果要 append 的用户属性之前不存在，会初始化一个空的 NSSet 或者 NSArray。
    • 可持续增加该集合元素，元素入库去重处理，若已存在ABC，追加CD，最终为ABCD，如用户点赞的新闻。
  • 调用示例:

              [JOPERATEService append:@"key" by:@[@"value"] completion:^(NSInteger errcode, NSString * _Nonnull msg) {
        
    }];

        

删除用户属性

支持的版本

开始支持的版本： 2.0.0

接口定义

• + (void)unset:(NSString * )key completion:(void (^)(NSInteger errcode, NSString * msg))completion;
  • 接口说明:
    • 删除某个用户属性的全部内容
    • 如果这个用户属性之前不存在，则直接忽略

调用示例

              [JOPERATEService unset:@"key" completion:^(NSInteger errcode, NSString * _Nonnull msg) {
        
    }];

        

计时事件部分

开始事件计时

• + (nullable NSString * )timeKeepingEventStart:(NSString * )event;
  • 接口说明：
    • 若需要统计某个事件的持续时间，先在事件开始时调用 timeKeepingEventStart:"事件名" 记录事件开始时间，该方法并不会真正发送事件。
    • 随后在事件结束时，调用 timeKeepingEventEnd:"事件 ID" with:properties。
  • 调用示例：

              NSString *eventID = [JOPERATEService timeKeepingEventStart:@"key"];

        

结束事件计时

• + (void)timeKeepingEventEnd:(NSString * )eventId with:(nullable NSDictionary * )properties;
  • 接口说明：
    • 结束事件计时，多次调用时，以首次调用为准
  • 调用示例：

              [JOPERATEService timeKeepingEventEnd:eventID with:@{@"key":@"value"}];

        

暂停事件计时

• + (void)timeKeepingEventPause:(NSString * )eventId;
  • 接口说明：
    • 多次调用时，以首次调用为准
  • 调用示例：

              [JOPERATEService timeKeepingEventPause:eventID];

        

恢复事件计时

• + (void)timeKeepingEventResume:(NSString * )eventId;
  • 接口说明：
    • 多次调用时，以首次调用为准
  • 调用示例：

              [JOPERATEService timeKeepingEventResume:eventID];

        

删除事件计时

• + (void)removeTimeKeepingEvent:(NSString * )eventId;
  • 接口说明：
    • 多次调用时，只有首次调用有效
  • 调用示例：

              [JOPERATEService removeTimeKeepingEvent:eventID];

        

清除所有计时事件

• + (void)clearTimeKeepingEvent;
  • 接口说明：
    • 清除所有计时事件
  • 调用示例：

              [JOPERATEService clearTimeKeepingEvent];

        

Demo 接口

获取运营增长开通状态

• + (void)isValid:(void (^)(NSInteger code, NSString * msg))completion;
  • 接口说明：
    • 您的项目是否已经开通了运营增长，code 为 0 位开通。
  • 调用示例：

              [JOPERATEService isValid:^(NSInteger code, NSString * _Nonnull msg) {
        
    }];

        

获取用户数据

• + (void)userData:(void (^)(NSInteger code, NSDictionary<NSString * ,  id> * data))completion;
  • 接口说明：
    • 回调中为用户数据，例如后台注册的用户事件，当前用户的渠道信息，用户标识等等
  • 调用示例：

              [JOPERATEService userData:^(NSInteger code, NSDictionary<NSString *,id> * _Nonnull data) {
        
    }];

        

获取项目信息

• + (void)appInfo:(void (^)(NSInteger code, NSDictionary<NSString * ,  id> * data))completion;
  • 接口说明：
    • 回调中为项目信息
  • 调用示例：

              [JOPERATEService appInfo:^(NSInteger code, NSDictionary<NSString *,id> * _Nonnull data) {
        
    }];

        

数据采集项配置

支持的版本

开始支持的版本： 2.0.8

接口定义

• **+ (void)setCollectControl:(JOperateCollectControl )control;*
  • 接口说明:
    • 数据采集配置。为了确保您使用极光运营增长的良好效果，我们强烈建议您都采集。
  • 参数说明:
    • control: 数据采集项配置类。对应参数设置为NO则不采集，默认为YES。

调用示例

             JOperateCollectControl *control = [[JOperateCollectControl alloc] init];
    control.wifi = YES;
    control.ssid = YES;
    ...
    [JOPERATEService setCollectControl:control];

        

JOPERATEConfig 类

应用配置信息类。以下是属性说明：

JOPERATEUserID 类

用户标识模型类。以下是属性说明：

JOPERATEEventObject 类

自定义事件对象类。所有的字符串属性长度不能超过 256 字节（包括 extra 的 key），以下是属性说明：

JOPERATEUserChannel 类

用户通道模型类。以下是属性说明：
如果不设置或者设置为 nil 则认为不修改，设置为 "" 空字符串的时候认为清空该渠道

JOperateCollectControl 类

数据采集配置类 ，为了确保您使用极光运营增长的良好效果，我们强烈建议您都采集。

数据校验模式

帮助开发者或者运营同学查看已经设置好的数据统计是否成功。

使用方法

在开发者后台进入调试页面，在 App 中配置好调试页面所显示 scheme，然后使用浏览器扫码二维码打开应用，调用 sdk 接口进入开发者模式。进入开发者模式后可以在后台实时查看当前设备的数据上报情况。

• + (void)openDebugMode:(NSURL *)url;
  • 接口说明:
    • 进入数据校验模式
  • 参数说明
    • url 回调的 url，在 Appdelegate 的 application:handleOpenURL: 中调用。不调用此接口 JOPERATE 将无法进入数据校验模式。

调用示例

              // 具体使用方法参考 demo
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {[JOPERATEService openDebugMode:url];
    return YES;
}