推广活动 API

如何使用推广活动 API?

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

下面我们举个例子,更好地阐释一下此功能的使用场景。想象一下:一位从事旅游业的客户打算为不同地区的用户推出新优惠,计划通过 AppLovin 和 AdColony 进行新的推广活动。为了推广活动顺利开展,客户肯定需要按地区划分的新跟踪链接,还要跟踪推广活动的广告支出。使用我们的推广活动 API,就能满足这些需求,方法如下:

  • 要想查看 AppLovin 和 AdColony 是否已有跟踪链接,客户需要使用 GET 请求,获取渠道跟踪链接

  • 在这个示例场景中,我们且假设不存在任何现有的跟踪链接。此时,客户就需要使用 CREATE 请求,创建渠道跟踪链接 (层级 1),供上述两个合作伙伴使用。

  • 接下来,客户可能要用到 GET 请求,获取合作伙伴列表,找到两个合作伙伴的 ID,将合作伙伴和其对应 ID 关联起来。

  • 有了合作伙伴 ID 之后,使用 UPDATE 请求,更新跟踪链接,客户就能将已创建的跟踪链接与合作伙伴关联起来,启用合作伙伴的成本参数。

这样,采用 AppLovin 和 AdColony 默认推广活动结构的完整跟踪链接就设置好了。跟踪链接上附加了 AdColony 的成本参数,以及渠道附加的任何其他默认参数。

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

版本控制

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

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

以下文档仅适用于 API V1 版本。

API 认证

要访问推广活动 API,请指定与您的用户相关联的 API 识别码 (可在 Adjust 控制面板的 "账户设置 > 用户详情 > API 识别码" 中找到)。本文档中,该用户识别码将被称为您的 "认证识别码"。

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

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

Authorization: Token token=user_token_here

响应格式

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

响应结构大致基于 Google 的 JSON API 规范指南: https://google.github.io/styleguide/jsoncstyleguide.xml

成功响应

请参阅下方请求成功时的推广活动 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
timestamp字符串:YYYY-MM-DDTHH:MM:MMZZ请求时服务器上的日期和时间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
timestamp字符串 "YYYY-MM-DDTHH:MM:MMZ"请求时服务器上的日期和时间2019-09-09T09:07:06Z
message字符串对应的错误信息,显示请求失败的原因"User not authenticated"

数据请求 (GET 请求) 将返回分页结果,其中包含下一页和前一页结果的 URL。推广活动 API 使用基于游标的分页,每个 GET 响应都包含 after 和 before 游标。此外,每个请求都会接受含游标值的 after 和 before 参数。要自定义分页的限制,请使用参数:limit (否则默认每页限 50 个元素)。

分页操作流程示例如下:

要为 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 // (此页为首页,因此无上一页)
      },
      "next": "https://api.adjust.com/public/v1/apps/yxs12pfewq/trackers?after=g2wAAAACYhW1_gxkAANuaWxq&limit=50",
      "previous": nil // (此页为首页,因此无前页)
    }

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

GET https://api.adjust.com/public/v1/apps/yxs12pfewq/tracker?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_ids整数显示附加在跟踪链接上的合作伙伴 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
app_name字符串跟踪码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_ids整数显示附加在跟踪链接上的合作伙伴 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": "def456",
  "label": "SpringCampaign",
  "level": 2,
  "archived": false,
  "has_subtrackers": false,
  "partner_id": 3,
  "cost_data_enabled": false,
  "url": "https://app.adjust.com/def456",
  "click_url": "https://app.adjust.com/def456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
  "impression_url": "https://s2s.adjust.com/impression/def456?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": "def456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/def456",
        "click_url": "https://app.adjust.com/def456?idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/def456?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_ids整数显示附加在跟踪链接上的合作伙伴 ID,例如,我们合作伙伴 Adroll 的 ID 是 33
cost_data_enabled布尔 (true/false)显示跟踪链接是否已启用 cost_datatrue
impression_url字符串展示跟踪链接的 URLhttps://view.adjust.com/impression/def456
url字符串跟踪链接 URLhttps://view.adjust.com/impression/def456

对象示例:
{
  "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": "def456",
        "label": "SpringCampaign",
        "level": 2,
        "archived": false,
        "has_subtrackers": false,
        "partner_id": 3,
        "cost_data_enabled": false,
        "url": "https://app.adjust.com/def456",
        "click_url": "https://app.adjust.com/def456?campaign={campaign_name}&idfa={idfa}&deeplink=http%3A%2F%2Fa.b%2Fc%3Fd%3D1%26e%3D%%MACROS%%",
        "impression_url": "https://s2s.adjust.com/impression/def456?campaign={campaign_name}&idfa={idfa}&s2s=1",
      }
    ]
  }
}

更新跟踪链接

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

终端:

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

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

请求正文

请求正文可以查询参数或 application/json 内容格式发送。API 只会更新指定的参数,没有任何参数是必需的。
参数格式描述示例
partner_ids整数将被附加在跟踪链接上的合作伙伴 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_ids整数显示附加在跟踪链接上的合作伙伴 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"
      }
    ]
  }
}

获取合作伙伴

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

终端: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
      }
    ]
  }
}

有关此主题