在使用前，請先閱讀數據模型的介绍。

1. 整合神策分析 SDK

在 NodeJS 中整合神策分析 SDK，使用神策分析採集並分析用戶數據。

我們推薦使用 npm 管理 Node 模組並取得神策分析 SDK：

npm install sa-sdk-node --save

JS

注：目前只支援 4.x 及以上 Node 版本

2. 注意事項

在 1.0.8 及之後版本中，增加了一個 allowReNameOption 選項，預設值為 true，在此情況下將屬性值和鍵值格式化為下底線風格命名格式，例如：

sa.track('user-id', 'userHappy', {
  '$appVersion': '1.0.0',
  'orderId': '123'
})

//then we get data

{
...
'event': 'user_happy'
'properties': {
  '$app_version': '1.0.0',
  'order_id': '123'
}
...
}

JS

可以透過呼叫 sa.disableReNameOption() 來設定 allowReNameOption 為 false。這種情况下，傳遞預設屬性時，需要傳遞如 $app_version 風格的命名規範的鍵值和屬性值，自定義屬性如 orderId 會被保留當前駝峰的命名風格。預設屬性格式規範請查看數據格式的介绍。

3. 使用 Node SDK

3.1. 取得設定資訊

首先從神策分析的主頁中，取得數據接收的 URL 和 Token（Cloud 版）。

如果使用神策分析 Cloud 服務，需取得的設定資訊為:

數據接收網址，建議使用不帶埠號的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
數據接收網址，帶埠號的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}

如果用戶使用單機版私有部署的神策分析，預設的設定資訊為：

數據接收網址: http://{$host_name}:8106/sa?project={$project_name}（注：神策分析 1.7 及之前的版本，單機版私有部署預設埠號為 8006）

如果用戶使用叢集版私有部署的神策分析，預設的設定資訊為：

數據接收網址: http://{$host_name}:8106/sa?project={$project_name}

其中 {$host_name} 可以是叢集中任意一台機器。

如果私有部署的過程中修改了 Nginx 的預設設定，或透過 CDN 等連接神策分析，則請諮詢相關人員取得設定資訊。

3.2. 匯入 SDK

在程序中初始化的程式碼中建構神策分析 SDK 的執行個體：

ES6:

import SensorsAnalytics from 'sa-sdk-node'

const sa = new SensorsAnalytics()
sa.disableReNameOption()

non-ES6:

var SensorsAnalytics = require('sa-sdk-node')
var sa = new SensorsAnalytics;
sa.disableReNameOption()

sa.submitTo('http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}')

JS

3.3. 追蹤事件

用戶透過 track() 介面記錄事件，對於任何事件，必須包含用戶識別符（distinct_id）和事件名（event_name）兩個參數。同時，用戶可以在 track() 的第三個參數為事件增加自定義事件屬性，在自定義屬性中需要包含 $is_login_id 屬性來說明 distinct_id 是否為登入 ID。以電商產品為例，可以這樣追蹤一次購物行為：

var distinct_id = 'ABCDEF123456'
var properties = {
    // '$time' 屬性是系統預設屬性，傳入 datetime 物件，表示事件發生的時間，如果不填入該屬性，則預設使用系統當前時間
    '$time' : datetime.datetime.now(),
    // '$ip' 屬性是系統預設屬性
    '$ip' : '123.123.123.123',
    // $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
    '$is_login_id' : True,
    // 商品 ID
    'ProductId' : '123456',
    // 商品類別
    'ProductCatalog' : 'Laptop Computer',
    // 是否加入收藏夾，Boolean 型別的屬性
    'IsAddedToFav' : True,
}

// 記錄用戶瀏覽商品事件
sa.track(distinct_id, 'ViewProduct', properties)

var properties = {
    // 用戶 IP 網址
    '$ip' : '123.123.123.123',
    // $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
    '$is_login_id' : True,
    // 商品 ID 列表，list<str> 型別的屬性
    'ProductIdList' : ['123456', '234567', '345678'],
    // 訂單價格
    'OrderPaid' : 12.10,
}

// 記錄用戶訂單付款事件
sa.track(distinct_id, 'PaidOrder', properties)

JS

3.3.1. 系统預設屬性

如前文中範例，事件屬性中以 '$' 開頭的屬性為系統預設屬性，在自定義事件屬性中填入對應 '$' 開頭的屬性值可以覆蓋這些預設屬性：

