Campaign management

合作伙伴管理支付手段 (PMFI)

引导流程为 Twitter 账号配置 ads.twitter.com 账号，该账号可由合作伙伴通过广告 API 进行管理，其广告支出由合作伙伴承担。
 

合作伙伴初始设置

新 PMFI 广告 API 合作伙伴的初始设置，最多需要 3 周时间交换所需信息。必须与 Twitter 的技术联系人以及合作伙伴集成管理联系人共享以下内容，以便启动流程：

  • 合作伙伴必须共享其 PGP/GPG 公开密钥。广告 API 合作伙伴和 Twitter 需要交换共享密钥。这将用于在引导流程中认证数据。
  • 用于广告 API 访问的 Twitter 应用的 app_id 或 consumer_secret。 如果你已在 developer.twitter.com 上登录 Twitter 账号，则可以通过应用面板查看并编辑现有的 Twitter 应用。若要创建 Twitter 应用，则需要有经过批准的开发者账号。 Twitter 允许一个应用用于生产 + 沙盒，另一个可选应用仅用于沙箱访问。必须基于合作伙伴控制的公司 Twitter 用户名创建 Twitter 应用。
     

广告商引导流程

广告商引导流程按照以下方式通过 Web 浏览器进行：

  1. 用户在合作伙伴的网站上启动引导流程，并输入要引导的用户名。
  2. 合作伙伴将用户重定向到 ads.twitter.com 上签名的有效负荷 URL。此有效负荷包含合作伙伴 API app_id、要引导的 Twitter 用户名的 Twitter user_id 和回调 URL 以及其他字段，记录如下。
  3. 要求用户使用标准 twitter.com 登录页面登录 ads.twitter.com。
  4. 用户登录后，将启动引导流程。此步骤包含广告审核，账号验证和其他检查。
  5. 所有引导任务完成后，将用户重定向到广告 API 合作伙伴提供的回调 URL，其中包含指示成功或失败的有效负荷。这包含三方授权程序。
     

引导重定向有效负荷

重定向 URL：

https://ads.twitter.com/link_managed_account

将使用以下参数调用重定向 URL：

名称 类型 说明
callback_url URL 编码字符串 无论结果如何，用户将在账号链接流程完成后重定向到此 URL。有关协议详细信息，请参阅合作伙伴重定向 URL 部分
client_app_id 整数 Twitter API 客户端应用 ID，用于识别管理合作伙伴
promotable_user_id 整数 将由管理合作伙伴管理其推广的 @handle 的 Twitter user_id。用于确保其与登录 ads.twitter.com 完成链接流程的用户相同
fi_description URL 编码字符串（最多 255 个字符） 支付手段名称。当检索支付手段时，这将显示在 API 的说明字段中。如果给定 funding_instrument 说明，会暂停现有的 funding_instrument，并将建立一个新的管理合作伙伴支付手段。（如果与现有名称同名，则不会进行任何操作）
timezone 字符，采用区域/位置的格式 此为时区，用于确定应用每日预算以及汇总收费的日期
currency ISO 4217 货币代码 将用于输入出价和进行计费的货币
country ISO 3166-1 alpha 2 国家/地区代码 账号的计费国家/地区
signature URL 编码和 base64 编码的二进制代码，如下所述 结合共享机密和其他参数的签名，用于认证调用的真实性和参数的有效性。


回调 URL 有效负荷

使用账号链接请求的 callback_url 参数，提供基本重定向 URL（参见上文）。ads.twitter.com 添加的参数为：

名称 类型 说明
status string
OK：已创建账号，或已找到符合条件的现有账号。
ACCOUNT_INELIGIBLE：不符合合作伙伴特定限制 USER_MISMATCH：用于登录 ads.twitter.com 的 Twitter 账号与账号链接请求中的 promotable_user_id 不同 INCOMPLETE_SERVING_BILLING_INFO 未指定时区、货币或国家/地区 INVALID_COUNTRY：指定了无效的国家/地区值 INVALID_CURRENCY：指定了无效的货币值 INVALID_TIMEZONE：指定了无效的时区值
account_id URL 编码字符串 链接账号的 Twitter 广告账号 ID
funding_instrument_id URL 编码字符串 活跃合作伙伴管理的支付手段 ID
signature URL 编码和 base64 编码的二进制代码，如下所述 结合共享机密与其他参数的 base64 编码的 HMAC-SHA1 签名，用于验证调用的真实性和参数的有效性。为了确保回调 URL 仅对账号链接流程所针对的 Twitter user_id 有效，应在签署请求时将 twitter user_id 附加到共享密钥（使用 &）。

为了确保回调 URL 仅对账号链接流程所针对的 Twitter user_id 有效，应在签署请求时将 twitter user_id 附加到共享密钥（使用 &）。
 

签署请求和回调 URL

