# Vivo 营销平台集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 广告效果数据 | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
目前 TE 支持接入 Vivo 营销平台 Marketing API 的广告效果数据 (opens new window)，支持获取广告创意层级的成本、点击、展示等聚合指标数据
# 集成流程
- 登录 TE 后台，进入三方集成模块，新增 Vivo 集成方案，并完成相关配置，并复制授权回调地址
- 登录 Vivo 开发者后台，获取开发者账号并创建应用，并收集所需的授权信息
- 回到 TE 后台，修改之前的 Vivo 集成方案，使用应用的 Client ID 与 secret，并打开授权链接完成授权
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、方案配置
接入 Vivo 平台数据前，需要先在 TE 后台创建相应的集成方案，并获取授权回调地址，您可以按照本文档完成集成方案的创建
# 1.1 临时编写授权信息
首先点击授权信息栏的「配置授权信息」按钮，在弹出的授权信息弹窗中，先随意编写授权信息的三项，作为临时的授权信息。之后在完成 Vivo 平台的应用创建后，还需进行调整。
# 1.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 Vivo Marketing API 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 1.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
# 1.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义 |
| source | time_granularity | 数据的时间聚合粒度，即拉取的数据以天还是小时进行聚合 可选值: DAY、HOUR |
| report_types | 数据层级，您只能选择一个数据层级 可选值：ACCOUNT(账户层级)、CAMPAIGN(计划层级)、GROUP(广告组层级)、ADVERTISEMENT(广告层级)、CREATIVE(创意层级，默认层级) |
# 1.5 获取授权回调地址
在完成上述配置后，请点击右上角的保存并授权获取授权信息。请复制第一步中的授权回调地址，并妥善保管。之后点击「暂不授权」关闭该弹窗：
接着，点击「保存」按钮完成方案的保存，至此您暂时完成了 TE 后台的配置工作，接下来请在 Vivo 后台完成相关配置。
# 二、获取开发者账号并创建应用
在完成 TE 后台的项目创建后，您还需要准备一个 Vivo 开发者平台应用，如果您已经创建了 Vivo 开发者应用，则可以跳过本节
# 2.1 获取开发者账号
在接入 Vivo Marketing API 之前，您首先需要获取开发者账号。首先进入开发者官网，点击右上角登录 (opens new window)按钮进入登录页面，登录您的二级代理商帐号或广告主帐号的营销平台账号。
# 2.2 应用的申请及创建
登录营销平台账号成为开发者后，进入应用管理看板：
请点击右上角的「新建应用」按钮进入创建应用程序界面：
您可以按照以下描述编辑配置，完成后点击提交创建应用
- 应用图标：可自定义，250 x 250 px 的应用图标，小于50kb。
- 应用名称：可自定义，不超过15个字符
- 回调地址：填入您在 TE 后台 Vivo 集成方案中获取的回调地址
- 应用介绍：介绍您的应用程序希望基于 Marketing API 实现的功能及您需要功能通过审核的原因，可以描述您需要将广告洞察数据回传至自有分析平台
- Token 有效期：
- Access Token 有效期：该应用下 access token 的有效时长
- Refresh Token 有效期：该应用下 refresh token 的有效时长，需大于 access token 的有效时长
接下来，Vivo 审核人员会在2-3个工作日内进行审核，完成审核后进行接下来的工作。
# 2.3 获取 Client ID 和 Client Secret
回到 Vivo 开发者平台，在「我的应用」页面获取创建好的应用的 clientId 与 Secret，即 Client ID 和 Client Secret
# 2.4 获取广告账户 ID
最后，您还需要获取准备拉取数据的广告账户的 ID，登录 Vivo 营销后台，点击右上角菜单中的「账号管理」，在账户中心板块的账号信息标签页中，可以获取账户 ID 信息。
# 三、回到 TE 后台，完成授权工作
完成 Vivo 后台的配置后，回到 TE 后台，进入到之前的创建的 Vivo 集成方案，点击「授权信息」：
接下来，请将您在 Vivo 后台获取到的 Client ID 和 Client Secret 并填入相应位置，Advertiser ID 中填入您在上一步中获取的广告账户 ID。完成编辑后点击保存按钮：
接着点击右上角的「保存并授权」，再次进入到授权信息弹窗。此时点击「前往授权」，将打开 Vivo 平台的授权页面
如果您有 Vivo 的广告主账号，建议您直接登录广告主账号；如果您
当您完成了授权之后，请在「授权信息」中点击左下角的「我已完成以上两步操作」后点击右下角的「完成授权」结束配置。至此，您完成了 Vivo 平台的数据集成。
# 四、数据入库
# 4.1 入库规则
- 由于创意报表是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 reportdate 或 reporttime 字段，即数据聚合时间，作为事件的 #event_time
- 默认的事件名为：vivo_ads_data
- 其他字段将全数入库
# 4.2 涵盖字段
广告创意数据支持拉取以下字段：
| 字段名 | 中文名与备注 |
|---|---|
| campaignid | 计划ID |
| campaignname | 计划名称 |
| mediatype | 推广计划类型 |
| groupid | 广告组ID |
| groupname | 广告组名称 |
| advertisementid | 广告ID |
| advertisementname | 广告名称 |
| creativeid | 创意ID |
| placetype | 广告位类型，详见【[附录-广告位枚举（广告报表）](https://open-ad.vivo.com.cn/doc/index?id=171)】 |
| apppackage | 包名 |
| cvtype | 转化类型，详见【[附录-广告组转化目标类型](https://open-ad.vivo.com.cn/doc/index?id=171)】 |
| reportdate | 上报时间，按天维度查询时返回，格式为:20200824 |
| reporttime | 上报时间，按小时维度查询时返回，格式为:2020-06-28 11:00:00 |
| advertiserid | 广告主ID |
| showcount | 曝光量 |
| clickcount | 点击量 |
| downloadcount | 下载量 |
| spent | 花费 |
| activatecount | 新增激活数 |
| registercount | 游戏注册量 |
| formsubmitcount | 表单提交量 |
| normalactivatecount | 普通激活数 |
| backactivatecount | 自定义激活数 |
| backregistercount | 自定义注册量 |
| adddesktopcount | 加桌数 |
| customretaincount | 自定义次留数 |
| gamepaycount | 游戏付费数 |
| custompaycount | 自定义付费数 |
| reactivation | 自定义拉活 |
| webpay | 网页购买 |
| gameappointment | 游戏预约数 |
| buttonclick | 按钮点击量 |
| fastapppay | 快应用付费数 |
| personalizedevents | 个性化事件数 |
| activatec | 新增激活数(按计费时间) |
| backactivatec | 自定义激活数(按计费时间) |
| registerc | 游戏注册量(按计费时间) |
| backregisterc | 自定义注册量(按计费时间) |
| adddesktopc | 加桌数(按计费时间) |
| cdownloadcount | 下载数(按计费时间) |
| customretainc | 自定义次留数(按计费时间) |
| gamepayc | 游戏付费数(按计费时间) |
| custompayc | 自定义付费数(按计费时间) |
| reactivationc | 自定义拉活(按计费时间) |
| gameappointmentc | 游戏预约数(按计费时间) |
| firstdayrecoveryadmonetizationc | 首日回收金额-广告变现(按计费时间) |
| totalrecoveryadmonetizationc | 累计回收金额-广告变现(按计费时间) |
| firstdayrecoverypaidrechargec | 首日回收金额-充值付费(按计费时间) |
| totalrecoverypaidrechargec | 累计回收金额-充值付费(按计费时间) |
| cfastapppay | 快应用付费数(按计费时间) |
| cpersonalizedevents | 个性化事件数(按计费时间) |
| cnormalactivatecount | 普通激活数(按计费时间) |
| ccreditcount | 自定义授信数(按计费时间) |
| cinstalldonecount | 安装完成数(按计费时间) |
| wechatgameregisterc | 微信小游戏注册数(按计费时间) |
| wechatgamepayc | 微信小游戏付费数(按计费时间) |
| creactivationretentioncount | 拉活自定义次留数(按计费时间) |
| creditcount | 自定义授信数(按转化时间) |
| installdonecount | 安装完成数(按转化时间) |
| wechatgameregistercount | 微信小游戏注册数(按转化时间) |
| wechatgamepaycount | 微信小游戏付费数(按转化时间) |
| reactivationretentioncount | 拉活自定义次留数(按转化时间) |
| reservecount | 日历预约数(按转化时间) |
| identifycodecount | 微信-识别二维码数 |
| addwechatmpacount | 微信-添加微信数 |
| dialoguempacount | 微信-用户首次消息数 |
| onedialoguecount | 有效咨询数 |
| firstdayrecoverypaidcount | 游戏首日首次付费 |
| tacount | 目标用户量(按转化时间) |
| ctacount | 目标用户量(按计费时间) |
| payonetimecount | 应用付费次数(按转化时间) |
| cpayonetimecount | 应用付费次数(按计费时间) |
| payonetimeamount | 应用付费金额(按转化时间) 单位为毫分（千分之一分），1元=100000毫分 |
| cpayonetimeamount | 应用付费金额(按计费时间) 单位为毫分（千分之一分），1元=100000毫分 |
# 4.3 标准化字段
TE 系统会对以下字段进行标准化处理：
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| advertiserid | te_ads_object.ad_account_id | 广告账号 ID |
| campaignid | te_ads_object.campaign_id | 广告计划id |
| campaignname | te_ads_object.campaign_name | 广告计划名称 |
| groupid | te_ads_object.ad_group_id | 广告组id |
| groupname | te_ads_object.ad_group_name | 广告组名称 |
| advertisementid | te_ads_object.ad_id | 广告创意id |
| advertisementname | te_ads_object.ad_name | 广告创意名称 |
| showcount | te_ads_object.impressions | 曝光量 |
| clickcount | te_ads_object.clicks | 点击量 |
| activatecount | te_ads_object.installs | 转化数 |
| spent | te_ads_object.cost | 买量成本 |