# @adjustcom/smart-banner-sdk 中文文档

规范地址：https://npmcn.com/package/%40adjustcom/smart-banner-sdk/

版本：1\.3\.3
npm 元数据更新时间：2026-10-23T12:54:10.809Z
中文译文更新时间：2026-11-05T22:13:17.556Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adjustcom/smart-banner-sdk
原文对照：https://npmcn.com/package/%40adjustcom/smart-banner-sdk/?lang=original
项目主页：https://github.com/adjust/smart_banner_sdk#readme
源码仓库：https://github.com/adjust/smart_banner_sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：184 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-05-16T23:27:37.299Z
- 最新版本发布：2026-10-23T12:54:10.394Z
- 近 30 天下载量：13616（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 5 个）

## 中文简介

调整智能屏蔽 SDK

## 安装

```sh
npm install @adjustcom/smart-banner-sdk
```

也可以使用：`pnpm add @adjustcom/smart-banner-sdk`、`yarn add @adjustcom/smart-banner-sdk`、`bun add @adjustcom/smart-banner-sdk`

## README

## 内容提要

这是用于网站或网络应用的"调整智能封面"SDK的指南. 您可以读取更多关于调整 TM 的 [调整.com](https://adjust.com/)。 。 。 .

## 目录

-   [安装](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-installation)
-   [初始化](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-initialization)
-   [隐藏并显示](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-visibility)
-   [本地化](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-localisation)
-   [深链接](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks)
-   [许可证](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-license)

## 安装

建议安装SDK的方法为npm:

```
npm install @adjustcom/smart-banner-sdk --save
```

然后导入到您的代码中:

```
import AdjustSmartBanner from '@adjustcom/smart-banner-sdk'
```

Sdk也通过CDN提供,然后通过环球访问 `AdjustSmartBanner`。 。 。 .

改为: 通过 CDN 装入智能封条 SDK 将以下片段粘入 `<head>` 标签 :

```html
<script type="application/javascript">
!function(n,t,e,o,a,s,r,i,c){var u=a+"_q";n[a]=n[a]||{},n[u]=n[u]||[];for(var d=0;d<s.length;d++)r(n[a],n[u],s[d]);i=t.createElement(e),c=t.getElementsByTagName(e)[0],i.async=!0,i.src="https://cdn.adjust.com/adjust-smart-banner-latest.min.js",i.onload=function(){n[a]=n[a].default;for(var t=0;t<n[u].length;t++)n[a][n[u][t][0]]?n[a][n[u][t][0]].apply(n[a],n[u][t][1]):console.error("No such function found in "+a+": "+n[u][t][0]);n[u]=[]},c.parentNode.insertBefore(i,c)}(window,document,"script",0,"AdjustSmartBanner",["init","show","hide","setLanguage","setIosDeepLinkPath","setAndroidDeepLinkPath","setContext"],(function(n,t,e){n[e]=function(){t.push([e,arguments])}}));
</script>
```

在通过CDN装入sdk时,我们建议使用精密版本. 您可以瞄准特定版本, 如 `https://cdn.adjust.com/adjust-smart-banner-1.2.4.min.js`,或者可以瞄准最新版本 `https://cdn.adjust.com/adjust-smart-banner-latest.min.js` 如果您需要自动更新而不需要更改目标文件。 sdk文件是被缓存的,因此可以尽可能快地提供,缓存每半小时刷新一次. 如果您需要更新, 请立即确定针对特定版本 .

## 初始化

为了初始化智能旗下SDK,你应该叫 `AdjustSmartBanner.init` 方法 :

```js
AdjustSmartBanner.init({
  appToken: "APP_TOKEN",
})
```

当你称这种方法为Smart Banner SDK检测设备平台时,如果它是移动平台,那么SDK加载可用的智能旗. 如果当前页面的横幅存在,则在初始化完成后立即显示.

以下是当前可用参数的完整列表 `init` 方法 :

### 强制性参数

#### **应用** `string | object`

根据您在您的空间里拥有的应用程序, 您会提供一个或多个应用标志 .

对于多平台的应用程序, 将它的应用程序代号传递给 Evolution SDK :

```js
AdjustSmartBanner.init({
  appToken: "APP_TOKEN",
})
```

对于单个平台的应用程序,每个平台都会通过应用标志:

```js
AdjustSmartBanner.init({
  appToken: {
    ios: "IOS_APP_TOKEN",
    android: "ANDROID_APP_TOKEN"
  }
})
```

### 可选段落

#### **日志级别** `string`

默认情况下,此参数设定为 `error`。可能的数值是: `none`, (中文(简体) ), `error`, (中文(简体) ), `warning`, (中文(简体) ), `info`, (中文(简体) ), `verbose`我们强烈建议您使用 `verbose` 测试时,以查看精确的日志,并确保整合工作进行得当. 以下是每个日志级别的更多细节:

-   `verbose` - 如果发生某些行动,将打印详细信息
-   `info` - 只打印基本信息信息、警告和错误
-   `warning` - 只打印警告和错误信息
-   `error` - 将只打印错误消息
-   `none` - 什么都不会印

#### **语言** `string`

您可以指示 sdk 显示旗帜时应该使用什么本地化 。 详情见 [本地化](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-localisation)。 。 。 .

示例

```js
AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  language: "fr"
})
```

#### **深链接路径参数**

这些参数允许您在点击横幅时指定您的用户在您的应用程序中降落的位置 。 详情见 [深链接](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks)。 。 。 .

##### **android DeepLinkPath 软件** `string`

覆盖Android深链接路径,这使得您在点击横幅时可以在移动应用程序中更改用户目的地.

示例

```js
AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  androidDeepLinkPath: "android/path/to/screen"
})
```

请找到 [更多实例](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-context-examples)进一步模板和上下文解释见 [深链接](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks) 章节.

##### **欧斯丁克派斯** `string`

覆盖了 iOS 深链接路径,这使得您在点击横幅时可以在移动应用程序中更改用户目的地.

示例

```js
AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  iosDeepLinkPath: "ios/path-to-screen"
})
```

请找到 [更多实例](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-context-examples)进一步模板和上下文解释见 [深链接](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks) 章节.

##### **上下文** `object`

设置深链接路径模板的上下文 。 上下文是一个SDK搜索值以插入深链接路径模板的对象. 详情见 [深链接](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks)。 。 。 .

实例:

```js
AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  iosDeepLinkPath: "products/product={item_id}",
  context: {
    item_id: "cool_jeans_123"
  }
})

AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  androidDeepLinkPath: "products/{item_id}",
  context: {
    item_id: "cool_jeans_123"
  }
})

AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  androidDeepLinkPath: "products/{item_id}",
  iosDeepLinkPath: "products/product={item_id}",
  context: {
    item_id: "cool_jeans_123"
  }
})
```

您可以为iOS和Android使用不同的路径并设置不同的上下文变量:

示例

```js
AdjustSmartBanner.init({
  // other initialisation parameters including mandatory ones
  androidDeepLinkPath: "promo/{android_promo}",
  iosDeepLinkPath: "main/{ios_promo}",
  context: {
    android_promo: "new_user",
    ios_promo: "registrationFinished",
    unused_variable: "this will be ignored"
  }
})
```

#### **旗下家长** `HTMLElement`

默认横幅附着在 `document.body`。要改变这一行为,您可以指定横幅的父程序 。 它应该是现有的 `HTMLElement`。 。 。 .

```js
const element = document.querySelector('#root-for-banner');

AdjustSmartBanner.init({
    // other initialisation parameters including mandatory ones
    bannerParent: element
})
```

#### **已创建** `function`

显示横幅后的函数 .

```js
AdjustSmartBanner.init({
    // other initialisation parameters including mandatory ones
    onCreated: () => console.log('Smart banner shown')
})
```

#### **解职** `function`

点击了标语的删除按钮时要调用的函数 .

```js
AdjustSmartBanner.init({
   // other initialisation parameters including mandatory ones
    onDismissed: () => console.log('Smart banner dismissed')
})
```

## 隐藏并显示

可以在初始化后隐藏智能旗并在需要时再次显示.

#### **隐藏**

隐藏了智能旗. 注意: 此函数不会从 DOM 中去除横幅 .

```js
AdjustSmartBanner.hide();
```

#### **显示**

展示出聪明的旗帜.

**重要**:如果您的网页应用程序是单一的页面应用程序(SPA),在导航发生后和当前页面URL更改后,您应该使用这种方法. 这迫使 SDK 读取页面更新的 URL, SDK 可以找到当前页面的合适横幅, 或者当它构建一个跟踪器链接时使用更新的 GET 参数 [动态深通](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks)。 。 。 .

```js
AdjustSmartBanner.show();
```

## 本地化

为了更好的用户体验,你可以将你的智能横幅本地化. Smart Banner SDK读取了浏览器中使用的语言,如果有这样的横幅本地化,横幅将会被以适当的语言显示. 但默认选择可能不是最好的选择, 很可能你更清楚用户喜欢哪种语言。 在此情况下, 您可以指示 sdk 使用何种语言 .

设置首选语言有两种方法

-   传为: [a 参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-language) 改为 `AdjustSmartBanner.init`
-   调用 `setLanguage` 设置如下:

```js
AdjustSmartBanner.setLanguage("fr");
```

设置器接受双字母语言代码,即:. `en`, (中文(简体) ), `de`等 (中文(简体) ).

## 深链接

Deeplink是一个链接,可以引导用户访问您移动应用程序中的某个事件或页面,提供无缝用户体验. 智能横幅 sdk 支持 [**纯字符串深链接路径**](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-plain-path) 财务报告和审定财务报表 [**深链接路径模板**](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-path-template)。 。 。 .

设置深链接路径或深链接路径模板有两种方法:

-   通过 [深链接路径参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-deeplink) 改为 `AdjustSmartBanner.init` 方法
-   调用 [`setAndroidDeepLinkPath`](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setters-androidDeeplinkpath) 财务报告和审定财务报表 [`setIosDeepLinkPath`](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setters-iosDeeplinkpath) 设置

### 纯字符串深链接路径

普通字符串深链接路径只是您移动应用程序中用作用户目的地的字符串.

示例

```js
// Plain string deeplink path

const deeplinkPath = "products/jeans/?product=cool_jeans_123"
```

### 深链接路径模板

深链接路径模板是一个字符串,其中包含卷曲括号中的占位符. Sdk 替换占位符为 [上下文值](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setting-context),即插入模板。 插值的结果是平面字符串,在您的移动应用程序中被用作用户目的地.

示例

```js
// Deeplink path template

const template = "products/{category}/?product={product_id}"

// Substrings {category} and {product_id} are the placeholders, which are replaced by values found in the context
```

**重要**: 深链接模板中的占位符由 sdk 使用 [提供上下文](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setting-context) 或者说 [获取参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplink-context-urlparams) 当前网页 URL.

#### 深链接路径模板的背景

上下文用于插入 [深链接路径模板](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/deeplinks-path-template)。 。 。 .

从方案角度提供背景情况有两种方法:

-   作为上下文 [深链接上下文参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-context) 改为 `AdjustSmartBanner.init`
-   调用 [`setContext` 设置](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setters-context)

设置上下文的另一种方法是使用 [获取参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplink-context-urlparams)。 。 。 .

在深链接路径模板内插之前, sdk 读取当前 URL 地址的 GET 参数,并将其与程序上传的上下文结合. 如果存在GET参数和同名上下文属性, sdk 倾向于并存储上下文中出现的值.

然后sdk通过深链接路径模板来查看并用组合上下文的属性来取而代之的是卷曲括号中的位置符. 如果组合上下文中没有这样的属性,则插入了空字符串而不是占位符 .

#### **使用 GET 参数作为上下文**

要插入深链接路径模板, sdk 读取当前 URL 地址的 GET 参数,并将其与程序设置上下文结合.

示例

```js
// Let's say the current URL is "https://my-shop.com/?product_id=111222&promo=spring_10"

AdjustSmartBanner.setIosDeepLinkPath("products/{product_id}/?promo={promo}");

// Then resulting deeplink path is "products/111222/?promo=spring_10"
```

你可以结合方法 设置上下文:

```js
// Let's say the current URL is "https://my-shop.com/?product_id=111222&promo=spring_10"

AdjustSmartBanner.setIosDeepLinkPath("products/{category}/{product_id}/?promo={promo}");

// But wait, there is no value for {category} in the GET parameters

AdjustSmartBanner.setContext({ category: "jeans" });

// Then resulting deeplink path is "products/jeans/111222/?promo=spring_10"
```

**重要**: 如果您的网页应用程序是单页应用程序( SPA) , 您应该呼叫 `AdjustSmartBanner.show()` 当 sdk 自己无法跟踪导航事件并检索更新的 URL 后页面地址更改时.

**重要**页:1 [上下文](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setting-context) 程序上传输到 sdk 是填入占位符的先行选择, 而带有相同密钥的 GET 参数会被忽略为上下文 .

示例

```js
// Let's say the current URL is "my-shop.com/?product_id=111222", so we have product_id parameter in the GET parameters

AdjustSmartBanner.setIosDeepLinkPath("products/{product_id}/");

// And then setContext function is called, which overrides a value of product_id
AdjustSmartBanner.setContext({ product_id: "999888" });

// Then resulting deeplink path is "products/999888/"
```

### **深链接路径和上下文设置器**

设置自定义深链接路径或深链接路径模板及其上下文有几种功能.

#### **设置和机器人 DepLinkPath**

接受代表深链接路径或深链接路径模板的字符串.

示例

```js
AdjustSmartBanner.setAndroidDeepLinkPath("products/jeans/?product=111222&promo=spring_10")
```

深链接路径模板可包含卷括号内的任何占位符.

示例

```js
AdjustSmartBanner.setAndroidDeepLinkPath("products/jeans/?product={product_id}&promo={promo_id}")
```

Sdk 将用来自 [上下文](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-context) 在初始化过程中提供或 [设置](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setters-context) 函数,或从 [URL 参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplink-context-urlparams)。 。 。 .

#### **设置( S) 深线**

接受代表深链接路径或深链接路径模板的字符串.

示例

```js
AdjustSmartBanner.setIosDeepLinkPath("products/jeans/?product=111222&promo=spring_10")
```

深链接路径模板可包含卷括号内的任何占位符.

示例

```js
AdjustSmartBanner.setIosDeepLinkPath("products/jeans/?product={product_id}&promo={promo_id}")
```

Sdk 将用来自 [上下文](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-init-context) 在初始化过程中提供或 [设置](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplinks-setters-context) 函数,或从 [URL 参数](https://npmcn.com/package/%40adjustcom/smart-banner-sdk/#readme-deeplink-context-urlparams)。 。 。 .

#### **设置**

一个有数据可以将占位符填入深链接模板的对象. sdk 在通过上下文的密钥中搜索一个占位符,并用给定值替换占位符.

示例

```js
AdjustSmartBanner.setAndroidDeepLinkPath("products/{category}/{product_id}/?promo={promo}");
AdjustSmartBanner.setContext({
  category: "jeans",
  product_id: "111222",
  promo: "spring_10"
});

// Resulting deeplink path is "products/jeans/111222/?promo=spring_10"
```

**重要**: 如果没有这样的密钥 `context` 找到 sdk 将尝试从当前 URL 地址的 GET 参数中获取值 。 如果无法找到要填入的值,则将占位符替换为空字符串.

示例

```js
AdjustSmartBanner.setIosDeepLinkPath("products/{category}/{product_id}/?promo={promo}");
AdjustSmartBanner.setContext({ category: "jeans" });

// Resulting deeplink path is "products/jeans//?promo="
```

**重要**: 注意到 `setContext` 覆盖上次保存的上下文,而不是顺序调用,您应该将所有需要的参数合并在一个对象中,然后调用 `setContext` 带着它.

示例

```js
// Wrong
AdjustSmartBanner.setIosDeepLinkPath("products/{category}/{product_id}");
AdjustSmartBanner.setContext({ category: "jeans" });
AdjustSmartBanner.setContext({ product_id: "111222" }); // Previous context is lost

// Resulting deeplink path is "products//111222", {category} is replaced with an empty string

// Correct
AdjustSmartBanner.setIosDeepLinkPath("products/{category}/{product_id}");
AdjustSmartBanner.setContext({
  category: "jeans",
  product_id: "111222"
});

// Resulting deeplink path is "products/jeans/111222"
```

## 许可证

调整型SDK根据麻省理工学院许可证获得许可.

版权(c) 2023年调整, [https://www.adjust.com (中文(简体) )](https://www.adjust.com/)

特此免费准许任何人获得《公约》副本 此软件和相关文档文件( “软件” ), 用于处理 软件不受限制,包括不受限制 使用、复制、修改、合并、出版、分发、分版许可和/或销售副本 软件,并允许向软件提供软件的人 因此,在下列条件下:

上述版权通知和这项许可通知应载入所有 软件的复制件或大部分.

软件是提供的"AS IS", 没有任何的恐惧, EXPRESS OR ,包括但不限制于雇佣军的保障, 特别目的和非目的的证明。 绝对不会 B. 任何索赔、索赔或其他索赔的索赔人或 责任,在契约、契约或其他行为中,产生于, 财产、财产、财产、财产、财产或财产 软件.

## 常见问题

### @adjustcom/smart-banner-sdk 是什么？

调整智能屏蔽 SDK

### 如何安装 @adjustcom/smart-banner-sdk？

在项目目录运行 npm install @adjustcom/smart-banner-sdk，或使用 pnpm add / yarn add / bun add。

### @adjustcom/smart-banner-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adjustcom/smart-banner-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adjustcom/smart-banner-sdk 可以商用吗？

@adjustcom/smart-banner-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adjustcom/smart-banner-sdk 的下载量有多少？

根据 npm 官方下载统计，@adjustcom/smart-banner-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 13,616 次，日均约 454 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adjustcom/smart-banner-sdk 还在维护吗？

最新版本 1\.3\.3 发布于 2026/10/23（15 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 5 个；首次发布于 2023/05/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。