You need to enable JavaScript to run this app.
导航
增长分析（私有化）
  • 文档首页
    • /增长分析（私有化）/数据分析与治理/数据管理/数据输出/数据输出
数据输出
最近更新时间：2025.03.05 17:05:27首次发布时间：2022.07.25 14:11:16
我的收藏
有用
有用
无用
无用

背景信息

应用场景

如果您需要将Finder-SDK采集的埋点数据实时推送到目标地址（例如您的业务数仓），数据输出模块可为您实现。

使用限制

细分项目

限制说明

支持的环境

  • 私有化环境：4.1.0版本（含）后开始支持。

数据输出方式

当前私有化环境支持实时与离线传输数据。实时与离线数据传输的主要流程如下。

  • 实时传输（私有化）

当前实时传输支持通过“Webhook”渠道实现数据实时触达。

  • 离线传输（私有化）

私有化4.6.1（含）之后支持在实时数据传输的基础上，将行为数据一次性或定时离线导出至FTP/SFTP，实现离线数据输出。
如您有其他数据传输的场景需求，可联系您的客户成功经理。

操作步骤（私有化）

前提条件

细分

前提条件

DataFinder侧

数据接收侧

  • 您需要配置完成接收传输数据的接收端。
    • 对于实时传输场景，您需要准备一个Webhook接收端，明确好接收数据的规则（例如接收数据时是否需要鉴权等）。
    • 对于离线传输场景，您需要准备一个用于接收数据的FTP/SFTP服务器，并获取到服务器的连接信息（服务器地址、鉴权信息等）。
  • 完成白名单配置：如果接收端有白名单限制，需将传输数据的Finder服务地址添加到白名单中。
    • 在私有化环境中，如果接收服务是在外网，需要配置私有化机器的出口ip。

创建数据输出任务

  1. 登录DataFinder控制台后，单击顶部导航栏的数据管理>数据输出>数据输出，进入数据输出页面。
    Image

    说明

    如果您无法在应用管理列表找到“数据输出”入口，请联系您的管理员为您开通权限。（权限配置入口：集团设置-角色管理-增长分析-配置功能权限）

  2. 单击页面右上角的新建任务，配置数据输出任务详情，完成后单击确定。

实时任务

实时任务用于实时转发行为数据。任务的配置详情如下。
Image

  1. 配置基本信息。

    参数

    参数说明

    任务名称

    您可以自定义名称，例如XX产品埋点数据推送。

    应用

    选择需要传输哪个应用采集到的数据至目标地址。

    任务类型

    当前私有化环境支持实时、离线-单次、离线-每日例行三种任务类型。
    如果您希望数据被SDK采集上报后即实时传输至目标地址，可选择任务类型为实时。

    输出内容

    配置分发到目标地址的数据内容，支持配置为：

    • 原始上报数据：即SDK采集上报的原始数据，数据被SDK采集上报后30秒内送达目标地址。
    • 事件表数据：SDK采集上报的数据经DataFinder处理后落库存储的事件表数据。数据被SDK采集上报后10分钟内送达目标地址。
      • 因原始数据落库时有数据处理过程，因此分发时间相较于原始上报数据会有延时。
      • 采集的原始数据如果不符合DataFinder的落库数据规范要求，则这部分原始数据不落表（例如属性数据类型不一致），也就不会被分发至目标地址。

    注意

    实时数据输出启动数据传输时，部分数据还未落库，例如：IP解析省份&城市等需要二次解析的数据；且实时输出传输不包含profile（用户数据）和item（业务对象） API上报的数据。因此如果您需要接收此类数据时，建议使用离线传输任务。

  2. 数据连接配置。

    参数

    参数说明

    连接协议

    默认选择HTTP

    接入方式

    默认选择Webhooks

    Webhook URL

    配置分发的Webhook URL地址。格式示例：http://localhost:6666/payload。http/https均可支持。

    注意

    • 一个数据分发任务仅支持填写一个URL地址，如有多个地址可创建多个任务。
    • 在私有化环境中，如果接收服务是在外网，需要配置私有化机器的出口ip。

    Headers

    您需要根据接收端对数据发送的Webhook要求，配置Webhook Headers，支持置多项Headers。
    例如，接收端要求配置鉴权信息，您可将鉴权信息配置在Headers中，后续DataFinder传输数据时会带上此处配置的Headers信息。

    测试接入连接

    您可单击测试接入连接测试是否与webhook端是联通状态。只有经过连接校验的任务方可被创建。

  3. 配置数据管理。

    说明

    私有化4.4.1（含）后新增过滤条件，可以根据事件和属性规则组合，选定分发的数据范围。

    Image

    参数

    参数说明

    添加事件

    配置需要分发到目标地址的事件列表。事件列表为包含逻辑，即仅选定的事件将会被分发。

    事件属性添加规则

    对已添加的事件通过事件属性进行过滤，即仅在事件列表范围内，且满足事件属性规则的数据才会被分发。

