[TOC]
## [簡介](#簡介)
使用本模塊，你不僅可以精準統計每個分發渠道所獲取的新增用戶、活躍用戶、留存率等指標，還可以自定義事件來深度追蹤用戶的使用細節、用戶屬性以及行為特征，直觀解讀用戶的操作流程，為業務分析和用戶體驗優化獲取最真實的樣本數據。
## [特性](#特性)
* 該 SDK 可以使用在 Web 頁面及 WebApp 等場景中，兼容 IE8+，各種移動端瀏覽器，及各種 WebView，包括 Phonegap、Cordova 和微信的 WebView。
+
* 使用簡單，功能強大。只需要加載，實例化之后，SDK 既可以自動統計，LeanCloud 的后臺會自動來分析，最終可以在應用的「分析」中看到諸如訪問時長、用戶增長、用戶留存率和實時在線用戶量等各種統計數據。
+
* 支持 WebApp，支持 Web 前端路由，完全自動統計。
+
## [通過 bower 安裝](#通過_bower_安裝)
~~~
bower install leancloud-analytics --save
~~~
安裝之后，頁面直接加載 bower_components/leancloud-analytics/src/AV.analytics.js 即可。?[什么是 bower ?](http://bower.io/)
## [Github 倉庫地址](#Github_倉庫地址)
可以直接通過 Github 倉庫使用，也可以通過 Github 給我們提出您的建議
Github 倉庫地址：[https://github.com/leancloud/js-analytics-sdk](https://github.com/leancloud/js-analytics-sdk)
Release 地址:?[https://github.com/leancloud/js-analytics-sdk/releases](https://github.com/leancloud/js-analytics-sdk/releases)
## [Demo 及示例代碼](#Demo_及示例代碼)
如果您覺得一點點閱讀文檔較慢，可以直接看我們的?[Demo 代碼](https://github.com/leancloud/js-analytics-sdk/tree/master/demo)，并且下載自己運行一下試試看。
1
~~~
// 最簡的示例代碼，請換成自己的 appId 和 appKey
var appId = 'csXFgnEzBkodigdDUARBrEse-gzGzoHsz';
var appKey = 'K2CE4ChmGnUwI8mMBgTRHw7y';
// 實例化統計分析功能（注意：實例化后，SDK 會自動開始統計 PV、UV、停留頁面時長等信息）
var analytics = AV.analytics({
// 設置 AppId
appId: appId,
// 設置 AppKey
appKey: appKey,
// 你當前應用或者想要指定的版本號（自定義）
version: '1.8.6',
// 你當前應用的渠道或者你想指定的渠道（自定義）
channel: 'weixin'
});
// 發送自定義的統計事件
analytics.send({
// 事件名稱
event: 'test-event-name',
// 事件屬性，任意數據
attr: {
testa: 123,
testb: 'abc'
},
// 該事件持續時間（毫秒）
duration: 6000
}, function(result) {
if (result) {
console.log('統計數據發送成功！');
}
});
~~~
## [方法文檔](#方法文檔)
### [全局命名空間](#全局命名空間)
LeanCloud JavaScript 相關 SDK 都會使用「AV」作為命名空間。
### [AV.analytics(options)](#AV_analytics_options_)
描述：配置一個統計分析功能，實例化一個 analyticsObject 可以來做后續操作。通過該方法實例化之后，SDK 會自動記錄頁面時間、一次訪問的時間、標記不同用戶等數據，LeanCloud 服務端會每天處理一次所有統計數據，自動計算出你想要的關鍵數據。
參數：
* options {Object} （必須） 配置統計分析中所需的參數。其中包括：
| 參數 | 類型 | 約束 | 說明 |
| --- | --- | --- | --- |
| appId | String | 必須 | 應用的 AppId，在「控制臺」-「設置」-「基本信息」中可以查看。 |
| appKey | String | 必須 | 應用的 AppKey |
| version | String | 可選 | 可以設置一個版本號，可以是當前應用的版本，完全自定義。 |
| channel | String | 可選 | 渠道信息，可以設置一個渠道，完全自定義，比如微信、微博等。 |
返回：{Object} 返回 analyticsObject，可以做后續的方法，支持鏈式。
例子：
~~~
var appId = 'csXFgnEzBkodigdDUARBrEse-gzGzoHsz';
var appKey = 'K2CE4ChmGnUwI8mMBgTRHw7y';
var analytics = AV.analytics({
appId: appId,
appKey: appKey,
// 你當前應用或者想要指定的版本號（自定義）
version: '1.8.6',
// 你當前應用的渠道或者你想指定的渠道（自定義）
channel: 'weixin'
});
~~~
### [AV.analytics.version](#AV_analytics_version)
描述：獲取當前 SDK 的版本信息
返回：{String} 返回當前版本
例子：
~~~
console.log(AV.analytics.version); // 0.0.1
~~~
### [analyticsObject.send(options, callback)](#analyticsObject_send_options__callback_)
描述：發送自定義事件，可以用來監測用戶行為，或者做其他相關統計。
參數：
* options {Object} （必須）發送數據的配置，具體參數包括：
| 參數 | 類型 | 約束 | 說明 |
| --- | --- | --- | --- |
| event | String | 必須 | 事件的名稱 |
| attr | Object | 可選 | 事件所攜帶的數據，可以是任意的 JSON，完全自定義 |
| duration | Number | 可選 | 該事件持續的時間，單位是毫秒 |
* callback {Function}（可選）自定義發送成功或者失敗后，會觸發的回調函數
返回：{Object} 返回 analyticsObject，可以做后續的方法，支持鏈式。
例子：
~~~
// 最簡的示例代碼，請換成自己的 appId 和 appKey
var appId = 'csXFgnEzBkodigdDUARBrEse-gzGzoHsz';
var appKey = 'K2CE4ChmGnUwI8mMBgTRHw7y';
// 實例化統計分析功能
var analytics = AV.analytics({
appId: appId,
appKey: appKey,
version: '1.8.6',
channel: 'weixin'
}).send({
// 事件名稱
event: 'test-event-name',
// 事件屬性，任意數據
attr: {
testa: 123,
testb: 'abc'
},
// 該事件持續時間（毫秒）
duration: 6000
}, function(result) {
if (result) {
console.log('統計數據發送成功！');
}
});
~~~
### [analyticsObject.send(eventList, callback)](#analyticsObject_send_eventList__callback_)
描述：發送自定義事件，可以用來監測用戶行為，或者做其他相關統計。
參數：
* eventList {Array} （必須）發送事件列表，每個事件單元的說明，請參考上一個 send 方法的 options 選項；
+
* callback {Function}（可選）自定義發送成功或者失敗后，會觸發的回調函數
+
返回：{Object} 返回 analyticsObject，可以做后續的方法，支持鏈式。
例子：
~~~
// 最簡的示例代碼，請換成自己的 appId 和 appKey
var appId = 'csXFgnEzBkodigdDUARBrEse-gzGzoHsz';
var appKey = 'K2CE4ChmGnUwI8mMBgTRHw7y';
var eventList = [
{
// 事件名稱
event: 'test-event-name',
// 事件屬性，任意數據
attr: {
testa: 123,
testb: 'abc'
},
// 該事件持續時間（毫秒）
duration: 6000
},
{
event: 'daasdfname',
duration: 2100
}
];
// 實例化統計分析功能
var analytics = AV.analytics({
appId: appId,
appKey: appKey,
version: '1.8.6',
channel: 'weixin'
}).send(eventList, function(result) {
if (result) {
console.log('統計數據發送成功！');
}
});
~~~
## [數據時效性](#數據時效性)
在控制臺的?分析?頁面中，有些報告可以展示實時數據，有些報告則依靠內部離線數據進行分析，因此有時你會看不到當天的數據。
如果當前頁面中存在?日期選擇?選項（通常在頁面右上角），你可以以此判斷當前的統計結果是否有延遲。如果?結束日期?顯示為?當日日期?或在其下拉菜單中有「今日」選項，即為實時數據；反之則為離線數據（如下圖所示），要推遲一天才能看到當日的情況。
