adjust-icon

TrueLink API (Deep Link Generator API)

使用深度链接生成器 API，您可以单独或批量创建应用定制深度链接。这些深度链接可长可短，能改善各个平台的用户体验。

操作前须知

以下是您在操作前需要了解的内容。

可用性

  • 您需要使用 TrueLink Core 或 Enterprise 套餐才能使用深度链接生成器 API。
  • 使用深度链接生成器 API 创建的链接不会出现在 Campaign Lab中。
  • 使用深度链接生成器 API 创建的短链接的 TTL（生存时间）为 120 天。

要求

  1. 管理员、编辑员或自定义编辑员权限。

  2. 为您的 iOS 和安卓应用设置相同的品牌化域名。

  3. 您需要有效的自定义链接识别码才能生成深度链接：

  4. 更新 Adjust SDK 来解析短链接。

  5. 如果您已设置数据驻留，请确保 iOS 和安卓应用使用同一地区。

速率限制

为确保最佳性能和公平使用，深度链接生成器 API 会执行以下速率限制：

  1. 每应用短链接创建限制：

    • 单个应用的短链接创建请求：每秒最多 50 个。
    • 批量链接创建请求：每 2 秒最多 100 个。

  2. 所有链接创建和更新操作的单个账户限制：

    • 单个账户中所有应用：每秒最多 200 个请求。

如果超出上述任一限制，API 就会返回 429 Too Many Requests 状态。收到此响应后，您必须等待速率限制窗口重置，然后才能重试请求。

要避免达到速率上线，尤其是在高吞吐量的情况下，我们推荐您采用下列措施：

  • 采用自动重试逻辑，并采用指数退避策略，逐步增加重试之间的延迟间隔。
  • 全局并发控制以有效限制并发请求数量，例如：
    • asyncio.Semaphore (Python)
    • async-sema (Node.js)
    • 或在 Java 中来自 java.util.concurrent 的 Semaphore

正确处理速率非常重要，能保持服务访问权限不受干扰，避免操作受限。

认证

要访问深度链接生成 API，您需要通过 Authorization 标头 (Bearer token) 提供 Adjust API 识别码。

如果您的组织启用了单点登录 (SSO)，请联系您的 Adjust 代表，或发送电子邮件至 support@adjust.com，我们将帮您查找 API 识别码。

非单点登录账户的 API 识别码位于用户 个人档案 中。要找到该识别码，请按照下列步骤操作。

  1. 选择账户 (用户) 图标。
  2. 选择 账户设置 。
  3. 选择 个人档案 标签页。
  4. 您的 API 识别码 会显示在 用户详细信息 中。选择复制按钮来将识别码复制到您的系统剪贴板。

重置 Adjust API 识别码

您可以随时重置 Adjust API 识别码。重置后，旧的识别码将失效。请务必在所有使用识别码的位置进行替换。使用无效识别码发送的请求会被 Adjust 拒绝。

重置 Adjust API 识别码：

  1. 选择账户 (用户) 图标。
  2. 选择 账户设置 。
  3. 选择 个人档案 标签页。
  4. 您的 API 识别码 会显示在 用户详情 中。
  5. 选择 重置 API 识别码 。
  6. 在窗口中输入账户密码并选择 重置 来重置您的 API 识别码。屏幕右上角会显示确认信息。
  7. 选择 API 识别码 旁的复制按钮来将识别码复制到您的系统剪贴板。

额度和用量

深度链接生成器 API 可以生成无限数量的长链接 ，但 短链接 的数量上限取决于您的合同条款。

  • 只有 唯一短链接 才会占用您的额度。如果多次发送同一组参数，那么额度仅会被扣减 1 次 。
  • 您的合同中注明了您的短链接额度。
  • 当额度用尽或合同到期时，无论 shorten_url 参数值如何， API 都会自动转为长链接生成 。

请求当前配额信息

执行以下请求以检索当前配额余额。响应会实时反映您的余额。

终端： https://automate.adjust.com/engage/deep-links/quota

方法： GET