离线任务

离线任务：用于批量导出历史行为数据。任务的配置详情如下。
Image

  1. 配置基本信息。

    参数

    参数说明

    任务名称

    您可以自定义名称，例如XX产品埋点数据推送。

    应用

    选择需要传输哪个应用采集到的数据至目标地址。

    任务类型

    当前私有化环境支持实时、离线-单次、离线-每日例行三种任务类型。
    如果您希望数据被SDK采集上报后,离线批量传输至目标地址，可选择任务类型为离线-单次或离线-每日例行。

    输出内容

    离线导出时只能选择行为数据。
    禁用或者不符合数据规范导致没有落库的数据，不会传输至目标地址。

    离线时间范围/离线结束时间

    根据任务类型选择配置：

    • 离线-单次任务：配置单次传输时间范围，DataFinder会在任务创建完成后的T+1天开始传输这个时间范围内的数据。
    • 离线-每日例行任务：配置例行离线传输的时间结束时间，DataFinder会在任务创建完成后的T+1天开始传输数据，到结束时间后停止数据传输。

    注意

    离线任务最多支持一次性导出T-30天的历史数据。

  2. 数据连接配置。

    参数

    参数说明

    连接协议

    选择FTP或SFTP。

    接入方式

    默认选择标准版本。

    连接地址

    配置FTP/SFTP服务器地址，以IP:端口格式填写。
    示例：XXX.168.0.1:8080

    鉴权方式

    默认不鉴权。
    如服务器设置了用户名与密码用于鉴权连接，可选PASSWORD模式，输入服务器账号密码。

    远端存储路径

    即具体存储的目录。

    测试接入连接

    您可单击测试接入连接测试是否与FTP/SFTP服务器是联通状态。只有经过连接校验的任务方可被创建。

  3. 配置数据管理。

    说明

    私有化4.4.1（含）后新增过滤条件，可以根据事件和属性规则组合，选定分发的数据范围。

    Image

    参数

    参数说明

    添加事件

    配置需要分发到目标地址的事件列表。事件列表为包含逻辑，即仅选定的事件将会被分发。

    事件属性添加规则

    对已添加的事件通过事件属性进行过滤，即仅在事件列表范围内，且满足事件属性规则的数据才会被分发。

数据输出结果确认

任务创建成功后预计10分钟内生效。您可以在10分钟之后查看接收端是否正常接收到了数据。

查看/启停/编辑任务

您可以在数据输出的任务列表页面查看所有数据输出任务：

  • 任务创建后默认状态为“执行中”，此时数据正常分发。如果您需要停止数据输出，可以点击“停止”将状态改为“已停用”。任务切换状态预计10分钟内生效。
    Image
  • 执行中任务不可编辑或删除，如果您需要修改数据传输地址,请先将执行中的任务停用，编辑后重新启用即可。
  • 针对离线类型的任务，可查看子任务的最新执行状态。
    Image
    • 任务执行时间为目前传输任务对应的行为数据时间范围，默认以日粒度切分。
    • 最后推送时间代表任务执行的时间，任务最新状态即子任务是否完成推送，建议重点关注失败状态的任务，尝试重新推送。
    • 我们将额外统计失败条数，如您发现失败量过多时，也可直接在操作栏便捷重新推送。

