> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-a-custom-widget.md).

# 创建自定义组件

开发动态工具，帮助合作伙伴推广您的品牌。自定义小组件可让您通过 iframe 将外部托管的工具或页面直接嵌入 impact.com 界面。使用本指南创建并配置一个自定义内容小组件，为您的合作伙伴提供个性化资源和一致的品牌体验。

{% stepper %}
{% step %}

## 访问自定义小组件创建器

1. 从左侧导航菜单中，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage]** → **内容** → [**小组件**](https://app.impact.com/secure/advertiser/engage/ads/list-widget-tool-flow.ihtml)**.**
2. 在右上角，选择 **创建小组件** → **自定义**.
   {% endstep %}

{% step %}

## 输入小组件详情

1. 输入一个 **名称** 自定义小组件的。
2. 可选地，输入一个 **说明** 用于自定义小组件。
3. 可选地，输入一个 **标签** 用于自定义小组件。
4. 如有需要， ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FiZjM1xY8o3v1iR3Zaysd%2FToggle.svg?alt=media\&token=b1550d48-bba9-4e81-8604-bc12370c5caa) **\[切换开启] 限制合作伙伴访问** 以指定应有权访问该小组件的单个合作伙伴和群组。
   * **合作伙伴：** 输入可访问自定义小组件的合作伙伴名称。
   * **群组：** 输入可访问自定义小组件的群组名称。
     {% endstep %}

{% step %}

## 配置小组件

1. 从显示选项中选择小组件的行为：
   * **在新标签页中打开：** 在单独的标签页中打开托管的 URL。
   * **嵌入到 impact.com 中：** 直接在平台界面中显示该小组件。
