本文件所描述的內容屬於神策分析的高級使用功能，涉及較多技術細節，適用於對相關功能有經驗的用戶參考。如果對文件內容有疑惑，請諮詢您的數據諮詢顧問取得一對一的協助。

神策分析 數據採集 一般使用各語言的 SDK 或我們提供的批量或流式數據匯入工具來完成。

在一些特殊情況下，如果用戶希望實作自己的接入工具，可以參考本文件。

若無特殊需求，建議使用我們的 SDK 或工具來進行數據接入，以避免未知的問題，並方便以後新功能的使用。例如當使用的程式語言沒有對應的 SDK 時，可以考慮使用 LogAgent 或其他批量匯入工具。

外部數據接入神策分析分為幾個步驟：

1. 產生數據

在神策分析數據接入過程中，每條數據（包括任何事件行為和用戶屬性數據）都是一個符合 數據格式 的 JSON。

例如：

{
    "distinct_id":"2b0a6f51a3cd6775",
    "time":1434556935000,
    "type":"track",
    "event":"ViewProduct",
    "properties":{
        "$manufacturer":"Apple",
        "$model":"iPhone5,2",
        "$os":"iOS",
        "$os_version":"7.0",
        "$app_version":"1.3",
        "$wifi":true,
        "$ip":"180.79.35.65",
        "$province":"湖南",
        "$city":"長沙",
        "$screen_width":320,
        "$screen_height":640,
        "product_id":12345,
        "product_name":"蘋果",
        "product_classify":"水果",
        "product_price":14
    }
}
JS

當希望一次傳送多條數據時，可以建構一個 Json 陣列，每個元素是一個完整的 Json。

  • 建議一次最多不超過 50 條數據；
  • 僅傳送一條可以使用長度為 1 的 Json 陣列。

例如：

[
    {
        "distinct_id":"2b0a6f51a3cd6775",
        "time":1434556935000,
        "type":"track",
        "event":"ViewProduct",
        "properties":{
            "product_name":"蘋果",
            "product_classify":"水果",
            "product_price":14
        }
    },
    {
        "distinct_id":"12345",
        "type":"profile_set",
        "time":1435290195610,
        "properties":{
            "Age":33,
            "IncomeLevel":"3000~5000"
        }
    }
]
JS

2. 編碼

本步驟主要是將 1.產生數據 中的 JSON 或 JSON 陣列 進行編碼。其下幾個子步驟需要依序執行。

  • 請使用 UTF-8 編碼格式；

2.1. 進行 Gzip 壓縮（可選）

為了優化數據傳輸，可以先對數據進行 Gzip 壓縮。

  • 此為可選步驟，可以不壓縮。

2.2. 進行 Base64 編碼（必須）

為了更好的相容各種傳輸方式，需要對數據進行 Base64 編碼。若進行了 2.1 進行 Gzip 壓縮，則將壓縮後的數據進行 Base64 編碼；否則直接將要傳輸的 JSON 或 JSON 陣列 進行 Base64 編碼。

2.3. 進行 UrlEncode 編碼（必須）

由於需要相容數據作為 URL 參數傳輸，故需要對 2.2 進行 Base64 編碼 得到的結果進行 UrlEncode，這個步驟可能是由瀏覽器或數據傳送框架完成的。

2.4. 拼裝 request

2.4.1. 一條 Json 數據

如果處理的是一條 Json 數據，request 格式如下：

data=xxxxx&gzip=1
CODE
  • data：即為 2.3 進行 UrlEncode 得到的編碼結果；
  • gzip：是否進行了 Gzip 壓縮；

2.4.2. 多條 Json 構成的陣列

如果是一次傳送多條 Json 構成的陣列，request 格式如下：

data_list=xxxxx&gzip=1
CODE
  • data_list：即為 2.3 進行 UrlEncode 得到的編碼結果；
  • gzip：是否進行了 Gzip 壓縮；

2.5. 編碼例子

本節示範對範例數據進行編碼，假設數據已經寫入到了 data.json 檔案中：

[
    {
        "distinct_id":"2b0a6f51a3cd6775",
        "time":1434556935000,
        "type":"track",
        "event":"ViewProduct",
        "properties":{
            "product_name":"蘋果",
            "product_classify":"水果",
            "product_price":14
        }
    },
    {
        "distinct_id":"12345",
        "type":"profile_set",
        "time":1435290195610,
        "properties":{
            "Age":33,
            "IncomeLevel":"3000~5000"
        }
    }
]
JS

  1. 先對數據進行 Gzip 並進行 Base64 編碼，在 Linux 下可使用如下命令：

    cat data.json | gzip | base64 -w 0
    CODE

    得到結果：

    H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD+VsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO+Zl5yfm+oDDMwcoJ3GwKCvA4W/EronuGIBDY0g6OEBAAA=
    CODE

  2. 再對數據進行 UrlEncode 編碼，如使用 線上工具 範例數據 UrlEncode 編碼得到：

    H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
    CODE

  3. 拼裝 request：

    gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
    CODE

3. 傳送數據

即將編碼後的數據傳送到神策分析接收數據的 API。

API 網址：

如果使用神策分析 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 等連接神策分析，則請諮詢相關人員取得設定資訊。

例如，以 Cloud 服務為例，使用 curl 傳送：

curl -v \
     --data 'gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d' \
     'http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}'
CODE

4. 其他

  • 如果沒有特殊情況，不建議自己實作上面的接入流程，而是使用 SDK 或工具的方式接入數據。
  • 神策分析是異步處理接收的數據，所以傳送完成後需要稍待片刻才能查詢到。

  • 本地解碼一條數據查看內容可以透過：

    UrlDecode > data # 將數據 UrlDecode（這步沒有好用的 bash 命令，可以使用線上工具）
cat data | base64 -d | gzip -d
    CODE