深度链接生成器 API

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

操作前须知

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

可用性

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

要求

管理员、编辑员或自定义编辑员权限。
为您的 iOS 和安卓应用设置相同的品牌化域名。
- 对于 iOS 应用，请确保将您的品牌化域名添加为Associated Domain (关联域名)。此操作会将域名设置为通用链接。
- 对于安卓应用，请确保将品牌化域名定义为Android App Link (安卓应用链接)。
您需要有效的自定义链接识别码才能生成深度链接：
- 针对单一应用 (包括单平台和多平台应用) ：在 Campaign Lab 中创建自定义链接，获得单个链接识别码。
- 针对多款应用，您有两种选择
  1. 在 Campaign Lab 中创建复合自定义链接，为多个应用生成同一个链接识别码。请参阅平台特定链接识别码了解详情。
  2. 使用两个现有自定义链接，并使用下划线 (_) 连接识别码，示例：linkTokenA_linkTokenB。
更新 Adjust SDK 来解析短链接。
- iOS |安卓| Unity | React Native | Flutter | Cordova | Cocos2d-x
如果您已设置数据驻留，请确保 iOS 和安卓应用使用同一地区。

速率限制

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

每应用短链接创建限制：
- 单个应用的短链接创建请求：每秒最多 50 个。
- 批量链接创建请求：每 2 秒最多 100 个。
所有链接创建和更新操作的单个账户限制：
- 单个账户中所有应用：每秒最多 200 个请求。

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

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

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

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

认证

深度链接生成器 API 使用 Bearer 识别码进行认证。您必须在向深度链接生成器 API 发出的每个请求的 Authorization 标头中包含您的 Adjust API 识别码。

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

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

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

重置 Adjust API 识别码

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

重置 Adjust API 识别码：

选择账户 (用户) 图标。
选择 账户设置 。
选择 个人档案 标签页。
您的 API 识别码 会显示在 用户详情 中。
选择 重置 API 识别码 。
在窗口中输入账户密码并选择重置来重置您的 API 识别码。屏幕右上角会显示确认信息。
选择 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 --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/fryYl"}

多平台应用

curl --location 'https://automate.adjust.com/engage/deep-links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer adjustApiToken' \
--data '{
     "link_token": "2d41nkvy",
     "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/jlbKj" }

复合链接

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/6JtQx"}

批量生成深度链接

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

API 协议

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

方法： POST

请求正文：

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

响应：

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

示例

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"
      },
      {
         "error_code": "service_error",
         "error_desc": "[ERROR MESSAGE]"
      },
      {
         "url": "https://example.go.link/6KnoE"
      },
      {
         "url": "https://example.go.link/5JmnD"
      }
   ]
}

调取短链接数据

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

API 协议

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

方法： GET

响应： 短识别码元数据

示例

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"
}

更新短链接目标

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

API 协议

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

方法： PUT

请求正文： 链接生成负载

响应： 成功时 HTTP 204 No Content

示例

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_url`	`Boolean`	指示是否应缩短链接。默认为 `true`。
`short_token`	`String`	自定义短识别码。使用此参数生成带有预定义值的短链接。例如，如果您要发送 `campaign2026`，那么生成的链接将为 `example.go.link/campaign2026`。在同一个品牌化域名中的识别码必须是唯一的。
`campaign`	`String`	推广活动的自定义名称。使用此参数，覆盖来自自定义链接的值。
`adgroup`	`String`	广告组的自定义名称。使用此参数，覆盖来自自定义链接的值。
`creative`	`String`	素材的自定义名称。使用此参数，覆盖来自自定义链接的值。
`deep_link_path`	`String`	指定用户被转至的应用内位置。适用于单一平台应用。
`ios_deep_link_path`	`String`	指定用户被转至的 iOS 应用内位置。适用于多平台 iOS 应用或复合链接。
`android_deep_link_path`	`String`	指定用户被转至的安卓应用内位置。适用于多平台安卓应用或复合链接。
`fallback`	`String`	非默认平台用户的登陆页。指定 `fallback` URL 时，我们建议您同时指定 `redirect_macos` 和 `redirect_windows`。
`redirect`	`String`	重定向 URL，用于覆盖 Adjust 的默认重定向。
`redirect_ios`	`String`	重定向 (Redirect) URL，仅覆盖 Adjust 针对 iOS 应用的默认重定向 (Redirect)。适用于多平台 iOS 应用或复合链接。
`redirect_android`	`String`	重定向 (Redirect) URL，仅覆盖 Adjust 针对 Android 应用的默认重定向 (Redirect)。适用于多平台 Android 应用或复合链接。
`redirect_macos`	`String`	重定向 URL，用于覆盖 Adjust 针对 macOS 的默认重定向。在指定 `fallback` 时，我们建议为 macOS 用户指定该参数。
`redirect_windows`	`String`	重定向 URL，用于覆盖 Adjust 针对 Windows 的默认重定向。在指定 `fallback` 时，我们建议为 Windows 用户指定该参数。
`label`	`String`	向链接附加自定义数据。使用该参数，添加唯一的用户推荐 ID。用户分享来自应用的短链接时，该 ID 会自动填充。
`og_title`	`String`	链接在社交媒体上分享的预览标题。
`og_description`	`String`	链接社交平台分享预览的描述。
`og_image`	`String`	JPG 或 PNG 图片的 URL，大小至少为 200 x 200 像素，用于链接的社交分享预览。

深度链接

参数	数据类型	描述
`url`*	`String`	最终链接：短链接或长链接
`long_url`*	`String`	对应的长链接

短识别码元数据

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

配额数据

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

错误响应

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