You need to enable JavaScript to run this app.
导航
数据输出
最近更新时间:2024.05.29 21:34:12首次发布时间:2022.07.25 14:11:16

背景信息

应用场景

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

使用限制

细分项目

限制说明

支持的环境

  • 私有化环境:4.1.0版本(含)后开始支持。
  • SaaS环境:
    • SaaS-字节云版本支持数据输出功能。
    • SaaS-云原生版本(火山云)暂不支持实时数据导出。

功能开关

为了保证您和用户的数据安全,SaaS环境的数据输出功能默认关闭。在开始使用之前,需要联系客服开通(请完整说明数据输出的用途和用量,并提供集团ID以便于审核)。

功能费用

数据输出功能暂时免费使用(SaaS-字节云环境):

  • 离线免费事件量上限10亿条(月)。
  • 实时免费事件量上限2亿条(月)。

后续会针对免费事件量及收费进行调整(预期25年前后,会基于功能研发投入及实际情况进行收费费用调整,调整前会对所有用户进行强触达提醒)。

数据输出方式

当前DataFinder的SaaS-字节云环境支持实时传输数据;私有化环境支持实时与离线传输数据。实时与离线数据传输的主要流程如下。

  • 实时传输(SaaS-字节云、私有化)

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

  • 离线传输(私有化)

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

操作步骤(私有化)

前提条件

细分

前提条件

DataFinder侧

数据接收侧

  • 您需要配置完成接收传输数据的接收端。
    • 对于实时传输场景,您需要准备一个Webhook接收端,明确好接收数据的规则(例如接收数据时是否需要鉴权等)。
    • 对于离线传输场景,您需要准备一个用于接收数据的FTP/SFTP服务器,并获取到服务器的连接信息(服务器地址、鉴权信息等)。
  • 完成白名单配置:如果接收端有白名单限制,需将传输数据的Finder服务地址添加到白名单中。
    • 在SaaS-字节云环境中,您需要添加以下来源ip的白名单:

      106.38.226.0/24
      116.132.239.0/24
      111.63.61.128/25
      111.63.211.128/25

    • 在私有化环境中,如果接收服务是在外网,需要配置私有化机器的出口ip。

创建数据输出任务

  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地址,如有多个地址可创建多个任务。
    • 在SaaS-字节云环境中,您需要添加以下来源ip的白名单:

    106.38.226.0/24
    116.132.239.0/24
    111.63.61.128/25
    111.63.211.128/25

    • 在私有化环境中,如果接收服务是在外网,需要配置私有化机器的出口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. 数据连接配置。

    参数

    参数说明

    连接协议

    选择FTPSFTP

    接入方式

    默认选择标准版本

    连接地址

    配置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 
 
}

离线传输:数据示例

单条数据示例:

{
   "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

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

类型

字段名

字段含义

值示例

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类型的用户属性,仅SaaS字节云存在

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 数据发送失败怎么办?

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

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

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