2. 可选地，从 **预览图片** 部分下，选择 **选择文件** 上传缩略图。请确保文件为 GIF、JPG 或 PNG，且不超过 512 KB。
3. 在……中 **小组件 URL** 字段中，输入托管小组件的网页地址。
4. 在 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[下拉菜单]**，选择与您网站安全性相匹配的协议（例如 https\://）。
5. （可选）选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-6282f271b7521383385339243690b303086736d9%2F3b5a585dd2895bdf1c30d1236c72ba590dddd18717863b27074c8d313d05ae20.svg?alt=media) **\[添加] 插入动态字段** 以展开令牌列表。
6. 找到要使用的令牌并选择 **插入**。平台将自动把令牌（例如 {irpid}）追加到您的 **小组件 URL**。请参阅 [动态字段令牌](#dynamic-field-tokens) 下方部分，查看每个令牌的说明。
   {% endstep %}

{% step %}

## 更新高级设置

在 **语言** ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[下拉菜单]**，选择此小组件显示所用的语言。
{% endstep %}

{% step %}

## 完成自定义小组件

选择 **创建** 以保存您的小组件。合作伙伴可以在 *内容小组件*.
{% endstep %}
{% endstepper %}

<details>

<summary>动态字段令牌</summary>

| 标记                             | 说明                   |
| ------------------------------ | -------------------- |
| `{click_url_encoded}`          | 已编码的点击 URL           |
| `{click_url}`                  | 未编码的点击 URL           |
| `{irimpurl}`                   | 我们的展示 URL            |
| `{irpid}`                      | 合作伙伴 ID              |
| `{subid1}`                     | 合作伙伴子 ID 1           |
| `{subid2}`                     | 合作伙伴子 ID 2           |
| `{subid3}`                     | 合作伙伴子 ID 3           |
| `{sharedId}`                   | 共享 ID                |
| `{iradid}`                     | 广告 ID                |
| `{ircid}`                      | 项目 ID                |
| `{click_url_encoded_deeplink}` | 已编码的点击 URL，附加深度链接参数。 |

</details>

## 示例

{% hint style="info" %}
**关于这些示例：** 自定义小组件由您构建并托管——impact.com 只会嵌入已托管的页面，并向其中注入实时合作伙伴数据。复制下方的参考实现，将它们托管在您自己的域名上并进行调整。合作伙伴无需编辑任何代码；他们只需从 *内容小组件*.
{% endhint %}

### 动态字段令牌如何到达您的小组件

当您向 **小组件 URL**添加动态字段令牌时，

例如，如果您设置 **小组件 URL** 进行 `https://widgets.yourbrand.com/search?partner={irpid}&clickurl={click_url_encoded}`，impact.com 会为 ID 为 `123456`:

{% code overflow="wrap" %}

```
https://widgets.yourbrand.com/search?partner=123456&clickurl=https%3A%2F%2Facme.sjv.io%2Fc%2F123456%2F789012%2F3456
```

{% endcode %}

{% hint style="warning" %}
将点击 URL 传递为 `{click_url_encoded}`，而不是 `{click_url}` —— 原始点击 URL 包含其自己的 `?` 和 `&` 字符，这会破坏您的查询字符串。使用前请先在页面中对其解码。
{% endhint %}

### 示例 1：搜索小组件

让合作伙伴在不离开 impact.com 的情况下搜索您的目录，并为任意产品复制一个可跟踪链接。您托管搜索页面；impact.com 传入合作伙伴的 ID 和点击 URL，因此每个结果链接都会归因于该合作伙伴。

1. 将搜索页面托管在您控制的域名上，并使用 HTTPS（例如， `https://widgets.yourbrand.com/search`）。将演示 `CATALOG` 数组替换为对您自己的产品目录或搜索 API 的调用。
2. 使用上面的五个步骤创建自定义小组件。在 **配置小组件**中，将 **小组件 URL** 设置为您的页面，并使用 `{irpid}` 和 `{click_url_encoded}` 令牌（如下所示）。
3. 使用 **在新标签页中打开**进行测试，作为测试合作伙伴执行一次搜索，并确认结果链接会跳转到您的网站并记录一次点击。然后将小组件切换为 **嵌入到 impact.com 中**.

**小组件 URL**

{% code overflow="wrap" %}

```
https://widgets.yourbrand.com/search?partner={irpid}&clickurl={click_url_encoded}
```

{% endcode %}

<details>

<summary>search-widget.html</summary>

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>产品搜索</title>
  <style>
    body { font-family: Arial, sans-serif; margin: 0; padding: 16px; }
    .search-bar { display: flex; gap: 8px; margin-bottom: 16px; }
    .search-bar input { flex: 1; padding: 10px; font-size: 16px; }
    .search-bar button { padding: 10px 16px; font-size: 16px; cursor: pointer; }
    .result { padding: 12px; border: 1px solid #ddd; border-radius: 6px; margin-bottom: 8px; }
    .result a { text-decoration: none; font-weight: bold; }
    .copy { margin-left: 8px; font-size: 13px; color: #2b6cb0; cursor: pointer; }
  </style>
</head>
<body>
  <div class="search-bar">
    <input id="q" type="text" placeholder="搜索产品..." />
    <button id="go">搜索</button>
  </div>
  <div id="results"></div>

  <script>
    // 1. 读取 impact.com 注入到 Widget URL 中的值。
    var params    = new URLSearchParams(window.location.search);
    var partnerId = params.get('partner') || '';
    var clickUrl  = decodeURIComponent(params.get('clickurl') || '');

    // 2. 将此演示数组替换为调用您自己的产品目录 / 搜索 API。
    var CATALOG = [
      { name: 'Trail Runner Shoe',   url: 'https://www.yourbrand.com/products/trail-runner' },
      { name: 'Waterproof Jacket',   url: 'https://www.yourbrand.com/products/waterproof-jacket' },
      { name: 'Merino Hiking Socks', url: 'https://www.yourbrand.com/products/merino-socks' }
    ];

    // 3. 构建可跟踪的深度链接：合作伙伴的点击 URL + 目标页面。
    //    在发布前，请确认您程序的确切深度链接格式（参见“发布前须知”）。
    function buildTrackingLink(destinationUrl) {
      if (!clickUrl) return destinationUrl;            // 如果令牌缺失，则回退：不进行跟踪
      return clickUrl + encodeURIComponent(destinationUrl);
    }

    function search() {
      var term = document.getElementById('q').value.toLowerCase();
      var matches = CATALOG.filter(function (p) {
        return p.name.toLowerCase().indexOf(term) !== -1;
      });
      var container = document.getElementById('results');
      container.innerHTML = matches.length ? '' : '<p>未找到产品。</p>';
      matches.forEach(function (p) {
        var link = buildTrackingLink(p.url);
        var row = document.createElement('div');
        row.className = 'result';
        row.innerHTML =
          '<a href="' + link + '" target="_blank" rel="noopener">' + p.name + '</a>' +
          '<span class="copy" data-link="' + link + '">Copy link</span>';
        container.appendChild(row);
      });
    }

    document.getElementById('go').addEventListener('click', search);
    document.getElementById('q').addEventListener('keyup', function (e) {
      if (e.key === 'Enter') search();
    });
    document.addEventListener('click', function (e) {
      if (e.target.classList.contains('copy')) {
        navigator.clipboard.writeText(e.target.getAttribute('data-link'));
      }
    });
  </script>
</body>
</html>
```

</details>

### 示例 2：动态富媒体广告（浮动聊天小组件）

动态富媒体广告是您托管并作为小组件嵌入的任何交互式 HTML 资源。在此示例中，您将构建一个浮动聊天气泡，它会展开为促销消息和行动号召。访客选择按钮时，会通过合作伙伴的点击 URL 进行重定向，因此该点击会被跟踪并归因。

1. 将页面托管在您控制的域名上，并使用 HTTPS（例如， `https://widgets.yourbrand.com/chat`）。自定义文案、颜色和行动号召，以匹配您的活动。
2. 使用上面的五个步骤创建自定义小组件，将 **小组件 URL** 与 `{click_url_encoded}` 令牌一起设置（如下所示）。
3. 使用 **在新标签页中打开** 作为测试合作伙伴进行测试，确认行动号召会打开您的网站并记录一次点击，然后将小组件切换为 **嵌入到 impact.com 中**.

**小组件 URL**

{% code overflow="wrap" %}

```
https://widgets.yourbrand.com/chat?clickurl={click_url_encoded}
```

{% endcode %}

如果要将访客发送到特定页面，而不是默认落地页，请使用 `{click_url_encoded_deeplink}` 令牌来替代 `{click_url_encoded}`，或如示例 1 所示，在您自己的代码中附加目标地址。

<details>

<summary>chat-widget.html</summary>

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>助手</title>
  <style>
    html, body { margin: 0; height: 100%; background: transparent; font-family: Arial, sans-serif; }
    #bubble {
      position: fixed; bottom: 20px; right: 20px;
      width: 60px; height: 60px; border-radius: 50%;
      background: #2b6cb0; color: #fff; font-size: 26px;
      display: flex; align-items: center; justify-content: center;
      cursor: pointer; box-shadow: 0 4px 12px rgba(0,0,0,.25);
    }
    #panel {
      position: fixed; bottom: 90px; right: 20px; width: 260px;
      background: #fff; border-radius: 10px; box-shadow: 0 6px 24px rgba(0,0,0,.2);
      padding: 16px; display: none;
    }
    #panel.open { display: block; }
    #panel p { margin: 0 0 12px; font-size: 14px; color: #333; }
    #cta {
      display: block; width: 100%; padding: 10px; border: none; border-radius: 6px;
      background: #2b6cb0; color: #fff; font-size: 15px; cursor: pointer;
    }
  </style>
