Android_SDK_接入说明文档
一、说明
1.适用范围
热云灵犀产品作为国内多维度的用户行为分析平台，能够更好的帮助客户基于用户数，精细化了解用户、寻找增长点、搭建多维数据分析模型，帮你实现数据驱动。
本文档适用于Android 2.3（API Level 9）及以上的操作系统。
2.统计说明
为了能够在接入过程中保持概念统一，针对通用概念做如下说明：
- 设备
指某台安装了Android应用的终端，例如SAMSUNG Galaxy Note 8、HTC U11、SAMSUNG Galaxy S8等。
- 账号
指用户在某台设备上安装了应用之后，在应用中的唯一标识。
通常用作账号的标识符可以是用户注册应用时的唯一用户名（如邮件地址），也可以是用户注册时自动生成的唯一字符串。
二、接入流程
1.申请APPKEY
1)打开http://io.reyun.com/login.html，使用您的热云灵犀账号进行登录。
2)进入“产品中心”，点击左上方“+新建产品”，完成产品创建，您将获得一串32位的16进制APPKEY；
如果您已经完成产品创建，请在如下位置获取APPKEY：“全部产品按钮”-“对应产品”-APPKEY
3)APPKEY为应用的唯一标识，用于集成到SDK中。
注：为了保证您的数据安全,请勿泄露您的APPKEY。
2.导入SDK
1)前往http://iodoc.reyun.com/sdkwen-dang.html下载SDK压缩包，解压至本地目录。
2)将目录中iosaas1.x.x.jar导入到您的工程目录下的libs文件夹中。
导入方法：在工程目录结构中，右键选择Properties->Java Build Path，点击右侧Libraries选项卡，点击Add JARs按钮在Project/libs目录选择iosaas1.x.x.jar，点击OK导入。
3.接入SDK
详见“三、接入方法说明”
4.测试
1)在开发环境中进行Debug测试，日志TAG为IOSaas：
ReYunConst.DebugMode=true;
注：热云SDK所有API接口的http response均以status：0表示成功，若不成功，会在返回的json里提示详细错误信息。
三、接入方法说明
1.在AndroidManifest.xml文件中添加如下权限
//网络访问权限
<uses-permissionandroid:name="android.permission.INTERNET"/>
//获取网络状态权限
<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE"/>
//获取wifi状态权限
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>
//读取手机IMEI的权限，最好在获得此权限后再初始化sdk（可选），如果缺少此权限，会以AndroidID作为设备唯一标识符
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"/>
//获取gps的权限（可选）。
<uses-permissionandroid:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permissionandroid:name="android.permission.ACCESS_COARSE_LOCATION"/>
//读写sd卡的权限
<uses-permissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permissionandroid:name="android.permission.READ_EXTERNAL_STORAGE"/>
2.初始化热云SDK
- 方法用途
用于应用启动后，初始化热云SDK。报送应用安装或启动事件。
- 使用方法：
调用IOSaas.initWithKeyAndChannelId方法进行初始化。
- 方法接口：
IOSaas.initWithKeyAndChannelId(Context appContext,String appKey,String channelId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| appContext | Context | 是 | 全局应用上下文 | |
| appKey | String | 是 | 创建产品时获得的32位字符长度的APPKEY | |
| channelId | String | 是 | 最长64位 | 用于标识推广渠道，支持英文、数字、下划线，默认填写_default_；分包（应用市场）模式，该值必须与热云后台“广告监”-“推广管理”-“推广活动管理”-新建推广活动（分包）填写的渠道ID一一对应。 |
- 示例代码：
IOSaas.initWithKeyAndChannelId(getApplicationContext(),"8283e21a7484c03edee3d61cc12e93ss","_default_");
3.统计用户注册数据
- 方法用途：
用于用户注册完成，报送应用注册事件。
- 使用方法：
在用户注册完成时调用IOSaas.setRegisterWithAccountID方法。
如果开发者没有自己的用户系统，希望使用用户设备ID作为accountId，直接调用IOSaas.getDeviceId()方法即可。
- 方法接口：
IOSaas.setRegisterWithAccountID(String accountId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| accountId | String | 是 | 最长64位 | 账号唯一标识，支持英文、数字、下划线 |
- 示例代码：
IOSaas.setRegisterWithAccountID(“123456”);
4.统计用户登录数据
- 方法用途：
用于用户登录完成、切换账号时，报送应用登录事件。
- 使用方法：
调用IOSaas.setLoginSuccessBusiness方法。
- 方法接口：
IOSaas.setLoginSuccessBusiness(String accountId);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| accountId | String | 是 | 最长64位 | 账号唯一标识，支持英文、数字、下划线 |
- 示例代码：
IOSaas.setLoginSuccessBusiness(“123456”);
5.统计用户充值成功数据（统计付费以此为准）
- 方法用途：
用于用户充值成功，统计充值数据，所有付费相关分析的数据报表均依赖此方法。
注：前端报送支付有掉单风险，收入数据会出现误差，为确保支付数据准确，建议使用服务器报送支付（请参考“REST”文档）。
- 使用方法：
用户充值成功且后端发货成功后调用IOSaas.setPayment方法。
- 方法接口：
IOSaas.setPayment(String transactionId,String paymentType,String currencyType,float currencyAmount);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| transactionId | String | 是 | 最长64位 | 交易流水号，请确保唯一。 |
| paymentType | String | 是 | 最长16位 | 支付类型，例如支付宝(alipay)，银联(unionpay)，微信支付（weixinpay）,易宝支付（yeepay），paymentType不能填写：FREE（FREE不统计付费） |
| currencyType | String | 是 | 最长3位 | 货币类型，按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 |
| currencyAmount | float | 是 | 最长16位 | 支付的真实货币金额，人民币单位：元 |
- 示例代码：
IOSaas.setPayment(“0062001242”,“alipay”,“CNY”,1000.00f);
6.统计用户自定义事件
- 方法用途：
用于统计用户在应用内的任意行为，如打开某个面板、点击某个Button、参与某个活动等。
- 使用方法：
在自定义用户行为的地方，调用IOSaas.setEvent方法。
- 方法接口：
IOSaas.setEvent(String eventName, Map<String, Object> extra);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| eventName | String | 是 | 最长32位 | 自定义事件名称，支持英文、数字、下划线 |
| extra | Map<String,Object> | 否 | 键值对不能超过80 | extra参数的key支持String类型，不能以“_”开头value支持字符串、数字、日期、布尔类型 |
- 示例代码：
IOSaas.setEvent(“eventName”, extra);
- 使用场景：
示例：使用自定义事件追踪玩家失败情况，记录失败地点、失败原因、失败行程等信息。
Map<String,Object> extra = new HashMap<String,Object>();
extra.put(“place”,”时光湖”); //失败地点
extra.put(“reason”,”误杀”); //失败原因
extra.put(“metre”,100); //失败行程
IOSaas.setEvent(“fail”, extra);
7.统计用户的profile
- 方法用途：
用于统计用户的profile信息。
- 使用方法：
统计用户profile的地方，调用IOSaas.setProfile方法。
- 方法接口：
IOSaas.setProfile(Map<String, Object>dataDic);
- 参数说明：
| 参数 | 类型 | 是否必填 | 长度 | 说明 |
|---|---|---|---|---|
| dataDic | Map<String,Object> | 是 | 通过键值对的形式提交用户profile数据，可使用参数参考如下表格。key支持英文、数字、下划线。value支持字符串、数字、日期、布尔类型。注：以“_”开头的属性为内置属性；自定义属性不可添加“_”。 |
- 用户属性
| 通用属性 | key:value | 数据类型 |
|---|---|---|
| 用户名 | "_name":"李明" | String |
| 昵称 | "_nickname":"小明" | String |
| 生日 | "_birthday":"1988-11-11" | DateTime |
| 性别 | "_gender":"男" | String |
| 婚姻状况 | "_marital_status":"未婚" | String |
| 家乡 | "_hometown":"北京" | String |
| 职业 | "_profession":"程序员" | String |
| 行业 | "_industry":"IT" | String |
| 学校 | "_school":"清华大学" | String |
| 学历 | "_degree":"本科" | String |
| 手机号 | "_tel":"13000000000" | String |
| 身份证号 | "_citizen_id":"330328194812280616" | String |
| 邮箱 | "_email":"[email protected]" | String |
| 微信 | "_wechat":"3782173321" | String |
| 微博 | "_weibo":"dsahiduwqio" | String |
| "_qq":"12345" | String | |
| 第一语言 | "_first_language":"汉语" | String |
| 城市 | "_city":"长沙" | String |
| 省份 | "_province":"湖南" | String |
| 国家 | "_country":"中国" | String |
| 来源 | "_source":"爱奇艺DSP" | String |
| 自定义用户属性 | ||
| 爱好 | "hobby":"音乐" | String |
- 示例代码：
Map<String, Object> dataDic = new HashMap<String, Object>();
profile.put(“_city”,”长沙”); //添加内置属性
profile.put(“hobby”,”音乐”);//添加自定义属性
IOSaas.setProfile(dataDic);
8.退出SDK
- 方法用途：
应用退出时释放sdk占用资源。
- 使用方法：
用于程序退出时调用IOSaas.exitSdk方法。
- 方法接口：
IOSaas.exitSdk();
- 示例代码：
IOSaas.exitSdk();
四、技术支持
如有任何问题，请及时联系我们的技术支持工程师：
技术支持邮箱：[email protected]
技术支持QQ：2785608528