数据格式说明

实时传输：分发数据示例

一次请求的body是一个json array，里面会包含1-50条事件。

[{
  "user": {
    "user_unique_id": "mock_user_unique_id",
    "user_id": 6934486383370142000,
    "user_type": 13,
    "user_is_auth": false,
    "user_is_login": false,
    "is_upgrade_user": false,
    "web_id": 6934486383370142000,
    "ip_addr_id": 0,
    "ssid": "acf3dd8f-7a18-42b1-996b-56a20156249c"
  },
  "header": {
    "app_id": 10000010,
    "app_name": "mock_web",
    "access": "",
    "client_ip": "221.122.122.122",
    "carrier": "",
    "os_name": "mac",
    "os_version": "10_15_5",
    "product_id": 107,
    "product_name": "default_to_b",
    "custom": "{\"app_id\":10000010,\"screen_width\":1440,\"screen_height\":900}",
    "trace_id": "16015901108710420012361360828522",
    "language": "zh-CN",
    "device_model": "Macintosh",
    "resolution": "1440x900",
    "width": 1440,
    "height": 900,
    "timezone": 8,
    "tz_offset": -28800,
    "platform": "web",
    "browser": "Chrome",
    "browser_version": "78.0.3904.108",
    "referrer": "",
    "referrer_host": ""
  },
  "params": "{\"app_name\":\"mock_web\",\"referrer\":\"\",\"user_unique_id\":\"\",\"time\":1601590110322,\"is_bav\":1,\"title\":\"测试页面\",\"event_index\":1616590857270,\"url\":\"http://demo.com.cn/product/list\",\"url_path\":\"/product/list\"}",
  "event_name": "predefine_pageview",
  "session_id": "aa7b79a1-4e27-44fe-bed8-56adfffddc07",
  "datetime": 1601590110,
  "server_time": 1601590110,
  "rnd": "ne0000",
  "log_type": "mario_event",
  "local_time_ms": 1601590110322
},{其他事件},{其他事件}]

实时传输：单个事件具体字段说明

//一个事件
Event {
          User user //user内格式见下面
          Header header //header格式见下面
          string params  // 事件参数,单层json map,需要dump成字符串
          string event_name  // 事件名
          uint64 event_id  // 事件id
          string session_id
          uint64 datetime  // 事件发生时间戳(秒)
          uint64 server_time  // 日志到达服务器时间
          string log_type 
          uint64 local_time_ms    // 事件发生时间戳(毫秒)
}

//事件内user字段

User {
     string user_unique_id  // 用户唯一id
     uint64 user_id  // 用户id
     uint32 user_type  // 用户类型
     bool user_is_auth  // 是否授权
     bool user_is_login  // 是否登录
     uint64 device_id  // 设备id
     string open_udid  // openudid
     string udid  // udid
     string client_udid  // 客户端自己生成的设备id
     string mc    // 设备mac地址
     string build_serial    // 硬件序列号
     string serial_number    // 序列号
     string idfa    // idfa
     bool is_upgrade_user    // 是否app升级用户
     uint64 web_id 
     uint64 ip_addr_id 
     string ssid 
     string idfv 
     string oaid 
     string cdid 
     string user_unique_id_type    // user_unique_id字段口径，tob场景使用，为空或default_user_unique_id_type为默认口径
}

//事件内header字段

