Data Locker——广告主使用指南

高阶付费

概要:Data Locker可以将您的报告发送到云端,或入库到您的BI系统。我们支持多种云端存储方式,您可以使用AppsFlyer的AWS数据存储桶或您在AWSGCS的自有存储桶,也可以使用SnowFlake。Data Locker还支持多宿端数据传输,也就是说,您可以将所有数据传输到多个宿端、分宿端传输不同数据,或结合这两种方式传输数据,还可以为各宿端分别配置Parquet或CSV格式。

Data Locker

6133DataLockerForAdvertisers.png

相关文档:

您可以在Data Locker中选择您需要AppsFlyer传输到指定宿端的数据,可用的维度包括应用、媒体渠道、事件和报告。然后您就能通过程序化的方式将这些数据从云端入库到您的系统中。

Data Locker——功能简介

功能 说明
存储方式

Data Locker可以将您的数据发送到下列任一云平台:

您可以在Data Locker中设置多个宿端。也就是说,您可以将部分或所有数据发送到多个宿端

示例

  • 按报告类型隔离数据:将原始数据发送到GCS,将汇总数据发送到Snowflake。
  • 按应用隔离数据:将各应用组的数据分别发送到不同的数据存储桶。
多应用

Data Locker可以发送您AF账户下的某个、某些或所有应用的数据。您在账户中添加应用时,Data Locker可自动涵盖这些新应用的数据。

可用窗口期

14天

数据隔离

数据隔离方式有以下两种:

  • 【默认】归并:即合并所有应用的数据。您可以使用每一行中的应用ID字段在数据文档中区分具体应用。
  • 按应用隔离数据:Data Locker可以将每个应用的数据分别放在单独的文件夹里,文件夹名称中包含具体的应用ID。
数据格式选项
  • CSV
  • PARQUET
数据时效性

数据时效性取决于报告类型

  • 每小时更新一次:滚动生成数据;AppsFlyer接收到激活和应用事件数据后数小时内就会将其写入存储桶。
  • 每天更新一次:卸载等报告每天更新一次,您可在次日拉取前一天生成的报告。
  • 文档编号:如果在同一指定时段内多次生成同一种报告,Data Locker会对文档进行编号。
Big Query和Google Data Studio

如果您将数据写入GCS,Big Query可以直接加载您的Data Locker文件,无需进行中间处理。您也可以使用Google Data Studio等其他工具进行数据可视化。

可通过Data Locker拉取的报告

数据存储结构

简要说明

您的数据构架取决于您使用的数据存储工具,即云存储或数据仓库。下文所述的目录结构是数据存储桶中的结构。如果您使用数据仓库(Snowflake)存储数据,则其中的视图结构与本文中的目录结构类似,详情请见Snowflake说明。

Data Locker会将数据写入您指定的存储工具中。如果您使用云存储,您可以选择AppsFlyer的AWS存储桶或者您在AWS或GCS上的自有存储桶。您可以随时切换存储工具、数据切分方式和数据宿端。

Data Locker以分级的目录结构将数据写入存储桶中,分级维度为报告类型、日期和时间。下图为目录结构示例:

DLFolderOVerview.png

具体报告的数据保存在该报告类型下的小时数(h)文件夹中:

  • 报告的数据时效性(每小时更新、每天更新或版本化)决定了文件夹名称中的小时数。
  • 以GZ压缩文件的形式提供数据,格式为Parquet或CSV。
  • 数据文件由列(字段)组成。
  • 用户链路报告的schema(字段)结构与此相同,具体取决于您选择的字段。其他报告各自有其显式字段,即无结构(schemaless)报告。详情请见Data Locker的广告主报告,其中列出了可用的报告并提供了各种报告的说明文档链接。

目录结构

文件夹 说明
订阅ID(Subscription ID)

DataLockerFolders.png

  • 存储桶中的根目录命名方式取决于广告主和云服务商。一般情况下,根目录的名称即您的Subscription ID,但如果您使用Cyberduck,则该ID通过书签设置,而不会显示在目录结构中。
  • data-locker-hourly目录下是报告主题文件夹,其上级目录取决于存储桶的所有者和相关的云服务商。

