语言 

推广活动 API

使用推广活动 API,即可获得跟踪链接、子跟踪链接和合作伙伴信息,无需通过 Adjust 控制面板。利用此功能,您也可以远程创建多个跟踪链接,访问应用的所有渠道、推广、广告组和素材级别跟踪链接。

阅读本文,了解如何通过向推广活动 API 发起查询来创建、接收跟踪链接和推广活动信息。

使用案例

对于想要灵活且高效地开展推广活动的营销人员,推广活动 API 是一款强大的工具。请查看下面的例子,了解如何最大程度上发挥推广活动 API 的优势。

使用情景​ :一位旅游业的客户正在针对不同地区的用户开展新的促销活动。该客户将通过 AppLovin 和 AdColony 进行推广。为了推广活动顺利开展,需要按地区创建新跟踪链接,还需要跟踪这些推广活动的广告支出。

该客户可通过推广活动 API 达成以上目的,方法如下:

  1. 要想查看是否已有针对 AppLovin 和 AdColony 的跟踪链接,客户需要使用 GET Network Trackers​ 。
  2. 如果不存在已有跟踪链接,则可以针对两个合作伙伴使用 CREATE Network Tracker (level 1)​ 。
  3. 要获得 AppLovin 和 AdColony 的合作伙伴 ID,可以用 GET Partner List​ 。
  4. 有了合作伙伴 ID 后就可以将创建好的跟踪链接关联到合作伙伴并通过 UPDATE Tracker​ 设置成本参数了。

完成这四个步骤后,客户便有了一个带有默认 AppLovin 和 AdColony 推广结构的跟踪链接,并且带有相应渠道的成本参数和其他默认参数。

版本控制

有重要更新发布时,Adjust 推广活动 API 版本号也会随之更新;如果是小更新,无重大变更,则版本号不需要更新。API 版本需要在所有请求的 URL 路径中设置。

版本 1 示例: https://api.adjust.com/public/v1/apps/{{app_token}}/trackers

请注意:
以下文档仅适用于 API V1 版本。

API 认证

要访问推广活动 API,需要确认与用户关联的 API 识别码请按照此处步骤查找 API 识别码

API 识别码和其控制面板用户拥有相同的用户权限

使用 API 时,若要认证请求,请为请求添加以下 HTTP 标头:

Authorization: Token token=user_token_here

响应格式

向推广活动 API 发出的请求为 application/json 格式,返回的响应为 json 格式。

响应结构大致基于 Google 的 JSON API 规范指南

成功响应

请求成功时,推广活动 API 响应结构如下:

{
  "data": {
    "api_version": //request_api_version,
    "request_id": //alphanumeric_request_id,
    "timestamp": //server_timestamp,
    "paging": {
      "page_size": //page_size,
      "collection_size": //total_elements_on_current_page,
      "total": //total_elements,
      "next": //url_for_next_page,
      "previous": //url_for_previous_page,
      "cursors": {
        "after": //after_cursor,
        "before": //before_cursor
      },
    },
    "items": [
     /// The list of elements requested
    ]
  }
}

字段定义:

字段格式描述示例
api_version字符串API 响应的版本 (应匹配用户发起请求时指定的版本)1
request_id字符串用户请求的唯一标识符FcK55-tdJUDOWQIAABsB
timestampstring YYYY-MM-DDTHH:MM:MMZ请求时服务器上的日期和时间2019-09-09T09:07:06Z
paging对象包含分页的字段 
paging.total字符串 (数字)数据库中的元素数量总计1000
paging.page_size字符串 (数字)当前页的最大元素数量50
paging.collection_size字符串 (数字)当前页的元素数量49
paging.next字符串 (URL)获得下一页结果的链接。如果当前页为末页,则该项为“nil”https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.previous字符串 (URL)获得上一页结果的链接。如果当前页为首页,则该项为“nil”https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?before=g2wAAAACYhW1_gxkAANuaWxq&limit=50
paging.cursors对象包含用于分页的游标 (下一章中将有更多的分页信息) 
paging.cursors.after字符串用于获取下一页的游标,需要指定g2wAAAACYhW1_gxkAANuaWxq
paging.cursors.before字符串用于获取下一页的游标,需要指定g2wAAAACYhW1_gxkAANuaWxq
items数组从 API 请求的元素的列表 (参见相应终端文档中对 item 的描述) 

错误响应