Header {
     string headers  // 自定义header,单层json map,需要dump成字符串
     uint32 app_id  // app_id
     string app_name  // app名称
     string app_version  // app版本
     string app_package  // app包名称
     string display_name  // app名称
     string app_channel  // app分发渠道
     string access  // 网络访问类型
     string client_ip  // 客户端ip
     string carrier    // 运营商
     string os_name    // 系统名称
     string os_version    // 系统版本
     uint32 product_id    // 产品id
     string product_name    // 产品名称
     uint64 install_id    // app升级id
     string custom //自定义事件公共属性，是一个json的字符串
     string trace_id 
     uint32 client_port    // 客户端端口号
     string data_center    //上报机房
     string app_key    // 应用key
     uint32 version_code    // 版本号
     string sig_hash    // sig_hash
     uint32 update_version_code    // 内部更新版本号
     string vendor_id    // app发行商id
     string app_language    // app语言
     string language    // 系统语言
     string app_region    // app设置地区
     string region    // 系统设置地区
     string vid    // vid
     string traffic_type 
     string carrier_region 
     string device_model    // 设备型号
     string device_brand    // 设备品牌
     string device_manufacturer    // 设备制造商
     string resolution    // 屏幕分辨率
     string display_density    // 屏幕像素显示级别
     uint32 density_dpi    // 屏幕像素显示密度
     sint32 width    // 屏幕宽度
     sint32 height    // 屏幕宽度
     string cpu_abi    // cpu类型
     uint32 origin_app_id    // 中台重置的原始app_id
     string origin_app_name    // 中台重置的原始app_name
     float timezone    // 时区
     string tz_name    // 时区名称
     sint32 tz_offset    // 时区偏差
     string mcc_mnc    // 国家+运行商标记
     uint32 os_api    // 客户端系统API版本号
     string rom    // rom
     string rom_version    // rom版本
     string release_build    // release_build
     uint32 manifest_version_code    // Android配置版本号
     string sim_region    // sim地区
     string sim_serial_number    // sim序列号
     bool is_jailbroken    // 设备是否越狱
     string push_os    // 支持的推送os
     string platform    // 平台类型
     string province    // 省
     string city    // 市
     string ab_version    // ab_test字段
     string ab_group    // ab_test字段
     string ab_feature    // ab_test字段
     string ab_client    // ab_test字段
     string ab_sdk_version    // ab_test字段
     string utm_source    // 广告来源
     uint32 sdk_version    // 建议使用sdk_version_v2
     bool not_request_sender    // not_request_sender
     string user_agent    // user_agent
     bool gcm_available 
     string utm_medium    // 广告媒介
     string utm_campaign    // 广告名称
     uint64 campaign_id 
     uint64 ad_id 
     uint64 creative_id 
     string browser 
     string browser_version 
     string referrer 
     string referrer_host 
     string app_version_minor    //4位版本号
     string utm_term    //广告关键词
     string utm_content    //广告内容
     string sdk_version_v2    //string类型sdk版本
     string pgl_oaid  [deprecated]  //已废弃,请使用user中的pgl_oaid字段
     string tracer_data    // SDK tracer自定义字段，json串
     string sdk_lib    // 标识sdk类型
     uint64 harmony_os_api    // 524~530为鸿蒙系统特有标识
     string harmony_os_version 
     string harmony_release_type 
     uint64 harmony_build_version 
     uint64 harmony_major_version 
     uint64 harmony_senior_version 
     uint64 harmony_feature_version 
 
}

离线传输：FTP/SFTP方式文件格式说明

离线任务开启后，会在配置的远端路径下按创建目录，并按照一定规则将数据切分为一个或多个压缩的文件，每个文件中为多行json格式的上报事件，具体如下：

说明

示例

目录结构

每日例行导出：基于客户配置路径，按照数据日期生成子目录，用于存储对应日期的数据。
单次导出：按照导出的日期范围，分别建立对应的日期子目录
目录结构为：
{客户配置上传路径}/{%Y-%m-%d日期}/

例行导出：
2024年7月11日运行导出7月10日的数据，则生成：
/{客户定义根路径}/2024-07-10/

单次导出：
2024年7月11日运行导出7月8-9日的数据，则生成：
/{客户定义根路径}/2024-07-08/
/{客户定义根路径}/2024-07-09/

文件名称

在对应日期的文件夹，按对应日期的数据大小，切分成1到多个gz文件，命名方式为：
{项目id}{应用id}{导出任务名}part{prat_num}{16位random_id}.txt.gz
其中prat_num从0开始，若当日只有1份文件，仍遵循此规则