各种场景的文件夹结构示例:

  • AppsFlyer存储桶:<af-ext-reports>/<unique_identifier>/<data-locker-hourly>
  • 您的AWS存储桶<af-datalocker-your bucket prefix>/<generated-home-folder><subscription-id>
  • 您的GCS存储桶:<your bucket name>/<generated-home-folder>/<subscription-id>
主题(t) 报告类型与报告主题相关。
日期(dt)

代表相关的数据日期。对于原始数据,该日期表示事件发生的日期。对于汇总数据,该日期表示上报日期。

时间(h或版本编号)

日期文件夹以小时数(h)版本编号命名,具体取决于报告类型。

以小时数命名的文件夹

h文件夹的小时数是指AppsFlyer接收到数据的时间。比如AF会将UTC时间14:00-15:00之间接收到的激活数据写入h=14文件夹中。请注意:AF接收数据后需要1-3小时左右才能将相应的h文件夹写入Data Locker中。比如h=14文件夹会在1小时后,即UTC时间15:00写入到Data Locker中。

小时数文件夹的特点

  • 共有24个h文件夹,分别以0-23编号,比如h=0、h=1等等。
  • h=late(延迟)文件夹用于存储次日凌晨之后接收到的前一天的事件,即UTC时间的次日00:00–02:00之间发送到AF的事件。举例来说,如果某用户在UTC时间周一08:00激活某个应用,AF在UTC时间周二01:00接收到该激活,则AF会将该激活写入周一的延迟文件夹中。
  • AF会将UTC时间02:00之后接收到的数据按实际的接收日期和小时数写入相应的文件夹中。
  • 取数时请务必一并拉取h=late文件夹中的数据,任何其他文件夹都不包含这些数据。
  • _temporary文件夹Data Locker有时会在h文件夹下生成一个临时文件夹。请忽略这些临时文件夹及其子文件夹。临时文件夹示例:/t=impressions/dt=2021-04-11/h=18/_temporary
  • 注意
    • 原始数据报告每天写入一次,保存在h=23文件夹中。卸载报告一般保存在h=2文件夹中,但也可能出现在其他文件夹中。
    • 群组和增量报告直接保存在dt文件夹中。
    • 版本化报告的命名与本节所述方式不同。

非UTC时区应用的逐时报告注意事项

要确保拉取到某一天的全部数据,必须按应用时区来确定具体日期,并拉取该日期的文件夹。方法如下:

  • 东半球时区:如需拉取某个日期的所有数据,必须按UTC时间和日期取相应文件夹中的数据。示例:假设相关应用的时区是UTC+10(澳大利亚悉尼)。如需拉取悉尼时间周二的所有逐时数据,必须取用以下文件夹:周一的h=14–23和late文件夹,周二的h=0–13和14-15文件夹。注意:取数时必须包含周二的h=14-15文件夹,这是因为有些数据传输到AF可能会有延迟,而这些延迟送达的事件数据会出现在h=14–15文件夹中。然后,您还需要将悉尼日期换算成UTC日期,按相应的event_time(事件时间)筛选数据。
  • 西半球时区:如需拉取某个日期的所有数据,必须按UTC时间和日期取相应文件夹中的数据。示例:假设相关应用的时区是UTC- 7(美国洛杉矶)。如需拉取洛杉矶时间周二的所有逐时数据,必须取用以下文件夹:周二的h=7–23和late文件夹,以及周三的h=0–6和7-8文件夹。注意:取数时必须包含周三的h=7-8文件夹,这是因为有些数据传输到AF可能会有延迟,而这些延迟送达的事件数据会出现在h=7–8文件夹中。然后,您还需要将洛杉矶日期换算成UTC日期,按相应的event_time(事件时间)筛选数据。

版本编号文件夹

部分报告会按版本化方式命名。也就是说,Data Locker会多次写入指定日期的最新数据。这是因为有些数据的接收会有延迟,或后续出现了更准确的数据,因此Data Locker中的数据会持续更新,从而使同一个报告出现多个版本,其中最近期的版本数据最准确。

