本文档所描述的内容属于神策分析的高级使用功能,涉及较多技术细节,适用于对相关功能有经验的用户参考。如果对文档内容有疑惑,请咨询神策值班同学获取一对一的协助。

神策分析 数据采集 一般使用各语言的 SDK 或我们提供的批量或流式数据导入工具来完成。

在一些特殊情况下,如果用户希望实现自己的接入工具,可以参考本文档。

若无特殊需求,建议使用我们的 SDK 或工具来进行数据接入,以避免未知的问题,并方便以后新功能的使用。例如当使用的编程语言没有对应的 SDK 时,可以考虑使用 2023-05-16_14-08-00_.LogAgent v1.13 或其他批量导入工具。

外部数据接入神策分析分为几个步骤:

1.1. 生成数据

在神策分析数据接入过程中,每条数据(包括任何事件行为和用户属性数据)都是一个符合 2022-12-22_16-35-39_.数据格式 v1.13 的 JSON。

例如:

{
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "distinct_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "event": "$AppStart",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F"
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "autoTrack"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
}
JS

当希望一次发送多条数据时,可以构造一个 Json 数组,每个元素是一个完整的 Json。

  • 建议一次最多不超过 50 条数据;
  • 仅发送一条可以使用长度为 1 的 Json 数组。

例如:

[
  {
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "distinct_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "event": "$AppStart",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F"
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "autoTrack"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
  },
  {
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "distinct_id": "your_customer_id",
    "login_id": "your_customer_id", 
    "event": "$SignUp",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_login_id": "your_customer_id" 
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple",
        "age": 18
    }
  }
]
JS

1.2. 编码

本步骤主要是将 1.生成数据 中的 JSONJSON 数组 进行编码。其下几个子步骤需要顺次执行。

  • 请使用 UTF-8 编码;

1.2.1. 进行 Gzip 压缩(可选)

为了优化数据传输,可以先对数据进行 Gzip 压缩。

  • 此为可选步骤,可以不压缩。

1.2.2. 进行 Base64 编码(必须)

为了更好的兼容各种传输方式,需要对数据进行 Base64 编码。若进行了 2.1 进行 Gzip 压缩,则将压缩后的数据进行 Base64 编码;否则直接将要传输的 JSON 或 JSON 数组 进行 Base64 编码。

1.2.3. 进行 UrlEncode 编码(必须)

由于需要兼容数据作为 URL 参数传输,故需要对 2.2 进行 Base64 编码 得到的结果进行 UrlEncode,这个步骤可能是由浏览器或数据发送框架完成的。

1.2.4. 拼装 request

1.2.4.1. 一条 Json 数据

如果处理的是一条 Json 数据,request 格式如下:

data=xxxxx&gzip=1
CODE
  • data:即为 2.3 进行 UrlEncode 得到的编码结果;
  • gzip:是否进行了 Gzip 压缩;

1.2.4.2. 多条 Json 构成的数组

如果是一次发送多条 Json 构成的数组,request 格式如下:

data_list=xxxxx&gzip=1
CODE
  • data_list:即为 2.3 进行 UrlEncode 得到的编码结果;
  • gzip:是否进行了 Gzip 压缩;

1.2.5. 编码例子

本节演示对样例数据进行编码,假设数据已经写入到了 data.json 文件中:

