5. 数据接入说明

优质

小牛编辑

135浏览

2023-12-01

开发环境

iOS 系统版本
- 及策SDK目前最低支持iOS 6.0及以上版本,请开发者在嵌入及策SDK的时候将iOS Deployment Target 设置为iOS 6.0 以上.
Xcode 版本
- 及策 SDK1.0 开发环境为 Xcode 7.0或更高版本，开发者在嵌入Jice SDK的时候，请将 xcode 开发环境升级到 7.0或更高版本。

集成 SDK

第1步: Download SDK

登录及策网站https://jice.io/login，点击右下角设置，进入APP信息管理页面，点击iOS SDK按钮下载SDK.

第2步:导入SDK

下载成功后，解压 zip 文件。将解压后的JiceSDKLib文件夹放到需要使用的 App 项目中,添加过程中注意确保在弹出的界面中勾选Copy items into destination group's folder(if needed)，并确保Add To Targets 勾选相应的Target。

第3步: 添加SDK需要的Framework

在需要添加SDK的项目的 Xcode 开发环境中选择 TARGETS-->Build Phases-->Link Binary With Libraries--> + 添加以下framework框架:

libz.1.2.5.td
Security.framework
AdSupport.framework
CoreTelephony.framework
SystemConfiguration.framework

初始化SDK

登录及策网站https://jice.io/login，点击右下角设置，进入APP信息管理页面，获取appkey.

在程序的入口（如 AppDelegate.m ）中引入 JiceSDK.h，并在初始化方法（如 application:didFinishLaunchingWithOptions:）中调用函数shareInstanceWithAppKey:launchOption:config:.

API参数
- config:SDK 配置类，如果你想做一些自定义设置，可以移步自定义SDK配置查看更详细的说明.
- appKey: Jice系统为您分配的应用唯一标识符.
- shareInstance:当成功初始化以后则可以通过shareInstance获取JiceSDK的实例,进行用户行为以及事件或属性的追踪.

// 默认配置上报数据与推送加载不做网络限制,调试模式关闭
JiceConfig *config = [[JiceConfig alloc] init];
NSString *appKey = @"您的AppKey";
[JiceSDK shareInstanceWithAppKey:appKey launchOption:launchOptions config:config]; 
或
NSString *appKey = @"您的AppKey";
[JiceSDK shareInstanceWithAppKey:appKey launchOption:launchOptions config:nil];

恭喜，按照上述步骤，您已经完成了SDK的基础集成，您可以登录Jice系统，进入事件分析，按截图选择启动事件，如果事件总数不为0，则说明，您已经嵌入成功。您可能需要等几分钟才能看到数据。

初始化我方SDK后，默认授权我方进行用户设备信息等隐私数据采集，同时建站方应在用户首次激活APP时添加相关隐私协议声明获取用户同意。

追踪事件

在完成了SDK的基础集成后，您可以调用track:event properties:来进行事件追踪。在进行事件追踪之前，需要您的运营人群在Jice网站定义好需要追踪的事件，并导出代码文件给您，您只需要把事件追踪代码放到事件触发的位置即可。

