> 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) **\[互动]** → **内容** → [**小组件**](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**时，impact.com 会在加载您的页面之前，将其替换为每个合作伙伴的真实值。您的页面会从查询字符串中读取这些值，并用它们生成可跟踪的链接。

例如，如果您将 **小组件 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 注入到小组件 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 + '">复制链接</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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.