[
  {
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "distinct_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "event": "$AppStart",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F"
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "autoTrack"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple"
    }
  },
  {
    "anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
    "distinct_id": "your_customer_id",
    "login_id": "your_customer_id", 
    "event": "$SignUp",
    "time": 1710407424971,
    "type": "track",
    "identities": {
        "$identity_anonymous_id": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_idfv": "C57174DA-4D5B-4BA7-A7B5-E740B3070C4F",
        "$identity_login_id": "your_customer_id" 
    },
    "lib": {
        "$lib_version": "4.6.2",
        "$lib": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code"
    },
    "properties": {
        "$os": "iOS",
        "$app_version": "1.4.1",
        "$lib_method": "code",
        "$lib_version": "4.6.2",
        "$os_version": "17.2",
        "$lib": "iOS",
        "$manufacturer": "Apple",
        "age": 18
    }
  }
]
JS
  1. 先对数据进行 Gzip 并进行 Base64 编码,在 macOS 下可使用如下命令:

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

    得到结果:

    H4sIAI/QIGYAA+VTTU+DQBC991dsSI9CoC6ueoNWrx7QkzFkC1ucWHY3uwsJMf53+YwFa9NoD0YPXObNeztvePM4Q+i1/hCyKBe8ykWhY0ita2QtfeIRvApsvPJDG4cBsQMS+vYNwW547hJ3iW+ts46bgjbAE/MNKisZNw1pHkgZGarMgBjIWQ14xHOxS/ACXxFvgCrZQJZRNHkZ+iGtlcAA0zXUmWrr8x6o4h9YnChBuimPVmgF3vopt7CejFdX4pIpDYI3kti5cBajVzuKBXfRqEyl3OV5Dna8KS/OmXkWrVlaGHHf7ms0j1RCMrVna0Kf4NFEpOwTfNCs0CN9ctwucsqLDU1MoZhq8DpLW9YbnfVmT5/zShQqTgptRM5UUxv+sciAf9mDpsGPIOMP8s/Ffq/CwdWg33EpbWj/zZHsdNCsTd7lx93Mnt4B6qJXJSIGAAA=
    CODE
  2. 再对数据进行 UrlEncode 编码,如使用 在线工具样例数据 UrlEncode 编码得到:

    H4sIAI%2FQIGYAA%2BVTTU%2BDQBC991dsSI9CoC6ueoNWrx7QkzFkC1ucWHY3uwsJMf53%2BYwFa9NoD0YPXObNeztvePM4Q%2Bi1%2FhCyKBe8ykWhY0ita2QtfeIRvApsvPJDG4cBsQMS%2BvYNwW547hJ3iW%2Bts46bgjbAE%2FMNKisZNw1pHkgZGarMgBjIWQ14xHOxS%2FACXxFvgCrZQJZRNHkZ%2BiGtlcAA0zXUmWrr8x6o4h9YnChBuimPVmgF3vopt7CejFdX4pIpDYI3kti5cBajVzuKBXfRqEyl3OV5Dna8KS%2FOmXkWrVlaGHHf7ms0j1RCMrVna0Kf4NFEpOwTfNCs0CN9ctwucsqLDU1MoZhq8DpLW9YbnfVmT5%2FzShQqTgptRM5UUxv%2BsciAf9mDpsGPIOMP8s%2FFfq%2FCwdWg33EpbWj%2FzZHsdNCsTd7lx93Mnt4B6qJXJSIGAAA%3D
    CODE
  3. 拼装 request:

    gzip=1&data_list=H4sIAI%2FQIGYAA%2BVTTU%2BDQBC991dsSI9CoC6ueoNWrx7QkzFkC1ucWHY3uwsJMf53%2BYwFa9NoD0YPXObNeztvePM4Q%2Bi1%2FhCyKBe8ykWhY0ita2QtfeIRvApsvPJDG4cBsQMS%2BvYNwW547hJ3iW%2Bts46bgjbAE%2FMNKisZNw1pHkgZGarMgBjIWQ14xHOxS%2FACXxFvgCrZQJZRNHkZ%2BiGtlcAA0zXUmWrr8x6o4h9YnChBuimPVmgF3vopt7CejFdX4pIpDYI3kti5cBajVzuKBXfRqEyl3OV5Dna8KS%2FOmXkWrVlaGHHf7ms0j1RCMrVna0Kf4NFEpOwTfNCs0CN9ctwucsqLDU1MoZhq8DpLW9YbnfVmT5%2FzShQqTgptRM5UUxv%2BsciAf9mDpsGPIOMP8s%2FFfq%2FCwdWg33EpbWj%2FzZHsdNCsTd7lx93Mnt4B6qJXJSIGAAA%3D
    CODE

1.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=H4sIAI%2FQIGYAA%2BVTTU%2BDQBC991dsSI9CoC6ueoNWrx7QkzFkC1ucWHY3uwsJMf53%2BYwFa9NoD0YPXObNeztvePM4Q%2Bi1%2FhCyKBe8ykWhY0ita2QtfeIRvApsvPJDG4cBsQMS%2BvYNwW547hJ3iW%2Bts46bgjbAE%2FMNKisZNw1pHkgZGarMgBjIWQ14xHOxS%2FACXxFvgCrZQJZRNHkZ%2BiGtlcAA0zXUmWrr8x6o4h9YnChBuimPVmgF3vopt7CejFdX4pIpDYI3kti5cBajVzuKBXfRqEyl3OV5Dna8KS%2FOmXkWrVlaGHHf7ms0j1RCMrVna0Kf4NFEpOwTfNCs0CN9ctwucsqLDU1MoZhq8DpLW9YbnfVmT5%2FzShQqTgptRM5UUxv%2BsciAf9mDpsGPIOMP8s%2FFfq%2FCwdWg33EpbWj%2FzZHsdNCsTd7lx93Mnt4B6qJXJSIGAAA%3D' \
     'http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}'
CODE

1.4. 其他

  • 如果没有特殊情况,不建议自己实现上面的接入流程,而是使用 SDK 或工具的方式接入数据。
  • 神策分析是异步处理接收的数据,所以发送完成后需要等待片刻才能查询到。
  • 本地反编码一条数据查看内容可以通过:

    UrlDecode > data # 将数据 UrlDecode(这步没有好用的 bash 命令,可以使用在线工具)
    cat data | base64 -d | gzip -d
    CODE