为了确保对 /link_managed_account 的请求和回调 URL 有效，必须在源位置签署请求并由接收者在对请求执行操作之前认证请求。使用 Twitter 与管理合作伙伴共享的密钥签署请求，可确保一方仅接受由获得授权的另一方发送的请求。

签名生成算法与 OAuth 中使用的类似。

创建签名基本字符串，如下所示：

  • 将 HTTP 方法转换为大写字母，并将基本字符串设置为等于此值。
  • 将“&”字符附加到基本字符串。
  • 对 URL 进行百分号编码（不带参数），并将其附加到基本字符串。
  • 将“&”字符附加到基本字符串。
  • 附加经过百分号编码的查询字符串，其构建方式如下：
  • 对要签署的每个键和值进行百分号编码。
  • 按键的字母顺序对参数列表进行排序。
  • 对于每个键/值对（以及合作伙伴重定向 URL 的 primary_promotable_user_id）：
  • 将百分号编码的键附加到查询字符串。
  • 将“=”字符附加到基本字符串。
  • 将百分号编码值附加到查询字符串。
  • 用“&”字符分隔百分号编码的键=值对。
  • 使用 HMAC-SHA1 算法，以先前交换的共享密钥作为键，以基本字符串作为值，生成签名。
  • base64 对步骤 2 的输出进行编码，删除在步骤 3 中生成签名的尾部换行符百分号编码，并将其添加至签名参数中的 URL
     

签署示例

签署链接账号请求

要签署的 URL，假设 GET 请求：

https://ads.twitter.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1

此 URL 具有以下参数：

callback_url = https://managingpartner.com/link_account_callback
client_app_id = 12345
fi_description = some name
promotable_user_id = 1

通过步骤 a - d 生成的由 http 方法和不带参数的 URL 组成的基本字符串类似如下所示：

GET https://ads.twitter.com/link_managed_account

e 的子步骤生成的查询字符串类似如下所示：

callback_url=https://managingpartner.com/link_account_callback&client_app_id=12345&fi_description=some name&promotable_user_id=1

注意，键-值对按键名称排序。

经过百分号编码的查询字符串类似如下所示：

callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

结合步骤 a - d 和 e 产生的完整基本字符串：

GET https://ads.twitter.com/link_managed_account&callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

使用 hmac-sha1 算法，以“secret”为键进行签署。结果采用 Base64 编码，不显示最终的“ ”（步骤 2 和 3）：KBxQMMSpKRrtg9aw3qxK4fTXvUc=

然后，将此签名添加（百分号编码）到签名参数中原始 URL 的末尾（步骤 4）：

https://ads.twitter.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D

签署合作伙伴重定向 URL（账号链接请求回调）要签署的 URL，假设 GET 请求：

https://managingpartner.com/link_account_callback?status=OK&account_id=ABC&funding_instrument_id=DEF

此 URL 具有以下参数：

account_id = ABC、funding_instrument_id = DEF 并且 status = OK

通过步骤 a - d 生成的由 http 方法和不带参数的 URL 组成的基本字符串类似如下所示：

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&``

e 的子步骤生成的查询字符串类似如下所示：

account_id=ABC&funding_instrument_id=DEF&status=OK

经过百分号编码的查询字符串类似如下所示：

account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

结合步骤 a - d 和 e 产生的完整基本字符串：

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

使用 hmac-sha1 算法，以“secret”、原始链接请求针对的 Twitter 用户 ID、1（promotable_user_id = 上述的 1）为键（也就是“secret&1”）进行签署。

结果采用 Base64 编码，不显示最终的“ ”（步骤 2 和 3）：jDSHDkHJIFXpPLVxtA3a9d4bPjM=

然后，将此签名添加（百分号编码）到签名参数中原始 URL 的末尾（步骤 4）：

https://managingpartner.com/link_account_callback?&status=OK&account_id=ABC&funding_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D


共享密钥的使用/更新

签署算法应该能够用多个密钥重复它本身。这样可以使用多个共享密钥，并且定期循环共享密钥。
 

partner_managed_funding_instrument 创建

如果给定 fi_description parameter，且账号中不存在同名的 partner_managed_funding_instrument，则会创建新的 partner_managed_funding_instrument，并且会暂停所有现有的 partner_managed_funding_instrument。

如果存在同名的 partner_managed_funding_instrument，则不会新建一个。
 

重复引导流程回调/令牌更新

如果 API 访问令牌丢失，可以重复引导流程。实施引导流程需要用户处于已登录状态。如果用户匹配 promotable_user_id、已找到关联的广告账号，并且一切正常，则会将用户重定向回到回调 URL，合作伙伴可以启动 OAuth 流程，获取访问令牌。
 

不可重定向的错误流程

如果使用无效参数调用了账号链接 URL，则在给定无效或过期参数时，系统会向用户显示与 OAuth 流程中类似的页面。
 

PMFI 的持续更新

引导广告商后，只能由管理支付手段的合作伙伴使用 PUT accounts/:account_id/funding_instruments/:funding_instrument_id 端点对支付手段进行管理。