API 参数
- eventName :事件名称，需为英文，例如示例中@"addtocart".
- properties: 事件属性，属性的key需为英文，例如示例中@{@"productname" : @"tshirt"。

(void)trackEventName:(NSString *)eventName properties:(NSDictionary *)properties;

示例

- (void)trackEventName:(NSString *)eventName properties:(NSDictionary *)properties;
    [[JiceSDK shareInstance] trackEventName:@"addtocart"
                        properties:@{@"productname" : @"tshirt",
                                     @"itemprice" : @"100"}];

如果没有事件属性，您也可以调用如下方法进行追踪。

- (void) trackEventName:(NSString *)eventName;

注意事项：
- 事件名称参数必填，事件属性可选；
- 事件名称 key 和事件属性 key 必须和在Jice系统中设置的相同，否则无法在Jice系统中查看该事件的数据；
- 最多可以支持50个事件，每个事件最多能添加20个属性。

恭喜，按照上述步骤，您已经完成了SDK的事件追踪设置，您可以登录Jice系统，进入事件分析，选择您追踪的事件，如果事件总数不为0，则说明，您已经嵌入成功。您可能需要等几分钟才能看到数据。

追踪用户信息

如果想进一步追踪触发事件的用户信息，您需要调用addUserIndentifier:方法。在进行用户信息追踪之前，需要您的运营人群在Jice网站定义好需要追踪的用户属性，并导出代码文件给您。

当用户注册时候进行调用该接口，传入用户的属性。
当用户编辑更新个人信息后需要调用重新设置用户属性;
API参数
- userid: 用户的唯一标识符，不能为空。
- properties：用户属性, 例如：昵称、性别等，用户属性key须为英文。如果userid和properties[@"id"]值传的不一致，则会用userid覆盖properties[@"id"].

- (void)addUserIndentifier:(NSString *)userid properties:(NSDictionary *)properties;

示例

NSDictionary *profile = @{ @"id" : @"74568544",
                           @"name" : @"Jim",
                           @"gender" : @"Male",
                           @"birthday" : @"1989-10-01",
                           @"email" : @"nono@site.cn",
                           @"levl" : @"no",                              
                           @"phonenumber" : @"13299186743"};   
[[JiceSDK shareInstance] addUserIndentifier:profile[@"id"] properties:profile];

注意事项：
- 用户属性key和在Jice系统中设置的必须一致，否则无法在Jice系统中查看该事件的数据。

恭喜，按照上述步骤，您已经完成了SDK的用户信息追踪设置。您可以登录Jice系统，进入用户分析，当用户注册成功后，您可以在用户列表中看到该用户。您可能需要等几分钟才能看到数据。

应用内推送设置

Jice系统提供强大的应用内消息推送功能，可以将特定的消息推送给特定的人群，在使用这个神奇的功能之前，您需要做如下工作：

第1步: 定义展示推送消息的时机

例如，您是一名电商app的开发人员，您的运营人员希望在用户进入生鲜类商品列表页面时，展示一条推送消息，那么您需要生鲜类商品列表页调用addJiceViewOn:。

API参数
- view:推送消息展示的目标view，推送消息展示窗口的大小依赖于目标view，如果想全屏居中展示，需要将view设置为[UIApplication sharedApplication].keyWindow。
- delegate:如果您想在展示推送或点击推送时做一些额外的操作，例如，点击推送后进入到某个页面，您需要实现JiceViewDelegate中相应的方法，具体见下一步。

- (void)addJiceViewOn:(UIView *)view WithDelegate:(id<JiceViewDelegate>)delegate;

示例

[[JiceSDK shareInstance] addJiceViewOn:[UIApplication sharedApplication].keyWindow WithDelegate:self];

第2步: 定义点击推送消息后的操作

例如，用户点击推送消息后，您希望他进入某个页面，那么您需要实现JiceViewDelegate中的jiceViewDidClick:方法。其中showInfo是在Jice系统中填写的跳转链接。SDK统一作为字符串传输，开发者可以根据需求对其他格式的数据自行解析进行相应处理

当然，你也可以实现JiceViewDelegate中的其他方法，在推送展示和点击的过程中进行其他处理。

@protocol JiceViewDelegate <NSObject>

@optional

- (void)jiceViewWillShow; //推送视图将要显示
- (void)jiceViewDidShow;//推送视图已经显示
- (void)jiceViewDidClick:(NSString *)showInfo;//推送点击后的触发事件。可以根据需要自行解析showInfo
- (void)jiceViewDidDismiss;//推送将要消失
- (void)jiceViewError:(NSError *)error;//为推送错误回调，如果展示推送失败sdk将调用此接口。相关错误码使用枚举JicePushShowError定义.  
@end

在jiceViewError中使用的错误码枚举:

typedef NS_ENUM(NSUInteger, JicePushShowError) {
        JicePushNoData = 1000,              // 没有推送数据
        JicePushIsShowing = 1001,           // 推送正在展示中
        JicePushNoNet = 1002,               // 暂时没有网络
        JicePushIsDownloading = 1003        // 推送正在下载中 
    };

第3步: 集成线上测试模式

我们建议在正式推送消息前，先进行真机测试，这样可以查看推送活动的展示和点击效果是否和预期的一致。

定义URL Scheme，在Xcode中，选择你的工程设置项，选中“TARGETS”一栏，在“info”标签栏的“URL type“添加“URL scheme”.
在Jice网站的管理模块录入该URL Scheme。
在AppDelegate中添加下面两个方法。 url 为通过扫码进入传入的推送活动属性。

// Compatible iOS9
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    [[JiceSDK shareInstance] handleOpenURL:url];
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString*, id> *)options {
    [[JiceSDK shareInstance] handleOpenURL:url];
    return YES;

}

在完成上述步骤后，应用内推送的设置就已经完成了。您或者您的运营人员登录及策系统，通过二维码扫描测试，如果活动流程正常，则表示已经嵌入成功。

自定义SDK设置

SDK还支持一些自定义设置，例如发送监测数据包的网络策略等，如果有相关需求，可以自定义JiceConfig。

trackServer : [可选]私有化部署的服务器上报服务器地址,不设置使用默认地址,例如:http://jice.fw4.me.
pushServer : [可选]私有化部署的推送下发服务器地址,不设置使用默认地址,例如:http://ac.jice.io.
sendCondition: 追踪事件的上报网络策略,可以选择wifi 或者蜂窝网络进行上报,默认值为Wifi+WWAN.
loadCondition: 推送活动展示的网络策略,可以选择wifi 或者蜂窝网络进行上报,建议使用Wifi+WWAN方式.
sessionInterval: 应用在后台到前台的切换计算为有效启动的时间间隔，单位为秒，默认设置为0，如果设置为 10 即前后台切换时间大于 10s 才算为一次新的启动.
isDebugMode: 调试模式，设置为true时，当有监测数据发送时，可以在控制台查看日志。
isAlreadyActivated : [可选]设备已激活标示,标示用户是否在SDK 使用前已经激活过设备,开发者可以自己传入避免与旧数据冲突,连续计算激活数据,YES则不重复统计激活数据,默认NO

JiceConfig *config = [[JiceConfig alloc] init];
// 事件发送网络条件
config.sendCondition = JiceNetworkConditionWWAN | JiceNetworkConditionWifi;
// 推展示网络条件
config.loadCondition =  JiceNetworkConditionWWAN | JiceNetworkConditionWifi;
//有效启动时间间隔，单位为秒
config.sessionInterval = 15;
//测试模式选择
config.isDebugMode = YES;