发生错误时,推广活动 API 响应结构如下:

{
  "error": {
    "api_version": //request_api_version,
    "request_id": //alphanumeric_request_id,
    "timestamp": //server_timestamp,
    "message": //error_message
  }
}

字段定义:

字段格式描述示例
api_version字符串API 响应的版本 (应匹配用户发起请求时指定的版本)1
request_id字符串用户请求的唯一标识符FcK55-tdJUDOWQIAABsB
timestampstring "YYYY-MM-DDTHH:MM:MMZ"请求时服务器上的日期和时间2019-09-09T09:07:06Z
message字符串对应的错误信息,显示请求失败的原因"User not authenticated"

速率限制

  • 每分钟 每用户​ 50 次请求。

当超过推广活动 API 终端的速率限制时,API 会返回 HTTP 429 “Too Many Requests” 响应代码。

数据请求 (GET 请求) 将返回分页结果,其中包含下一页和前一页结果的 URL。推广活动 API 使用基于游标的分页,每个 GET 响应都包含 after 和 before 游标。此外,每个请求都会接受含游标值的 after 和 before 参数。

默认页面上限为 50 个元素。要自定义页面上限,请使用 limit 参数。

示例:

要为 app_token 为 yxs12pfewq 的应用获得跟踪链接,请发送初始请求:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers

响应中会包含一个 “paging“ 部分,如下:

"paging": {
      "page_size": "50",
      "collection_size": "49",
      "total": "199"
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil // (the first page has no previous page)
      },
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50",
      "previous": nil // (the first page has no previous page)
    }

要转到第二页,请在发出下一个 GET 请求时,向参数 (附带相应的参数名称) 中添加 after 值 (位于游标内)。例如:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq

或仅使用分页元素中 next 属性的 URL:

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50

要转到前页,请按照相同的流程操作,但使用 before 值,或使用 previous 属性的 URL。

终端

获取渠道跟踪链接

使用此终端,为您指定的应用获得渠道层跟踪链接。

终端

GET https://api.adjust.com/public/v1/apps/{app_token}/trackers

URL 参数

参数格式描述示例
app_token字符串应用识别码yxs12pfewg

查询参数

参数格式描述示例
After字符串从下一页获取元素的游标 (可选)g2wAAAACYhW1_gxkAANuaWxq
Before字符串从上一页获取元素的游标 (可选)g2wAAAACYhYGiAhkAANuaWxq
limit不小于 0 的数字所请求页的最大元素数量50

响应格式

对象定义

字段格式描述示例
name字符串跟踪链接名称Adroll
label字符串跟踪链接名称中最后一个层级的部分Adroll
level整数跟踪链接的层级,根据 Adjust 推广活动结构,渠道 = 1,推广 = 2,广告组 = 3,素材 = 41
archived布尔 (true/false)显示跟踪链接是否已归档true
has_subtrackers布尔 (true/false)表明跟踪链接是否带有子跟踪链接true
partner_id整数显示附加在跟踪链接上的合作伙伴 ID,例如,我们合作伙伴 Adroll 的 ID 是 33
cost_data_enabled布尔 (true/false)显示跟踪链接是否已启用 cost_datafalse
impression_url字符串展示跟踪链接的 URLhttps://view.adjust.com/impression/abc123
url字符串跟踪链接 URLhttps://app.adjust.com/abc123
click_url字符串点击跟踪链接的URLhttps://app.adjust.com/abc123

对象示例:

{
  "name": "Adroll",
  "token": "abc123",
  "label": "Adroll",
  "level": 1,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/abc123",
  "click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
  "impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
 }

响应示例 (仅包含单一跟踪链接):

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?limit=1

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "label": "Adroll",
        "level": 1,
        "name": "Adroll",
        "token": "abc123",
        "url": "https://app.adjust.com/abc123",
        "click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
        }
        ]
  }
}

获取子跟踪链接

使用此终端,为指定的跟踪链接获得子跟踪链接。

终端

GET https://api.adjust.com/public/v1/apps/{app_token}/trackers/{tracker_token}/children

参数格式描述示例
app_token字符串应用识别码yxs12pfewq
tracker_token字符串跟踪码abc123

查询参数

参数格式描述示例
After字符串从下一页获取元素的游标 (可选)g2wAAAACYhW1_gxkAANuaWxq
Before字符串从上一页获取元素的游标 (可选)g2wAAAACYhYGiAhkAANuaWxq
limit不小于 0 的数字所请求页的最大元素数量50