响应： 配额数据

响应标头

大多数 API 响应都包含标头，可实时显示短链接配额和合同状态：

响应标头
X-ShortLink-Quota-Limit: 100000 # Total short link quota allocated
X-ShortLink-Quota-Remaining: 86129 # Remaining short link generations
X-Contract-Status: active # Current contract status. One of: "active", "inactive". "inactive" is returned when the contract has ended or the contract information is not yet available
X-Contract-End-Date: 2025-12-31 # Contract expiration date
X-Contract-Start-Date: 2024-12-31 # Contract start date

生成单个深度链接

采取此操作，针对单平台、多平台或复合应用配置生成长/短深度链接。如果您需要动态创建单个深度链接，请使用此方法。

API 协议

终端： https://automate.adjust.com/engage/deep-links

方法： POST

请求正文： 链接生成负载

响应： 深度链接对象或错误响应

示例

单一平台应用

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c52mluz",
     "redirect": "https://example.com/redirect",
     "fallback": "https://example.com/fallback",
     "deep_link_path": "/custom-path"
   }'
响应
{
   "url": "https://example.go.link/czWsH",
   "long_url": "https://example.go.link/custom-path?adj_t=1c52mluz&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect"
}

多平台应用

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c1zm8r9",
     "redirect": "https://example.com/redirect",
     "fallback": "https://example.com/fallback",
     "android_deep_link_path": "/custom-path",
     "redirect_macos": "https://www.example.com/redirectmacos"
   }'
响应
{
   "url": "https://example.go.link/8oBfZ",
   "long_url": "https://example.go.link?adj_t=1c1zm8r9&adj_deep_link=adjustdeeplinks%3A%2F%2Fcustom-path&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect&adj_redirect_macos=https%3A%2F%2Fwww.example.com%2Fredirectmacos"
}

复合链接

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c2n7ybx_1cjet4nl",
     "redirect": "https://example.com/redirect",
     "fallback": "https://example.com/fallback",
     "ios_deep_link_path": "/custom-path-ios",
     "android_deep_link_path": "/custom-path-android",
     "redirect_macos": "https://www.example.com/redirectmacos"
   }'
响应
{
   "url": "https://example.go.link/j55JZ",
   "long_url": "https://example.go.link/custom-path-ios?adj_t=1c2n7ybx_1cjet4nl&adj_deep_link=example%3A%2F%2Fcustom-path-android&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect&adj_redirect_macos=https%3A%2F%2Fwww.example.com%2Fredirectmacos"
}

仅生成长链接 (不占用短链接配额)

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c52mluz",
     "redirect": "https://example.com/redirect",
     "fallback": "https://example.com/fallback",
     "deep_link_path": "/custom-path",
     "shorten_url": false
   }'
响应
{
   "url": "https://example.go.link/custom-path?adj_t=1c52mluz&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect",
   "long_url": "https://example.go.link/custom-path?adj_t=1c52mluz&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect"
}

使用自定义短识别码生成短链接 (链接后缀 / 自定义后缀)

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c52mluz",
     "deep_link_path": "/custom-path",
     "short_token": "custom-token",
     "redirect_macos": "https://www.example.com/redirectmacos"
   }'
响应
{
   "url": "https://example.go.link/custom-token",
   "long_url": "https://example.go.link/custom-path?adj_t=1c52mluz&adj_redirect_macos=https%3A%2F%2Fwww.example.com%2Fredirectmacos"
}

批量生成深度链接

采取此操作，通过单个请求中生成多个深度链接。支持多种应用类型的长/短链接生成。使用批量生成功能，您可以一次性创建最多 100 个链接，以优化性能，和减少请求用量。

API 协议

终端： https://automate.adjust.com/engage/deep-links/bulk

方法： POST

请求正文：

参数数据类型
data*数组[链接生成负载]

响应： | 参数 | 数据类型 | | ---------- | ----------------------------------------------------------------------------- | | data* | 数组[深度链接或错误响应] |

