接口文档SDK业务专题开发者工具

快速入门

本节将为您介绍如何成为Marketing API开发者,开启您的智能化营销体验生活。

在调用Marketing API接口前,您必须先注册成为开发者并创建应用申请对应的接口权限。以下将分别为您介绍开发者注册以及应用创建的具体流程。请您重点关注文档中加粗、变色部分的描述。

1. 如何注册成为开发者?

当您决定开始使用Marketing API进行接口调用,您需要首先注册成为开发者:

Step 1:进入注册页面。点击开发者官网右上角注册按钮即可进入;

Step 2:关联QQ号作为开发者登录凭证。进入注册页面后,如果当前电脑已经登录QQ客户端,则默认显示以当前登录QQ号作为快捷登录,您也可以点击“帐号密码登录”换用其他QQ号;
Tips:

  1. 关联QQ号是开发者登录的唯一凭证,且不能进行修改。对于企业开发者,建议使用公用QQ帐号进行注册,并妥善保管。

  2. 如果您已经是腾讯社交的客户(代理商或广告主),建议您直接用代理商帐号或广告主帐号的开户QQ进行注册。

Step 3:完善开发者资料。将资料填写完整并通过手机验证码验证通过后,即完成开发者注册。

2. 如何创建应用程序并申请权限?

2.1 开发者应用的分类及作用

通过腾讯广告开发者专区创建的应用程序是指基于Marketing API开发的应用,比如管理广告的投放平台、广告数据分析工具、自动化营销的脚本等。创建应用程序的目的是为了获取所需接口在正式环境的调用权限。在获取正式环境的接口权限前,建议您先通过沙箱环境进行接口调试。

开发者应用按注册者类型和权限范围,可以分为私有应用第三方应用两类(每一类应用最多可申请20个)。下面将介绍这两类应用的适用场景及具体差异。

私有应用

当您的开发者注册QQ同时是代理商、广告主、商务管家等身份的开户QQ时,您可创建私有应用,通过该应用,您可以直接操作注册QQ对应的账号名下的广告身份(如代理商可操作代理商本人及其子客信息,商务管家账号可以操作商务管家账号下认领的广告账号信息)。

Tips:

  • 私有应用仅能管理注册QQ对应的账号身份,不可以进行第三方授权(oAuth授权)管理其他账号。
  • 与第三方应用相比,私有应用在权限审核、令牌获取等场景门槛较低。

第三方应用

当您希望通过Marketing API管理多广告账号、或为广告行业提供第三方技术服务时,您可以通过创建第三方应用来实现。

Tips:

  • 无论开发者注册QQ是否拥有广告业务身份,您均可以注册第三方应用
  • 该QQ身份为开发者身份的唯一凭证,建议使用公司公共QQ注册,避免后续人员变动导致的账号权限问题。
  • 支持第三方授权(oAuth授权),因此为了保证数据安全性,第三方应用的权限审核相较私有应用会更加严格

2.2 应用的申请及创建

Step1: 注册成为开发者后,在开发者官网进行登陆并进入应用程序管理看板,可选择创建私有应用或第三方应用(私有应用的前置条件是您的开发者注册QQ账号同时为代理商、广告主、商务管家等身份的开户QQ),则界面会显示相应的创建入口如下图:

Step 2:点击“创建新应用”进入创建应用程序界面,填写应用名称、应用介绍信息等。请注意,私有应用需要填写的内容比第三方应用少,但仅可管理该QQ号对应的广告账号。

  • 应用图标:360 x 360 px 的应用图标。
    • 显示在OAuth 2.0 授权页面中,作为推广客户(服务商/广告主)识别应用的标识
  • 应用名称:应用程序的名称,多个应用程序不允许重名。
    • 显示在OAuth 2.0 授权页面中,作为推广客户(服务商/广告主)识别应用的标识
  • 应用介绍:介绍您的应用程序希望基于Marketing API实现的功能及您需要功能通过审核的原因。
  • 回调地址将用于OAuth 2.0授权完成后的跳转及信息返回到您指定地址,供您获取相关返回信息,详情可参考发起请求
  • Access Token有效期:该应用下access token的有效时长,默认为24小时
  • Refresh Token有效期:该应用下refresh token的有效时长,默认为30天,refresh token有效期需大于access token。
  • 注:access token 和 refresh token详细介绍见授权认证

