# APICloud SDK

## **APICloud SDK 使用说明**

> #### *在使用前，请先阅读*[*数据模型*](https://54td.gitbook.io/shence/technical_guide/data_import/data_model)*的介绍。*

## **概述**

SensorsAnalyticsAPICloudSDK 封装了 Sensors Analytics 数据统计 Android & iOS SDK，使用此模块可进行用户行为数据采集。

神策分析，是针对企业级客户推出的深度用户行为分析产品，支持私有化部署，客户端、服务器、业务数据、第三方数据的全端采集和建模，驱动营销渠道效果评估、用户精细化运营改进、产品功能及用户体验优化、老板看板辅助管理决策、产品个性化推荐改造、用户标签体系构建等应用场景。作为 PaaS 平台支持二次开发，可通过 BI、大数据平台、CRM、ERP 等内部 IT 系统，构建用户数据体系，让用户行为数据发挥深远的价值。

#### 使用此模块需要在 config.xml 文件中配置相应的 feature

配置示例：

```markup
    <feature name="sensorsAnalyticsAPICloudSDK">
        <param name="serverURL" value="数据接收地址URL"/>
        <param name="debugMode" value="debugOff"/>
        <param name="enableAutoTrack" value="true"/>
        <param name="downloadChannel" value="应用宝" />
        <param name="enableLog" value="false"/>
    </feature>
```

配置说明：

* feature 名称：`sensorsAnalyticsAPICloudSDK`
* param 参数
  * serverURL：(必填项，如果有特殊字符 `&` ，使用`&amp;`) 数据接收地址 URL。
  * debugMode：(必填项) Debug 模式，有三种模式：
    * `debugOff` - 关闭 Debug 模式，发版 App 时使用此模式
    * `debugAndTrack` - 打开 Debug 模式，校验数据，并将数据导入神策分析系统中
    * `debugOnly` - 打开 Debug 模式，校验数据，但不进行数据导入
  * enableAutoTrack：(可选项) 是否采集 App 启动、App 退出事件，传入字符串 true 表示采集启动、退出事件
  * downloadChannel：(可选项) App 的下载渠道，配置此参数时，会触发 App 安装激活事件（AppInstall），下载渠道会存储在 DownloadChannel 字段中
  * enableLog：(可选项) 是否开启调试日志，传入字符串 true 表示开启调试日志。

注意：正式发布 App 时请将 debugMode 指定成 \`debugOff\` 模式！

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **login**

设置当前用户的 loginId

login({params})

**params**

loginId：

* 类型：字符串
* 描述：(必填项)用户的登录id，不能为空，且长度不能大于255

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.login({
    loginId: '123456'
});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **registerSuperProperties**

设置公共属性，设置之后，之后触发的事件会带上设置的公共属性

registerSuperProperties({params})

**params**

properties：

* 类型：json 格式
* 描述：(必填项)公共属性，属性名需要满足一般变量的命名规则

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.registerSuperProperties({properties:{ PlatformType:"Android"}});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **track**

track 事件。

track({params})

**params**

event：

* 类型：字符串
* 描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

properties：

* 类型：json 格式
* 描述：(选填项)事件属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.track({
    event:'ViewProduct',
    properties:{
       ProductID:123456,
       ProductCatalog:'Laptop Computer',
       IsAddedToFav: false
    }
});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **trackTimerStart**

事件计时开始，需要和 `trackTimerEnd` 成对使用。

trackTimerStart({params})

**params**

event：

* 类型：字符串
* 描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.trackTimerStart({event:'ViewPage'});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **trackTimerEnd**

trackTimerEnd 计时结束，并触发事件，事件时长记录在 event\_duration 字段中。计时开始和计时结束，所对应的 event 事件名必须一致。

trackTimerEnd({params})

**params**

event：

* 类型：字符串
* 描述：(必填项)事件名称，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

properties：

* 类型：json 格式
* 描述：(选填项)事件属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.trackTimerEnd({
    event:'ViewPage',
    properties:{
       pageID:"111"
    }
});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **profileSet**

profileSet 设置用户属性。

profileSet({params})

properties：

* 类型：json 格式
* 描述：(选填项)用户属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.profileSet({
    properties:{
       sex:"男"
    }
});
```

**可用性**

iOS 系统，Android 系统

可提供的1.2.0及更高版本

### **profileSetOnce**

profileSetOnce 设置用户首次属性。

profileSetOnce({params})

properties：

* 类型：json 格式
* 描述：(选填项)用户属性，名称需要满足一般变量的命名规则，即不能以数字开头，且只包含：大小写字母、数字、下划线和$

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
sa.profileSet({
    properties:{
       firstCharge:100
    }
});
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本

### **getDistinctId**

getDistinctId 获取当前用户的 distinctId ，如果用户未登录时，返回值为 匿名 ID ；登录（调用login）后，返回值为 登录 ID 。

getDistinctId()

* 返回值类型：String 字符串

**示例代码**

```javascript
var sa = api.require('sensorsAnalyticsAPICloudSDK');
var distinctId = sa.getDistinctId();
```

**可用性**

iOS 系统，Android 系统

可提供的 1.2.0 及更高版本