示例

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
"data": [
    {
    "link_token": "1doptv0c",
    "redirect": "https://example.com/redirect",
    "fallback": "https://example.com/fallback",
    "campaign": "custom-campaign"
    },
    {
    "link_token": "ERRORDATA"
    },
    {
      "link_token": "1df3xslh_1dsykkaa",
      "redirect": "https://example.com/redirect",
      "fallback": "https://example.com/fallback",
      "ios_deep_link_path": "/custom-path-ios",
      "android_deep_link_path": "/custom-path-android"
    },
    {
      "link_token": "1dzwtdjt",
      "redirect": "https://example.com/redirect",
      "fallback": "https://example.com/fallback",
      "android_deep_link_path": "/custom-path"
    }
  ]
}'
响应
{
   "data": [
      {
         "url": "https://example.go.link/4IlkC",
         "long_url": "[CORRESPONDING LONG URL]"
      },
      {
         "error_code": "service_error",
         "error_desc": "[ERROR MESSAGE]"
      },
      {
         "url": "https://example.go.link/6KnoE",
         "long_url": "[CORRESPONDING LONG URL]"
      },
      {
         "url": "https://example.go.link/5JmnD",
         "long_url": "[CORRESPONDING LONG URL]"
      }
   ]
}

采用该操作，调取之前所生成短链接的元数据，例如失效日期、重定向参数等。可用于检查或验证短链接状态。

终端： https://automate.adjust.com/engage/deep-links/short-link?short_token={short_token}&app_token={app_token}

方法： GET

响应： 短识别码元数据

请求 - cURL
curl --location --request GET 'https://automate.adjust.com/engage/deep-links/short-link?short_token=4IlkC&app_token=zgvhg75bw83k' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken'
响应
{
   "created_at": "2025-03-19T13:31:31Z",
   "expires_at": "2025-10-08T17:04:24.201134367Z",
   "token": "4IlkC",
   "ulink": "example",
   "url": "https://example.go.link/?adj_t=1g41cvql_1gb5zq24&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback-1&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect"
}

采用此操作，更新现有短链接的重定向目标 (长链接)。短链接本身 保持不变 。

终端： https://automate.adjust.com/engage/deep-links/{short_token}

方法： PUT

请求正文： 链接生成负载

响应： 成功时 HTTP 204 No Content

请求 - cURL
curl --location --request PUT 'https://automate.adjust.com/engage/deep-links/4IlkC' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
  "link_token": "1doptv0c",
  "redirect": "https://example.com/new-redirect",
  "fallback": "https://example.com/new-fallback",
  "deep_link_path": "/new-custom-path"
}'
响应
204 No Content

数据模型

