应用场景

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

使用限制

数据输出方式

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

• 实时传输（私有化）

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

• 离线传输（私有化）

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

前提条件

创建数据输出任务

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

   说明

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

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

实时任务

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

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（含）后新增过滤条件，可以根据事件和属性规则组合，选定分发的数据范围。

   

   参数	参数说明
   添加事件	配置需要分发到目标地址的事件列表。事件列表为包含逻辑，即仅选定的事件将会被分发。
   事件属性添加规则	对已添加的事件通过事件属性进行过滤，即仅在事件列表范围内，且满足事件属性规则的数据才会被分发。

离线任务

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

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（含）后新增过滤条件，可以根据事件和属性规则组合，选定分发的数据范围。

   

   参数	参数说明
   添加事件	配置需要分发到目标地址的事件列表。事件列表为包含逻辑，即仅选定的事件将会被分发。
   事件属性添加规则	对已添加的事件通过事件属性进行过滤，即仅在事件列表范围内，且满足事件属性规则的数据才会被分发。

数据输出结果确认

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

查看/启停/编辑任务

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

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

实时传输：分发数据示例

一次请求的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"
   }
}

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

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

geo_info.csv

16.44MB

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

Q1 能否获取历史数据？

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

Q2 数据发送时间？

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

Q3 数据发送失败怎么办？

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

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

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