</head>
<body>
  <div id="bubble">&#128172;</div>
  <div id="panel">
    <p>嗨！在寻找我们的最新优惠吗？点击下方即可购买并节省。</p>
    <button id="cta">立即购买</button>
  </div>

  <script>
    // impact.com 会将合作伙伴的点击 URL 注入此页面。
    var params   = new URLSearchParams(window.location.search);
    var clickUrl = decodeURIComponent(params.get('clickurl') || '');

    var bubble = document.getElementById('bubble');
    var panel  = document.getElementById('panel');
    bubble.addEventListener('click', function () {
      panel.classList.toggle('open');
    });

    document.getElementById('cta').addEventListener('click', function () {
      if (!clickUrl) return;
      // 在新标签页中打开，这样点击就会被跟踪并归因于该合作伙伴。
      window.open(clickUrl, '_blank', 'noopener');
    });
  </script>
</body>
</html>
```

</details>

## 发布前须知

* 请自行托管，并使用 HTTPS。impact.com 通过 iframe 嵌入您的页面或在新标签页中打开它——它不会托管您的代码。在嵌入模式下，您的页面运行在 iframe 中，因此打开目标链接时请使用 `target="_blank"` 或 `window.open(...)` ，而不要导航父窗口。
* 请对点击 URL 进行编码。将其作为 `{click_url_encoded}` 传递，并在页面中对其解码，这样其自身的 `?` 和 `&` 字符就不会破坏您的查询字符串。
* 请与您的 impact.com 集成工程师确认深度链接格式，并确保目标地址已包含在允许用于深度链接的域名范围内。

## 其他资源

* [与合作伙伴创建并共享跟踪链接](/brand/zh/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-and-share-tracking-links-with-partners.md) — 如何创建跟踪链接并与您的合作伙伴共享。
* [跟踪链接参数说明](/brand/zh/what-would-you-like-to-learn-about/platform-features/tracking/tracking-explained/tracking-link-parameters-explained.md) — 跟踪链接的结构以及您可以添加的参数，例如子 ID、共享 ID 和深度链接。
* [设置深度链接允许的域名](/brand/zh/what-would-you-like-to-learn-about/account-administration/program-settings/tracking-settings/set-up-permitted-domains-for-deep-linking.md) — 授权合作伙伴可在您网站上深度链接到的目标域名。
* [资产类型简介](/brand/zh/what-would-you-like-to-learn-about/platform-features/ads/create-ads/introduction-to-asset-types.md) — 您可以向合作伙伴提供的资源类型，包括自定义小组件在其中的位置。
* [Rakuten Advertising 到 impact.com：关键迁移步骤](/brand/zh/what-would-you-like-to-learn-about/getting-started/rakuten-advertising-to-impact.com-key-transition-steps.md) — 将程序从 Rakuten Advertising 迁移到 impact.com 时会发生哪些变化。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-a-custom-widget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.