参数数据类型描述
link_token*String自定义链接的链接识别码。可以是单个识别码，也可以是多个识别码的组合形式：linkTokenA_linkTokenB。
shorten_urlBoolean指示是否应缩短链接。默认为 true。
short_tokenString自定义短识别码 (链接后缀 / 自定义后缀)。使用此参数生成带有预定义值的短链接。例如，如果您要发送 campaign2026，那么生成的链接将为 example.go.link/campaign2026。在同一个品牌化域名中的识别码必须是唯一的。
campaignString推广活动的自定义名称。使用此参数，覆盖来自自定义链接的值。
adgroupString广告组的自定义名称。使用此参数，覆盖来自自定义链接的值。
creativeString素材的自定义名称。使用此参数，覆盖来自自定义链接的值。
deep_link_pathString指定用户被转至的应用内位置。适用于单一平台应用。
ios_deep_link_pathString指定用户被转至的 iOS 应用内位置。适用于多平台 iOS 应用或复合链接。
android_deep_link_pathString指定用户被转至的安卓应用内位置。适用于多平台安卓应用或复合链接。
web_deep_link_urlString指定用户跳转的目标网页 URL 位置，不要求应用深度链接路径。
web_onlyBoolean设为 true 时，生成的链接会在 URL 路径中添加 /w 前缀 (例如https://example.go.link/custom-path 会变成 https://example.go.link/w/custom-path)，从而转化为网页端限定格式。即便应用已经安装，网页端限定链接也绝不会打开应用，而是会将用户重定向到网页或应用商店 (按照 redirect 参数定义)。需要配置品牌化域名。默认为 false。
fallbackString非默认平台用户的登陆页。指定 fallback URL 时，我们建议您同时指定 redirect_macos 和 redirect_windows。
redirectString重定向 URL，用于覆盖 Adjust 的默认重定向。
redirect_iosString重定向 (Redirect) URL，仅覆盖 Adjust 针对 iOS 应用的默认重定向 (Redirect)。适用于多平台 iOS 应用或复合链接。
redirect_androidString重定向 (Redirect) URL，仅覆盖 Adjust 针对 Android 应用的默认重定向 (Redirect)。适用于多平台 Android 应用或复合链接。
redirect_macosString重定向 URL，用于覆盖 Adjust 针对 macOS 的默认重定向。在指定 fallback 时，我们建议为 macOS 用户指定该参数。
redirect_windowsString重定向 URL，用于覆盖 Adjust 针对 Windows 的默认重定向。在指定 fallback 时，我们建议为 Windows 用户指定该参数。
labelString向链接附加自定义数据。使用该参数，添加唯一的用户推荐 ID。用户分享来自应用的短链接时，该 ID 会自动填充。
custom_dynamic_callback_parametersObject附加至已生成 URL 查询字符串的键值回传参数，不包含 adj_ 前缀。键和值均自动进行 URL 编码。
og_titleString链接在社交媒体上分享的预览标题。如果设置了任何 OG 字段，则为必填项。
og_descriptionString链接社交平台分享预览的描述。即使已设置了其他 OG 字段，该字段也是可选的。
og_imageStringJPG 或 PNG 图片的 URL，大小至少为 200 x 200 像素，用于链接的社交分享预览。如果设置了任何 OG 字段，则为必填项。
参数数据类型描述
url*String最终链接：短链接或长链接
long_url*String对应的长链接

短识别码元数据

参数数据类型描述
created_at*StringISO 日期时间对象
expires_at*String短链接有效期的 ISO 日期时间对象
updated_atString链接最近更新的 ISO 日期时间对象
token*String识别码
ulink*String品牌化域名
url*String完整的长链接

配额数据

参数数据类型描述
limit*Integer分配的短链接总配额
remaining*Integer剩余短链接生成次数
contract_status*String当前合同状态。下列状态之一：“active”、“inactive”。当合同已结束或合同信息尚不可用时，返回“inactive”。
contract_start_dateStringISO 日期对象。合同开始日期。
contract_end_dateStringISO 日期对象。合同到期日期。

自定义动态回传参数

动态回传参数 (DCP) 允许您在点击或展示时发送自定义推广参数。 用它们为您的内部系统收集用户特定数据和接收 Adjust 推广参数之外的渠道合作伙伴宏。 这些自定义参数是完整点击 URL 的一部分，因此可以在您的应用中调取，用于特定内容、自定义体验构建等深度链接跳转。

示例

请求 - cURL
curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "1c52mluz",
     "redirect": "https://example.com/redirect",
     "fallback": "https://example.com/fallback",
     "deep_link_path": "/custom-path",
     "custom_dynamic_callback_parameters": {
       "coupon_code": "SUMMER_2026",
       "affiliate_id": "partner 42",
       "source_page": "home/banner"
     }
   }'
响应
{
   "url": "https://example.go.link/7XpQr",
   "long_url": "https://example.go.link/custom-path?adj_t=1c52mluz&adj_fallback=https%3A%2F%2Fexample.com%2Ffallback&adj_redirect=https%3A%2F%2Fexample.com%2Fredirect&coupon_code=SUMMER_2026&affiliate_id=partner%2042&source_page=home%2Fbanner"
}

错误响应

参数数据类型描述
error_code*String错误代码：request_error，auth_error，validation_error， service_error
error_desc*String人类可读的错误描述
error_desc_detailsArray其他元数据