1_10000000_test1_2023-10-18_part0_rvgycnvjxpunuevg.txt.gz

文件内容说明

单个文件为gz压缩文件，解压后为txt文件，里面为多行数据，每行为1个json格式的事件。
json格式具体见数据示例。

例如：

1_10000000_test1_2023-10-18_part0_rvgycnvjxpunuevg.txt
未知大小

离线传输：事件属性数据示例

单条数据示例：

{
   "user": {
      "user_unique_id": "4010980525",
      "web_id": "",
      "ssid": "1729384455933548568",
      "anonymous_id": null,
      "device_id": "7279348669067838213",
      "hash_uid": "1729384455933548568"
   },
   "header": {
      "app_id": 10000000,
      "app_name": "toutiao",
      "ab_version": [],
      "custom": {
         "continent": "AS",
         "device_model": "iphone 7 plus",
         "platform": "ios",
         "getui_client_id": "A2800992-931C-4836-A884-AF6D6B35D064",
         "platform_type": "web/h5",
         "browser": "safari",
         "sdk_version": "6180690",
         "browser_version": "9.1.3",
         "sdk_lib": "ios",
         "__trace_id": "1694880771043042001034172826147014",
         "session_id": "f5de541d7433774ade7931a766c6087088ba",
         "network_carrier": "at&t",
         "ad_id": "0",
         "device_brand": "apple",
         "is_login": 1,
         "width": 0,
         "age": 56,
         "height": 0
      },
      "app_language": "zh_CN",
      "app_version": "0.15",
      "timezone": "8",
      "language": "zh_CN",
      "resolution": "320*570",
      "loc_country_id": "1814991",
      "app_region": "China",
      "loc_province_id": "1796231",
      "client_ip": "180.156.197.138",
      "loc_city_id": "1796236",
      "package": "ios.package",
      "os_version": "11.4.0",
      "app_channel": "\u6296\u97f3\u89c6\u9891",
      "os_name": "ios",
      "network_type": "4g",
      "region": "China"
   },
   "sdk": null,
   "preset_user_profiles": "",
   "params": {
      "is_background": "false",
      "duration": 0,
      "session_duration": 0
   },
   "event_name": "app_launch",
   "time": {
      "event_time": 1694879843000,
      "server_time": 1694879843000,
      "event_date": "2023-09-16"
   }
}

离线传输：用户数据分发数据示例

数据示例如下：

{
    "app_id": "10000***",
    "project_id": "1",
    "subject_id": "1",
    "ssid": "172938885398003****",
    "stat_standard_id": "172938885398003****",
    "device_id": "",
    "web_id": "745710618994439****",
    "user_id": "879303****",
    "user_unique_id": "879303****",
    "hash_uid": "172938885398003****",
    "update_time": "1736242840766",
    "last_active_date": "2025-01-06",
    "user_profiles": {
        "gender": "female",
        "campaign_name": "",
        "cheat_type": ""
    }
}

字段名

字段含义

app_id

应用id

project_id

项目id

subject_id

主体id

ssid

增长分析默认使用的统计口径ID

stat_standard_id

基本同ssid

device_id

设备的唯一标识（移动端）

web_id

设备的唯一标识（网页端、小程序）

user_id

用户ID

user_unique_id

用户唯一标识，一般情况直接使用产品业务中使用的用户标识，比如登录账号

hash_uid

内部使用字段，经过hash之后的UID

update_time

更新时间

last_active_date

最近活跃日期

user_profiles

其他所有用户属性，以json格式表示
例如：

{
        "gender": "female",
        "campaign_name": "",
        "cheat_type": ""
    }

注意

  • user_is_new(是否新用户)属性由计算得出，查询出来始终为空。
  • last_active_date(最后活跃日期)在外层结构中默认返回

离线传输：二次解析字段的映射

离线传输的数据可能会额外包含地域ID（需要使用映射表获取中文）、是否登录等经过二次处理的预置属性。在传输过程中，此类数据以ID的形式进行存储，ID与其对应的中英文名称、属性取值等映射关系如下表所示。您可参考下表将接收到的此类数据进行映射处理，便于后续的查询分析。