指定日期的报告保存在该日期下的版本编号文件夹中。每个版本各自放在单独的文件夹中,这些文件夹的名称是通过Epoch时间戳来命名的,用以识别相关报告。

在设计数据入库流程时,请务必注意Data Locker会回溯性地写入数据。比如Data Locker可能会在1月14日在1月1日的文件夹中写入数据。如果您使用的是自有存储桶,建议使用云服务消息通知来触发入库流程(AWS | GCS

分应用取数

Data Locker可以将所有指定应用的数据文件合并到统一的数据文件中,也可以将数据按应用分别写入不同的文件夹中。分应用写入的数据会放在h文件夹下,详情请见下表。
区隔类型 说明
【默认】合并

所有应用的数据合并在统一的数据文件中。取数时请使用行级的app_id field字段来区分不同应用的数据。

示例:h=2文件夹下为数据文件

UnifiedByApp.png

数据文件的命名方式为unique_id.gz。

  • 您的数据拉取流程必须符合以下要求:
    • 必须在_SUCCESS标签设置完毕后再拉取数据。
    • 必须拉取扩展名为.gz的文件夹中的所有文件。切勿在数据入库流程中使用分卷编号逻辑。
分应用取数

文件夹中包含分应用的子文件夹。具体应用的数据文件保存在该应用的文件夹中。下图中的h=19文件夹含有应用文件夹,每个应用文件夹中包含相关的数据文件。请注意:数据文件名称中没有app_id,必须通过文件夹名称中的app_id来识别。

DLSegregateByApp.png

各应用文件夹的命名方式为unique_id.gz:

  • 您的数据拉取流程必须符合以下要求:
    • 必须在_SUCCESS标签设置完毕后再拉取数据。
    • 必须拉取扩展名为.gz的文件夹中的所有文件。切勿在数据入库流程中使用分卷编号逻辑。

局限性:PBA报告无此选项。

数据文件

内容 细节
完成标签

一个h文件夹中的所有数据都写入完毕后,系统会设置末尾文件(完成)标签。

  • 请务必先确认数据带有_SUCCESS标签,然后再拉取数据。

  • 即使某个文件夹中没有数据可写(即该文件夹为空时),系统也会设置_SUCCESS标签。

  • 请注意:在分应用取数时,需在h文件夹(而非应用文件夹)中确认该标签。详情请见上节图示。
文件类型
  • 分卷文件通过GZ压缩。
  • 解压后的数据文件是Parquet或CSV格式的,具体取决于您的设置。
字段顺序(CSV文件)

如果是CSV文件,则报告中的字段顺序总是不变的,新添加的字段会出现在现有字段的右侧。

在这种情况下:

  • 各种用户链路报告的字段结构完全一致。也就是说,不同类型的报告可以使用相同的数据入库流程。请参考原始数据字段词典中的字段释义,在报告中选择您需要的字段。
  • 在报告可用性部分中,带有FF标记的报告字段结构与一般报告不同。
字段填充注意事项

字段为空:报告中会出现部分null或空的字段。出现这种情况即表示这个字段在该报告中没有数据可以上报。一般来说,null表示该字段在相应报告和应用类型中不适用。空值(显示为"')表示该字段适用于相应的报告和应用类型,但未找到相关数据。

如果媒体渠道受限,则受限字段的值为“null”。

总体而言,null值和空值的含义基本相同,都可以理解为没有可用的值。

时区和货币

您在应用配置中指定的时区和货币对Data Locker中的数据无效。Data Locker数据的时区和货币单位如下:

  • 时区:日期和小时数按UTC时间计算。
  • 货币:event_revenue_usd字段以美元为单位。

带逗号的值:逗号会出现在双引号(`"`)之间,如`"iPhone6,1"`

不同的分类取数方式会产生不同的数据文件

存储工具选项

 注意!

如果您使用的是自有存储工具:

  • 请确保您符合GDPR等数据隐私条例以及广告平台/SRN的数据保存规定。
  • 请勿使用您的自有存储桶向第三方发送数据。
  • 可选的存储工具如下:
    • AppsFlyer存储桶
    • 客户自有存储桶——AWS或GCS
  • 您可以随时切换存储工具。
  • 更改存储工具后会发生以下变化:
    • AF会在一小时内将数据写入新的存储桶。
    • 更改存储工具后会有一个7天的过渡期,在此期间我们会继续将数据写入原先的存储工具。您可以在AF后台查看过渡期的结束时间,以便对后续的数据入库流程变更做出相应的安排。您也可以根据实际情况重启过渡期,或换回AppsFlyer存储桶。
    • 切换存储选项:您可以使用多宿端存储选项,将数据同时发送到多个宿端,这样就能切换存储选项。完成迁移和测试后,请删除弃用的存储选项。
  AppsFlyer的AWS存储桶 广告主自有的存储选项(GCS、AWS、Snowflake)
存储桶名称 由AppsFlyer设置
  • GCS:无限制。
  • AWS:由广告主设置。必须带有前缀af-datalocker-。

示例:af-datalocker-your-bucket-name

存储桶所有者 AppsFlyer 广告主
存储平台 AWS AWS、GCS、Snowflake
广告主用于访问数据的证书 AppsFlyer账户的管理员可以在其Data Locker界面中查看此信息。 AppsFlyer不掌握该信息。用户证书是由云服务商提供的。
数据保存 数据会在14天后自动删除。 由广告主执行
数据删除请求 由AppsFlyer执行 由广告主执行
数据安全 存储桶由AppsFlyer管理。客户具有只读权限。

存储桶由广告主管理。

  • AWS:AppsFlyer需要存储桶的GetObject、ListBucket、DeleteObject、PutObject权限。该存储桶必须仅用于AppsFlyer数据存储。请勿将其用于其他用途。
  • GCS:详情请见GCS配置指南
存储容量 由AppsFlyer管理 由广告主管理
使用带存储桶策略的VPC端点读取数据 不适用 【可选】如果您在AWS的存储桶层级采取了VPC端点安全防护措施,必须将AppsFlyer的服务器加白。

广告主自有存储桶的数据安全负责人须知

注意事项:

  • 该存储桶或宿端仅可用于AppsFlyer的数据写入,不能有其他实体向该宿端写入数据。
  • AF写入数据的25小时后您可以从相关宿端中删除该数据。
  • 宿端中的数据是AF服务器中数据的副本。我们会按AF的数据保存规定将这些数据保存在服务器中。
  • 出于一些技术原因,我们有时会删除并重写数据。因此需要删除与列表权限。这两个权限都不会造成任何安全隐患:这是因为AF是唯一一个向该存储桶中写入数据的实体,因此列表权限不回带来风险;此外由于AF可以重新生成相关数据,因此删除权限也没有安全风险。
  • 如需了解其他相关信息,请发送邮件至hello@appsflyer.com联系我们的数据安全团队或您的CSM。

多宿端作用原理

您可以使用Data Locker将您的部分或所有数据发送到多个宿端(在连接部分设置)。比如,将A应用的数据发送到AWS,将B应用的数据发送到GCS。

每个连接由一套完整的Data Locker设置组成,其中包含一个宿端。每个连接的设置都是单独分开的。

管理宿端连接时需注意以下几点:

  • 宿端连接在Data Locker设置部分中,分单独的标签页显示。也就是说,您可以在各连接的专属标签页中管理其配置。默认标签页为“Data Locker”。
  • 请按以下步骤创建新连接:
    1. 单击添加连接
    2. 为该连接命名,并选择存储工具类型。
    3. 点击保存
      保存成功后,该连接就会显示在默认的“Data Locker”标签页旁边。每个标签页的图标代表相应的存储工具类型。
  • 如需查看连接详情、创建连接副本或删除连接,请点击⋮(选项图标)

设置流程

设置Data Locker

请使用本节所属流程设置Data Locker。更改Data Locker的任何设置都需要最多3小时后才能生效。

前期准备

设置广告主自有存储桶:

如果您要使用自由存储桶设置Data Locker,请先完成以下任一/各项流程:

  • 设置您的AWS存储桶。
  • 设置您的GCS存储桶。

请注意:如果您的套餐中不含Data Locker,但含群组分析报告或SKAN数据,您也必须完成自有存储桶设置。

AppsFlyerAdmin_us-en.png请按以下步骤设置Data Locker:

  1. 需要账户管理员完成该设置。
  2. 从AppsFlyer面板进入配置 > Data Locker
  3. 【可选】如果您已经有在用的Data Locker宿端,并需要再添加其他宿端,请点击+
  4. 选择一个云服务数据宿端。请完成以下任一操作:
    • 选择AppsFlyer的AWS存储桶(仅限套餐中包含Data Locker的广告主),然后进入第4步。
    • 选择您的AWS存储桶
      1. 输入不含前缀af-datalocker-的AWS存储桶名称。
      2. 点击测试
      3. 确保未收到“存储桶路径无效”的报错消息。
    • 选择您的GCS存储桶,然后输入您的GCS存储桶名称,最后点击“test”进行测试。
  5. 选择文件夹结构(数据隔离):
    • 【默认】合并
    • 分应用取数
  6. 选择文件格式:
    • 【默认】Parquet
    • CSV
  7. 选择相关应用。点击全选可自动添加后续加入的新应用。
  8. 点击应用
  9. 【可选】媒体渠道:您可以选择一个或多个媒体渠道,以便在报告中查看相关数据。
    • 默认=All(所有媒体渠道)。也就是说,您后续添加的所有媒体渠道都会自动添加到Data Locker中。
  10. 选择您要拉取的报告类型(至少一种)。
  11. 【可选】应用内事件:选择需要拉取的应用内事件。如果您的应用内事件类型超过100种,则无法进行搜索。请输入相关事件的实际名称,并点选。
    • 默认=All(所有应用内事件)。也就是说,您后续添加的所有应用内事件都会自动添加到Data Locker中。
  12. 点击应用
  13. 【可选】字段:选择您要在报告中查看的字段。注意:AF有时会在报告中开放额外字段,请在数据入库时注意这一点。
  14. 点击Save Configuration。完成操作后会出现以下两种结果:
    • 如果您选择了AppsFlyer的AWS存储桶
      • AF将为您创建专属的AWS存储桶。界面会显示存储桶证书。
      • 您可以使用该证书以只读方式访问存储桶。
    • 如果您选择了客户自有存储桶:AF将在3小时内把数据写入您的存储桶。

重置证书

AF账户管理员可以随时重置AppsFlyer存储桶证书。请注意:重置证书后,您必须升级数据导入脚本,将新证书写入脚本中。

AppsFlyerAdmin_us-en.png 请按以下步骤重置AppsFlyer存储桶的证书:

  1. 从AppsFlyer面板进入配置 > Data Locker
  2. 选择AppsFlyer存储桶。
  3. 点击“证书”部分中的重置证书
    界面打开确认窗口。
  4. 点击重置
  5. 等待界面显示Credentials successfully reset(证书重置完毕)的消息(约20秒)。
    然后您就可以使用新的证书了。

其他相关信息

特点与局限性

特点
特点 说明
广告平台 广告平台不可用
代理 代理不可用
应用设定的时区 不适用。Data locker文件夹按UTC时间逐时拆分。实际事件时间是以UTC时间显示的,请根据需要将其换算到其他时区。不论您在应用配置中设定了哪个时区,从事件发生到Data Locker记录事件之间的延迟保持不变。
应用设定的货币 不支持
数据量限制 不适用
数据时效性 数据的更新频率取决于具体报告的数据时效性,详情请见本文档
历史数据 不支持。如需拉取历史数据,请使用Pull API(仅部分报告具有可用的历史数据)。
用户权限 如需配置Data Locker,须具备相关权限
单应用/多应用 支持多应用取数。Data Locker是帐户级别的功能。

疑难解答

  • 问题:无法使用AWS CLI获取数据
  • 报错消息:调用ListObjectsV2时出现错误(AccessDenied),收到“Access Denied”消息(拒绝访问)
  • 原因:AppsFlyer存储桶的AWS证书不正确。这可能是由于您的计算机上有多个证书或无效证书。
  • 解决方法
    1. 请换一种方法(例如Cyberduck)访问存储桶,不要使用CLI。这是为了验证您使用的证书是否能正常生效。如果可以通过Cyberduck连接,则表明是证书缓存的问题。
    2. 刷新AWS证书缓存
      具体方法请见下方AWS截图

      mceclip0.png

AWS数据拉取

本节解释了AWS数据拉取工具的使用方式,这些工具包括AWS CLI、Cyberduck、Amazon S3浏览器。请注意:下文说明是针对AppsFlyer存储桶编写的。如果您使用的自有存储桶,请根据实际情况调整相关操作。

AWS CLI

前期准备

  • 在您的电脑上安装AWS CLI。
  • 从AppsFlyer面板进入Data Locker配置页面,然后在证书栏中获取所需信息。

请按以下方式使用AWS CLI

  1. 在Windows中使用<Windows>+<R>键,然后点击OK,打开相关终端。
    界面显示命令行窗口。
  2. 输入aws configure
  3. 输入证书面板中显示的AWS Access Key。
  4. 输入证书面板中显示的AWS Secret Key。
  5. 输入eu-west-1
  6. 按下回车键。

根据需要使用以下CLI命令。

您可以在以下命令中找到{home-folder}的值

如需在存储桶中列出文件夹:


aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/

列出文件和文件夹

Data Locker存储桶中有三类文件夹:

  • Report Type t=
  • Date dt=
  • Hour h=

如需列出某个报告类型下的所有报告:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/

如需列出某个报告类型在某个日期的所有报告:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/dt=2019-01-17

如需列出某报告类型在某日某时的所有报告:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/dt=2019-01-17/h=23

如需下载特定日期的文件:


aws s3 cp s3://af-ext-reports/<home-folder>/data-locker-hourly/t=installs/dt=2020-08-01/h=9/part-00000.gz ~/Downloads/

Cyberduck

前期准备

  • 安装Cyberduck客户端。
  • 从AppsFlyer面板进入Data Locker配置页面,然后在证书栏中获取所需信息。

请按以下步骤配置Cyberduck

  1. 在Cyberduck后台点击“Action”(操作)。
  2. 选择New Bookmark(新建书签),打开配置窗口。
  3. 在第一个字段中(即下图中标[1]处)选择Amazon S3

    DataDuckSmall2.png

  4. 填写以下字段:
    • Nickname(昵称):自定义文本
    • Server(服务器):s3.amazonaws.com
    • Access Key ID(访问密钥ID):复制AppsFlyer后台的证书栏中显示的AWS Access Key。
    • Secret Access Key(秘密访问密钥):复制AppsFlyer后台的证书栏中显示的Bucket Secret Key。
    • Path(路径):{Bucket Name}/{Home Folder} 示例:af-ext-reports/1234-abc-ffffffff
  5. 点击窗口右上角的X,关闭该窗口。
  6. 选择相关连接。
    界面会展示数据目录。

Amazon S3浏览器

前期准备

  • 安装Amazon S3浏览器。
  • 从AppsFlyer面板进入Data Locker配置页面,然后在证书栏中获取所需信息。

请按以下步骤配置Amazon S3浏览器

  1. 在S3浏览器中点击Accounts > Add New Account
    界面打开Add New Account(添加新账户)窗口。

    mceclip0.png

  2. 填写以下字段:
    • Account Name(帐户名):自定义文本。
    • Access Key ID(访问密钥ID):复制证书栏中的AWS Access Key。
    • Secret Access Key(秘密访问密钥):复制证书栏中的Bucket Secret Key。
    • 选择Encrypt Access Keys(对密钥加密),输入密码。将此密码记录下来,以防遗忘。
    • 选择Use secure transfer(使用安全传输)。
  3. 点击保存更改
  4. 点击Buckets > Add External Bucket(添加外部存储桶)。
    界面打开Add External Bucket窗口。

    mceclip2.png

  5. 输入Bucket name(存储桶名称)。存储桶名称的格式为:{Bucket Name}/{Home Folder}。您可以在在证书窗口中看到存储桶名称和主文件夹的值。
  6. 点击Add External bucket(添加外部存储桶)。
    系统创建存储桶并将其展示在窗口左侧边栏中。
    完成上述操作后,您就能访问Data Locker文件了。