Distinct$ip - 填入該屬性，神策分析會自動根據 IP 網址解析用戶的省份、城市資訊，該屬性值為 str 型別；
$time - 填入該屬性，神策分析將事件時間設定為屬性值的時間，該屬性值必須為 datetime.datetime 或 datetime.date 型別。請注意，神策分析預設會過濾忽略 365 天前或 3 天後的數據，如需修改請聯繫我們。

關於其他更多預設屬性，請參考數據格式中 '預設屬性' 一節。

3.3.2. 事件公共屬性

特别地，如果某個事件的屬性，在所有事件中都會出現，可以透過 registerSuperProperties() 將該屬性設定為事件公共屬性。例如，應用版本設定為所有事件共有屬性方法如下:

sa.registerSuperProperties({
  $appVersion: '1.0.0',
  env: 'production'
});

JS

成功設定事件公共屬性後，再透過 track() 追蹤事件時，事件公共屬性會被增加進每個事件中。

4. 用戶識別

在伺服器端應用中，神策分析也要求為每個事件設定用戶的 Distinct ID，這有助於神策分析提供更準確的留存率等數據。

對於註冊用戶，推薦使用系统中的用戶 ID 作為 Distinct ID，不建議使用用戶名、Email、手機號碼等可以被修改的資訊。

4.1. 用戶註冊/登入

當同一個用戶的 Distinct ID 發生變化時（一般情况為匿名用戶註冊行為），可以透過 trackSignup() 將舊的 Distinct ID 和新的 Distinct ID 關聯，以確保用戶分析的準確性。例如：

// 匿名 ID 由前端傳過來
var anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

String registerId = "0012345678";
// 用戶註冊/登入時，將用戶註冊 ID 與 匿名 ID 關聯
sa.trackSignup(registerId, anonymousId);

JS

注意，對同一個用戶，TrackSignUp() 一般情況下建議只呼叫一次（通常在用戶註冊時呼叫），用戶登入前後的行為的關聯建議在業務端實現。在神策分析 1.13 版本之前，多次呼叫 TrackSignUp() 時，只有第一次關聯行為是有效的。神策分析 1.13 版本之後提供了多裝置 id 關聯的方法。更詳細的說明請參考標識用戶，並在必要時聯繫我們的技術支援人員。

5. 設定用戶屬性

為了更準確地提供針對人群的分析服務，神策分析 SDK 可以設定用戶屬性，如年齡、性別等。用戶可以在留存分析、分佈分析等功能中，使用用戶屬性作為過濾條件或以用戶屬性作為維度進行多維分析。

使用 profileSet() 設定用戶屬性:

var properties = {
// 設定用戶等級屬性（Level）為 VIP
  'UserLv': 'Elite VIP',
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
  '$is_login_id' : True,
}

sa.profileSet(distinctId, properties);

JS

對於不再需要的用戶屬性，可以透過 profileUnset() 方法將屬性刪除。

用戶屬性中，屬性名稱與屬性值的限制條件與事件屬性相同，詳細說明請參考數據格式。

5.1. 記錄初次設定的屬性

對於只在首次設定時有效的屬性，我們可以使用 ProfileSetOnce() 記錄这些屬性。與 ProfileSet() 介面不同的是，如果被設定的用戶屬性已存在，則這條記錄會被忽略而不會覆蓋已有數據，如果屬性不存在則會自動建立。因此，profileSetOnce() 比較適用於為用戶設定首次啟用時間、首次註冊時間等屬性。例如：

var distinctId = "ABCDEF123456789";

// 設定用戶管道屬性（AdSource）為 "App Store"
sa.profileSetOnce(distinctId, {
  "AdSource": "App Store"
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
  '$is_login_id' : True,

});

// 再次設定用戶管道屬性（AdSource），設定無效，屬性 "AdSource" 的值仍為 "App Store"
sa.profileSetOnce(distinctId, {
   "AdSource": "Search Engine",
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
  '$is_login_id' : True,
});

JS

6. 物品元數據上報

在神策推薦專案中，客戶需要將物品元數據上報，以開展後續推薦業務的開發與維護。神策分析 SDK 提供了設定與刪除物品元數據的方法。

item_id（物品 ID ）與 item_type （物品所屬型別）共同組成了一個物品的唯一標識。所有的 item 系列方法都必須同時指定物品 ID 及物品所屬型別這兩個參數，來完成對物品的操作。

6.1. 設定物品