响应

返回的结果将采用 响应格式,列出子跟踪链接

对象定义

字段格式描述示例
name字符串跟踪链接名称Adroll::SpringCampaign
label字符串跟踪链接名称中最后一个层级的部分SpringCampaign
level整数跟踪链接层级2
archived布尔 (true/false)显示跟踪链接是否已归档true
has_subtrackers布尔 (true/false)表明跟踪链接是否带有子跟踪链接true
partner_id整数显示附加在跟踪链接上的合作伙伴 ID3
cost_data_enabled布尔 (true/false)显示跟踪链接是否已启用 cost_datafalse
impression_url字符串展示跟踪链接的 URLhttps://view.adjust.com/impression/abc123
url字符串跟踪链接 URLhttps://view.adjust.com/impression/abc123

对象示例:

{
  "name": "Adroll::SpringCampaign",
  "token": "xyz456",
  "label": "SpringCampaign",
  "level": 2,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?idfa={idfa}&s2s=1",
 }

响应示例 (包含一个跟踪链接):

GET https://api.adjust.com/public/v1/apps/yxs12pfew/trackers/abc123/children?limit=1

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfew/trackers/abc123/children?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "name": "Adroll::SpringCampaign",
        "token": "xyz456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?idfa={idfa}&s2s=1",
      }
    ]
  }
}

创建跟踪链接

使用此终端,创建新的跟踪链接或子跟踪链接。

终端:POST https://api.adjust.com/public/v1/apps/{app_token}/trackers

URL 参数

参数格式描述示例
app_token字符串应用识别码yxs12pfewg

请求正文

请求正文可以查询参数或 application/json 内容格式发送。

参数格式描述示例
name字符串新跟踪链接的名称Adroll
parent_token字符串父级跟踪链接的跟踪码 (仅在创建子跟踪链接时需要)abc123

请求示例:

渠道跟踪链接 - json payload 示例:

POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
}

子跟踪链接 (任意层级)- json payload 示例:

POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
  "parent_token": "abc123"
}

响应:

返回的结果将采用 响应格式,包含您的新跟踪链接

对象定义

字段格式描述示例
name字符串跟踪链接名称Adroll::Spring Campaign::PubID123
label字符串跟踪链接名称中最后一个层级的部分PubID123
level整数跟踪链接的层级,根据 Adjust 推广活动结构,渠道为 1,推广活动为 2,广告组为 3,素材为 43
archived布尔 (true/false)显示跟踪链接是否已归档true
has_subtrackers布尔 (true/false)/td>表明跟踪链接是否带有子跟踪链接true
partner_id整数显示附加在跟踪链接上的合作伙伴 ID,例如,我们合作伙伴 Adroll 的 ID 是 33
cost_data_enabled布尔 (true/false)显示跟踪链接是否已启用 cost_datatrue
impression_url字符串展示跟踪链接的 URLhttps://view.adjust.com/impression/xyz456
url字符串跟踪链接 URLhttps://view.adjust.com/impression/xyz456

对象示例:

{
  "name": "Adroll::SpringCampaign::PubID123",
  "token": "ghi789",
  "label": "PubId123",
  "level": 3,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/ghi789",
"click_url": "https://app.adjust.com/ghi789?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/ghi789?idfa={idfa}&s2s=1",
 }

响应示例 (针对渠道层跟踪链接):

POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "name": "Adroll"
}

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adroll",
        "token": "abc123",
        "label": "Adroll",
        "level": 1,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/abc123",
"click_url": "https://app.adjust.com/abc123?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/abc123?campaign={campaign_name}&idfa={idfa}&s2s=1",
      }
    ]
  }
}

响应示例 (针对子跟踪链接):

POST https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers
{
  "parent_tracker": "Adroll"
  "name": "SpringCampaign"
}

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adroll::SpringCampaign",
        "token": "xyz456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/xyz456",
"click_url": "https://app.adjust.com/xyz456?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
"impression_url": "https://s2s.adjust.com/impression/xyz456?campaign={campaign_name}&idfa={idfa}&s2s=1",
      }
    ]
  }
}

更新跟踪链接

使用此端点,用户可以更新跟踪链接。

终端:

PATCH https://api.adjust.com/public/v1/apps/{app_token}/trackers/{tracker_token}

URL 参数