Step 3:您可根据使用需要选择对应的权限组分类,权限组分类的详细介绍可通过权限等级进一步了解 – 创建后,私有应用自动审核通过,您可以立即开始相关能力的搭建。第三方应用则会在2-3个工作日内进行审核。

  • 如您的应用还未开发完成,建议先使用沙箱环境进行调试。
  • 第三方应用的开发者可根据获取到的应用程序id(client_id)及client_secret,以此发起OAuth 2.0 授权获得指定推广帐号的操作权限,详情参考授权认证

3. 发起请求,开启智能化营销体验

3.1 授权认证{ #auth }

Token是在Marketing API操作指定账号的身份凭证,当您需要操作特定广告账号时,您需要使用该广告账号对您的开发者应用进行授权,以获取access_token和refresh_token,所有接口均通过请求参数中传递的 access_token(授权令牌)来进行身份认证和鉴权,系统会在校验 access_token有效、接口调用配额未用完、接口调用频次未超限3个条件符合后接受此次请求进行具体业务处理并做出响应。

Marketing API目前支持腾讯广告平台用户及微信公众平台广告主两种账号进行授权鉴权。

注:微信公众平台广告主授权获得的token,目前仅支持异步任务下载广告报表、表单线索查询、广告粉丝数据查询、用户行为数据上报、人群上传等部分接口的调用。

本节将为您介绍如何进行 Marketing API 的授权认证 。

该环节您可以获取指定账号的access_token和refresh_token,其中:

  • access_token是您调用接口时,操作指定广告账号的身份凭证,默认有效期24小时。您可以通过开发者应用管理页面,修改该token的有效时长
  • refresh_token是用于刷新access_token的凭证,用于向系统获取新的access_token(具体操作方法见后文),默认有效期30自然日,每次刷新access_token的操作可自动刷新refresh_token有效期的起始计算时间
  • 大量使用错误的token操作账号的行为可能导致您的IP被封停,请您关注并监控错误信息

3.1.1 私有应用如何获取access_token和refresh_token

进入应用详情界面

  1. 首先选择您要操作的账户身份:如广告主、服务商、商务管家、T1等(因同一个QQ可以同时具有多个身份,不同的身份的token是不同的)。

  2. 点击“获取或重置”即可获取或者重置您的token

  • token信息获取时仅展示一次,请妥善保存
  • token生成后10分钟后生效
  • 重置token,该身份下在该应用上的旧 refresh_token 和 access_token 会立即失效

3.1.2 第三方应用如何通过 OAuth 2.0 获得 access_token

客户需要通过您的应用进行推广操作时,您的应用需要先引导客户完成至少一次 OAuth 2.0 认证操作,以便获得调用接口操作的客户的推广帐号所必须的 access_token 。Marketing API的 OAuth 2.0 遵循业界通用的规范和流程,完成 OAuth 2.0 认证(当前只支持 server-side 模式)需要完成以下步骤:

  • A、引导客户进入 OAuth 2.0 登录界面;
  • B、客户用推广帐号登录(基于QQ号的使用开户QQ或自理管理员QQ,基于微信号的使用微信公众号或代理商管理员对应的微信账号扫码),;
  • C、登录成功并确认授权后广点通向您的应用程序返回一个授权码(Authorization Code);
  • D、应用程序调用接口用授权码(Authorization Code)获得 access_token,同时获得一个用于刷新 access_token 的 refresh_token;
  • E、在 access_token 过期后,使用 refresh_token 获得新的 access_token(可选)。

详细描述如下:

Step 1:引导客户完成OAuth 2.0认证获得authorization_code,获得 authorization_code 需要引导客户完成 OAuth 2.0 的认证。调用 OAuth 2.0 授权页面的URL形如:https://developers.e.qq.com/oauth/authorize?client_id=123456&redirect_uri=https%3a%2f%2fwww.example.com%3fpara1%3da%26para2%3db&state=&scope=ADS_MANAGEMENT&account_type=ACCOUNT_TYPE_QQ 。其中:

  • client_id:开发者创建的应用程序的唯一标识id,必填,可通过应用程序管理页面查看;

  • redirect_uri:回调地址,由开发者自行提供和定义(地址主域需与开发者创建应用程序时登记的回调主域一致),用于跳转并接收回调信息,必填,该字段需要做UrlEncode,确保后续跳转正常;

  • state:开发者自定义参数,可用于验证请求有效性或者传递其他自定义信息,回调的时候会原样带回,可选;

  • scope:授权的能力范围,可选,不传时表示授权范围为当前应用程序所拥有的所有全部权限;

  • account_type:授权用的账号类型,可选,包括QQ号和微信号,不传时默认为QQ号

  • OAuth 2.0 授权页面如下图所示:

  • 其中页面右侧为应用程序信息,左侧为请求授权的帐号信息,客户可以切换选择是用QQ号还是用微信号,推荐开发者直接在引导客户进入授权页时通过account_type指定要授权的账号类型。

  • 右侧显示的是应用程序的logo、名称、以及可授权的权限组分类。

  • 其中logo、名称是创建应用程序时开发者自行上传的信息,可授权的权限组分类是根据开发者调用oauth/authorize接口同步的scope生成的权限组信息;

  • 授权客户可通过列表选择授权给开发者的操作权限。

  • 左侧是提供给授权客户进行身份验证的入口。如客户同意授权,需要登录其对应的QQ帐号或者用微信号扫码,并点击同意授权。登录后,页面将会显示请求授权的账号信息。不同类型的帐号在同意授权后,应用可操作的推广帐号不同,具体规则如下:

  • 如果请求授权的是 腾讯广告平台的代理商帐号,代理商需用开户 QQ 登录并同意授权,完成 OAuth 2.0 后应用获得 access_token,该应用会获得当前代理商所有子客户的操作权限

  • 如果请求授权的是 腾讯广告的直客帐号,客户用 开户 QQ 登录并同意授权,完成 OAuth 2.0 后应用获得 access_token,该用户会获得 当前客户的操作权限

  • 如果请求授权的是 腾讯广告的商务管家帐号,客户用 开户 QQ 登录并同意授权,完成 OAuth 2.0 后应用获得 access_token,该用户会获得 当前商务管家账号下关联帐号 的操作权限

  • 如果请求授权的是 腾讯广告代理商子客户,用子客户的 自理管理员 QQ(由代理商分配)登录并同意授权,完成 OAuth 2.0 后应用获得 access_token,该应用会获得 当前子客户推广帐号 的操作权限

  • 如果请求授权的是 微信公众平台的代理商帐号,代理商用 管理员微信 扫码并同意授权,完成 OAuth 2.0 后应用获得 access_token,该应用会获得 当前代理商及所有代理子客户的操作权限;用运营管理员、运营人员微信 扫码并同意授权,则该应用会获得当前扫码人员名下管理的代理商子客操作权限

  • 如果请求授权的是微信公众平台的广告主帐号,客户用 微信公众号对应的管理员微信 扫码并同意授权,完成 OAuth 2.0 后应用获得 access_token,该用户会获得 当前客户推广帐号 的操作权限

    • 当引导客户在上述登录界面完成登录身份验证后,系统会携带 authorization_code(有效期5分钟)和state两个参数在浏览器端发出GET请求,形如:http://www.example.com/response?authorization_code=6a6b6c6d&state=112233

    • 当上述请求完成或请求链接超出3秒时,系统会自动跳转到刚才定义的回调地址中。您的应用程序在收到上述返回后,应当在 authorization_code 有效期内,利用 authorization_code 获得 access_token(详见下一步),并在跳转后的页面对客户给出相应的提示或跳转指引。

Step 2:使用 authorization_code 获得 access_token 和 refresh_token。用 authorization_code 获得 access_token 和 refresh_token 的接口地址为https://api.e.qq.com/oauth/token ,接口输入参数如下表所示:

请求参数:

字段名 类型 描述
client_id integer 应用 id,在开发者官网创建应用后获得,可通过 应用程序管理页面 查看
client_secret string 应用 secret,在开发者官网创建应用后获得,可通过 应用程序管理页面 查看
字段长度最小 1 字节,长度最大 256 字节
grant_type string 请求的类型,可选值: authorization_code (授权码方式获取 token )、 refresh_token (刷新 token )
字段长度最小 1 字节,长度最大 64 字节
authorization_code string OAuth 认证 code,可通过获取 Authorization Code 接口获取,当 grant_type=authorization_code 时必填
字段长度最小 1 字节,长度最大 64 字节
refresh_token string 应用 refresh token,当 grant_type=refresh_token 时必填
字段长度最小 1 字节,长度最大 256 字节
redirect_uri string 应用回调地址,当 grant_type=authorization_code 时, redirect_uri 为必传参数,仅支持 http 和 https,不支持指定端口号,且传入的地址需要与获取 authorization_code 时,传入的回调地址保持一致
字段长度最小 1 字节,长度最大 1024 字节

请求示例:

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=authorization_code' \ 
    -d 'authorization_code=<AUTHORIZATION_CODE>' \
    -d 'redirect_uri=https://www.example.com'

返回示例:

{
    code: 0,
    message: ,
    data: {
        access_token: 228bd56b7ee039540953352f766b40d31651487e,
        refresh_token: 854e744a1f4c6fc20f498e366b9aabd2c4b971fd,
        access_token_expires_in: 86400,
        refresh_token_expires_in: 2592000 
    }
}

获得 access_token 后,您可用此调用接口对相关的推广帐号进行操作,如果发起Marketing API请求可通过发起请求章节进行了解。

值得注意的是,一旦 access_token 失效,您将无法调用接口。access_token 和 refresh_token 的有效期可以通过 oauth/token 接口的返回字段获取,默认情况下 access_token 和 refresh_token 的有效期如下:

  • access_token默认有效期为24小时
  • refresh_token默认有效期为30天

3.1.3 如何刷新access_token

在refresh_token有效期内,您可以用 refresh_token 通过 auth/token 接口刷新 access_token。请求示意如下:

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=refresh_token' \
    -d 'refresh_token=<REFRESH_TOKEN>'

特别注意,每次刷新access_token时, refresh_token会自动续期。

3.1.4 如何刷新refresh_token

如果 refresh_token 失效,您需要重新通过 OAuth 2.0 获得新的 access_token 和 refresh_token 。

关于 OAuth 2.0 相关接口说明,可以参考接口清单中的 OAuth 相关接口

4. 常见问题

  1. 开发者官网的应用程序与推广的应用程序有什么关系?

开发者官网的应用程序是指基于Marketing API开发的应用,比如管理广告的投放平台、广告数据分析工具、自动化营销的脚本等等,而推广的应用程序是指广告主推广的目标应用。两者之前并无任何关联。

  1. 我需要为多个应用上报行为数据,需要分别创建应用程序么?

不需要。您只需创建一个应用程序,并申请数据上报的权限即可。一个应用可以获得多个推广帐号的授权,从而帮多个推广帐号上报数据。

  1. 应用程序审核通过后,是否就可以操作推广帐号了?

应用程序的审核是指给应用程序分配相应的接口权限,但是应用程序能操作哪些推广帐号,需要通过OAuth 2.0向指定的推广帐号发起授权申请,当指定的推广帐号同意授权后,应用程序即可调用接口对该帐号进行操作。