直接設定一個物品，如果已存在則覆盖。除物品 ID 與物品所屬型別外，其他物品屬性需在 properties 中定義。

物品屬性中，屬性名稱與屬性值限制條件與事件屬性相同，詳細說明請參考數據格式。

// 商品 Type
const itemType = 'book'
// 商品 ID
const itemId = '0321714113'
// 商品資訊
const properties = {
  name: 'C++ Primer',
  price: 31.54,
}
// 增加商品
sa.itemSet(itemType, itemId, properties)

JS

6.2. 刪除一個物品

如果物品不被推薦而需要下線，刪除該物品即可，如不存在則忽略。

除物品 ID 與物品所屬型別外，不解析其他物品屬性。

const itemType = 'book'
// 商品 ID
const itemId = '0321714113'
// 刪除商品
sa.itemDelete(itemType, itemId)// 商品 Type

JS

7. 設定 Node SDK

7.1. 設定數據傳送參數

ES6

import SensorsAnalytics from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

sa.submitTo(url)

JS

採用自定義設定專案

import SensorsAnalytics from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

const submitter = sa.submitTo({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })
// gzip: 是否支援gzip，預設為 true
// mode:
// 三種模式: track（生產環境使用），debug（校驗數據並上傳），dryRun（只校驗數據，不上傳），預設模式是 track
// timeout: http超時，單位毫秒(ms)，預設值為 10s

JS

import SensorsAnalytics, { Submitter } from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

const submitter = new Submitter(url)

sa.disableReNameOption()

sa.subscribe(submitter)

JS

import SensorsAnalytics, { Submitter } from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

const submitter = new Submitter({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })

sa.subscribe(submitter)

JS

7.2. 批量傳送 Batch Submit

WARN 批量傳送不支援 debug 和 dryRun ，會出現 400 錯誤。

7.2.1. 按照數量大包傳送

// Submit when 20 events are tracked
sa.submitTo(url, { count: 20 })

JS

7.2.2. 按時間傳送

// Submit when every 5 seconds
sa.submitTo(url, { timeSpan: 5 * 1000 })

JS

7.2.3. 時間和數據量結合

// Submit every 5 seconds, but also submit immediately if 20 events tracked
sa.submitTo(url, { count: 20, timeSpan: 5 * 1000 })

JS

8. 使用LoggingConsumer

Node SDK 中還提供了 LoggingConsumer ，如果啟用，將不透過 Node 模組進行數據傳送，而將所有數據都寫到本地的 log 檔裡，然後用戶再使用 LogAgent 讀取 log 檔，將數據匯入我們的系統。

WARN 注意在生產環境下使用 pm2 的情況下，需要初始化時增加 pm2Mode(bool)，設定為 true。另外，還需要執行 pm2 install pm2-intercom。

// 初始化 sa 執行個體後，不需要設定數據傳送網址，只需要透過呼叫如下語句，設定 log 檔存放的目錄，這裡建議使用絕對路徑
var customPath = '/Users/user/logs';
sa.initLoggingConsumer(customPath, pm2Mode)

JS

呼叫 LoggingConsumer 初始化後，後續數據傳送仍然呼叫原有模式下的介面，如 track 等，SDK 將自動將數據寫入當前設定的 log 路徑裡面。對應的 SDK 版本最低為 sdk-sa-node@1.0.11 和 sa-sdk-node@1.1.1。

9. 使用NWConsumer

從 1.2.0 版本开始 Node SDK 中還提供了 NWConsumer ，NWConsumer 的主要作用是即時上報數據到 SA 環境中，當網路發生異常的時候會把數據快取在本地，在下次應用啟動的時候會上報快取的數據。

// 初始化 sa 執行個體後，不需要設定數據傳送網址，只需要透過呼叫如下語句，設定 log 檔存放的目錄，這裡建議使用絕對路徑
const cachePath = '/Users/user/cachePath';
const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'
sa.initNWConsumer({
  url: URL, // 數據接收網址
  cachePath: __dirname, // 快取位置
  timeout: 30 * 1000 // 傳送數據超時時間
})

JS

呼叫 NWConsumer 初始化語句後，後續數據傳送仍然呼叫原有模式下的介面，如 track 等，SDK 將傳送失敗的數據寫入當前設定的快取數據庫裡面，並在下次應用啟動的時候會上報快取的數據。對應的 SDK 版本最低為 sdk-sa-node@1.2.0。

10. 更多資訊

更多資訊請連接 GitHub 主頁