参数格式描述示例
app_token字符串应用识别码yxs12pfewq
tracker_token字符串跟踪码abc123

请求正文

请求正文可以查询参数或 application/json 内容格式发送。API 只会更新指定的参数,没有任何参数是必需的。

参数格式描述示例
partner_id整数将被附加在跟踪链接上的合作伙伴 ID1
cost_data_enabled布尔 (true/false)显示跟踪链接是否应启用成本数据true

请求示例:

json payload 示例:

PATCH https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers/abc123
{
  "partner_id": 1,
  "cost_data_enabled": false
}

响应

响应将采用响应格式,返回更新后的跟踪链接。

对象定义

字段格式描述示例
name字符串跟踪链接名称AdColony
label字符串跟踪链接名称中最后一个层级的部分AdColony
level整数跟踪链接的层级,根据 Adjust 推广活动结构,渠道为 1,推广活动为 2,广告组为 3,素材为 41
archived布尔 (true/false)显示跟踪链接是否已归档true
has_subtrackers布尔 (true/false)表明跟踪链接是否带有子跟踪链接true
partner_id整数显示附加在跟踪链接上的合作伙伴 ID,例如,我们合作伙伴 Adcolony 的 ID 是 174174
cost_data_enabled布尔 (true/false)显示跟踪链接是否已启用 cost_datatrue
impression_url字符串展示跟踪链接的 URLhttps://view.adjust.com/impression/klm789
url字符串跟踪链接 URLhttps://view.adjust.com/impression/klm789

对象示例:

{
  "name": "Adcolony",
  "token": "klm789",
  "label": "Adcolony",
  "level": 1,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 174,
  "cost_data_enabled": true,
  "url": "https://app.adjust.com/klm789",
  "impression_url": "https://s2s.adjust.com/impression/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=  [IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD,
   "click_url": "https://s2s.app.adjust.com/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=[IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD"
 }

响应示例:

PATCH https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers/klm789?partner_id=174&cost_data_enabled=true

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "items": [
      {
        "name": "Adcolony",
        "token": "klm789",
        "label": "Adcolony",
        "level": 1,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 174,
        "cost_data_enabled": true,
        "url": "https://app.adjust.com/klm789",
        "impression_url": "https://s2s.adjust.com/impression/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=  [IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD,
        "click_url": "https://s2s.app.adjust.com/klm789?s2s=1&idfa=[IDFA]&gps_adid=[GOOGLE_AD_ID]&ip_address=[IP_ADDRESS]&adcolony_click_id=[CLICK_ID]&android_id_upper_sha1=[SHA1_ANDROID_ID]&cost_id=[CLICK_ID]&cost_type=[BID_TYPE]&cost_amount=[BID]&cost_currency=USD"
      }
    ]
  }
}

获取合作伙伴

使用此终端,获得合作伙伴列表。

Endpoint: GET https://api.adjust.com/public/v1/partners

查询参数

参数格式描述示例
After字符串从下一页获取元素的游标 (可选)g2wAAAACYhW1_gxkAANuaWxq
Before字符串从上一页获取元素的游标 (可选)g2wAAAACYhYGiAhkAANuaWxq
limit不小于 0 的数字所请求页的最大元素数量50

响应:

返回的结果将采用 响应格式,列出合作伙伴。

对象定义:

字段格式描述示例
id整数合作伙伴的 ID174
display_name字符串合作伙伴名称AdColony
support_cost_data布尔 (true/false)显示合作伙伴是否支持成本数据参数true

对象示例:

{
  "id": 174,
  "display_name": "Adcolony",
  "supports_cost_data": true
 }

响应示例 (包含一个合作伙伴):

GET https://api.adjust.com/public/v1/partners?limit=1

{
  "data": {
    "api_version": "1",
    "request_id": "FcK55-tdJUDOWQIAABsB",
    "timestamp": "2019-09-09T09:07:06Z",
    "paging": {
      "page_size": "1",
      "collection_size": "1",
      "total": "199",
      "next": "https://api.adjust.com/public/v1/partners?after=g2wAAAACYhW1_gxkAANuaWxq&limit=1",
      "previous": nil,
      "cursors": {
        "after": "g2wAAAACYhW1_gxkAANuaWxq",
        "before": nil
      }
    },
    "items": [
      {
        "id": 174,
        "display_name": "Adcolony",
        "supports_cost_data": true
      }
    ]
  }
}