geo_info.csv
16.44MB

离线传输：离线数据字段说明

类型

字段名

字段含义

值示例

User/用户ID合集

user_unique_id

用户唯一标识，一般情况直接使用产品业务中使用的用户标识，比如登录账号

8228513602

user_id

用户ID

8228513602

web_id

设备的唯一标识（网页端、小程序）

ssid

增长分析默认使用的统计口径ID

1729384455933532151

device_id

设备的唯一标识（移动端）

7333075566024720907

hash_uid

内部使用字段，经过hash之后的UID

1729384455933532151

anonymous_id

客户自行生成的匿名id，可选上报

header/公共属性（含预置）

app_id

应用ID

10000000

app_name

应用名称

test

ab_version

AB实验VID

custom

非预定义的公共属性合集，如在外层未找到公共属性请在该字段中获取

{
"continent":"AS",
"device_model":"ipad 5",
"platform":"ios",
"getui_client_id":"149555A7-5140-4DD5-A79F-75101D446E9F",
"platform_type":"android",
"browser":"chrome",
"sdk_version":"6800980",
"browser_version":"68.0.3440",
"sdk_lib":"ios",
"session_id":"21491c1987a8e846da88955856c99dad1f9b",
"network_carrier":"sprint",
"device_brand":"apple",
"is_login":1,
"ad_id":0,
"width":0,
"age":17,
"height":0
}

app_language

APP语言类型

en_US

app_version

APP版本

0.27

timezone

时区

8

language

系统语言类型

zh_CN

resolution

分辨率

1920*1080

loc_country_id

国家编号

1814991

app_region

软件地区

China

loc_province_id

省份编号

1279685

client_ip

客户端IP地址

113.63.59.55

loc_city_id

城市编号

1280737

package

安装包名

ios.package

os_version

系统版本

7.0.0

app_channel

渠道

app store

os_name

操作系统

ios

network_type

网络类型

4g

region

系统地区

China

app_version_minor

四位版本号

4

creative_id

创意ID（Tracer字段）

campaign_id

广告组ID（Tracer字段）

gender

性别

utm_campaign

广告推广活动

utm_source

广告推广渠道

utm_medium

广告推广媒介

utm_content

广告推广内容

utm_term

广告推广字词

__sdk_platform

SDK类型与版本，默认不显示，DataFinder系统应用字端。

$source_platform

事件上报的端类型，默认不显示，DataFinder系统应用字端。

$is_first_time

是否首次访问

$url_query

小程序URL查询参数

$is_first_day

是否首日访问

user_profile

all_value类型的用户属性，私有化环境不存在

params

自定义事件属性

{
"is_background":"false",
"__is_history":"true",
"__trace_id":"1697731728029042001030106337149514",
"duration":0,
"session_duration":0
},

event_name

事件名称

app_launch

time/时间

event_time

客户端时间

1697730863000

server_time

服务端时间

1697730863000

event_date

事件发生日期

2023-10-19

item/业务对象

业务对象属性（可选上报）

常见问题FAQ

Q1 能否获取历史数据？

实时任务不支持，请通过离线任务自助补推历史数据，最多支持T-30天的历史数据一次性导出。
此外，已停用的实时任务如果重新启用，停用期间的数据不可回溯。

Q2 数据发送时间？

实时数据正常情况在数据上报后60s内发送。

Q3 数据发送失败怎么办？

针对业务自身服务接收造成的发送失败，目前系统存在如下重试机制：
私有化环境中，当日内不限次重试；4.6（含）版本后如果某条数据连续三次失败，系统将不再推送该条消息；7天内您可以联系客户成功经理或火山的技术支持手动触发推送，过期将自动删除不再支持恢复

Q4 接受的数据条数为什么和界面统计的指标有差异？

不排除因网络不稳定等各种原因出现部分数据重复推送的情况。如有特殊情况可联系您的客户成功经理或火山的技术支持。