> 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/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-a-custom-widget.md).

# Create a Custom Widget

Develop dynamic tools that empower partners to promote your brand. Custom widgets allow you to embed externally-hosted tools or pages directly into the impact.com interface via an iframe. Use this guide to create and configure a custom content widget that provides personalized resources and a consistent brand experience for your partners.

{% stepper %}
{% step %}

## Access the custom widget creator

1. From the left navigation menu, select ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage]** → **Content** → [**Widgets**](https://app.impact.com/secure/advertiser/engage/ads/list-widget-tool-flow.ihtml)**.**
2. In the top-right corner, select **Create Widget** → **Custom**.
   {% endstep %}

{% step %}

## Enter widget details

1. Enter a **Name** of the custom widget.
2. Optionally, enter a **Description** for the custom widget.
3. Optionally, enter a **Label** for the custom widget.
4. If required, ![](https://4048883401-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) **\[Toggle on] Restrict Partner Access** to specify individual partners and groups that should have access to the widget.
   * **Partners:** Enter the name of the partners that can access the custom widget.
   * **Groups:** Enter the name of the groups that can access the custom widget.
     {% endstep %}

{% step %}

## Configure the widget

1. Select how the widget behaves from the display options:
   * **Open in new tab:** Opens the hosted URL in a separate tab.
   * **Embed in impact.com:** Displays the widget directly within the platform interface.
2. Optionally, from the **Preview Image** section, select **Choose File** to upload a thumbnail. Ensure the file is a GIF, JPG, or PNG and does not exceed 512 KB.
3. In the **Widget URL** field, enter the web address where your widget is hosted.
4. From the ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[Drop-down menu]**, select the protocol (e.g., https\://) that matches your site's security.
5. Optionally, select ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-6282f271b7521383385339243690b303086736d9%2F3b5a585dd2895bdf1c30d1236c72ba590dddd18717863b27074c8d313d05ae20.svg?alt=media) **\[Add] Insert dynamic fields** to expand the token list.
6. Locate the token you want to use and select **Insert**. The platform will automatically append the token (e.g., {irpid}) to your **Widget URL**. Refer to the [Dynamic field tokens](#dynamic-field-tokens) section below for a description of each token.
   {% endstep %}

{% step %}

## Update advanced settings

From the **Language** ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[Drop-down menu]**, select the language in which this widget will display.
{% endstep %}

{% step %}

## Finalize the custom widget

Select **Create** to save your widget. Partners can find this widget in *Content Widgets*.
{% endstep %}
{% endstepper %}

<details>

<summary>Dynamic field tokens</summary>

| Token                          | Description                                          |
| ------------------------------ | ---------------------------------------------------- |
| `{click_url_encoded}`          | Click URL encoded                                    |
| `{click_url}`                  | Click URL not encoded                                |
| `{irimpurl}`                   | Our impression URL                                   |
| `{irpid}`                      | Partner ID                                           |
| `{subid1}`                     | Partner sub ID 1                                     |
| `{subid2}`                     | Partner sub ID 2                                     |
| `{subid3}`                     | Partner sub ID 3                                     |
| `{sharedId}`                   | Shared ID                                            |
| `{iradid}`                     | Ad ID                                                |
| `{ircid}`                      | Program ID                                           |
| `{click_url_encoded_deeplink}` | Encoded click URL with appended deep link parameter. |

</details>

## Worked examples

{% hint style="info" %}
**About these examples:** Custom widgets are built and hosted by you — impact.com only embeds the hosted page and injects live partner data into it. Copy the reference implementations below, host them on your own domain, and adapt them. Partners never edit any code; they just open the finished widget from *Content Widgets*.
{% endhint %}

### How dynamic field tokens reach your widget

When you add a dynamic field token to the **Widget URL**, impact.com replaces it with each partner's real values before loading your page. Your page reads those values from its query string and uses them to build trackable links.

For example, if you set the **Widget URL** to `https://widgets.yourbrand.com/search?partner={irpid}&clickurl={click_url_encoded}`, impact.com loads the following for a partner whose ID is `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" %}
Pass the click URL as `{click_url_encoded}`, not `{click_url}` — a raw click URL contains its own `?` and `&` characters, which break your query string. Decode it in your page before use.
{% endhint %}

### Example 1: Search widget

Lets a partner search your catalog and copy a trackable link for any product without leaving impact.com. You host the search page; impact.com passes in the partner's ID and click URL so every result link is attributed to that partner.

1. Host the search page on a domain you control, over HTTPS (e.g., `https://widgets.yourbrand.com/search`). Replace the demo `CATALOG` array with a call to your own product catalog or search API.
2. Create the custom widget using the five steps above. In **Configure the widget**, set the **Widget URL** to your page with the `{irpid}` and `{click_url_encoded}` tokens (shown below).
3. Test with **Open in new tab**, run a search as a test partner, and confirm result links resolve to your site and record a click. Then switch the widget to **Embed in impact.com**.

**Widget 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>Product search</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="Search products..." />
    <button id="go">Search</button>
  </div>
  <div id="results"></div>

  <script>
    // 1. Read the values impact.com injected into the Widget URL.
    var params    = new URLSearchParams(window.location.search);
    var partnerId = params.get('partner') || '';
    var clickUrl  = decodeURIComponent(params.get('clickurl') || '');

    // 2. Replace this demo array with a call to your own product catalog / search 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. Build a trackable deep link: the partner's click URL + the destination page.
    //    Confirm your program's exact deep-link format before publishing (see "Before you publish").
    function buildTrackingLink(destinationUrl) {
      if (!clickUrl) return destinationUrl;            // fallback: no tracking if the token is missing
      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>No products found.</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>

### Example 2: Dynamic rich media ad (floating chat widget)

A dynamic rich media ad is any interactive HTML asset you host and embed as a widget. In this example, you'll build a floating chat bubble that expands into a promo message and a call-to-action. When the visitor selects the button, they're redirected through the partner's click URL, so the click is tracked and attributed.

1. Host the page on a domain you control, over HTTPS (e.g., `https://widgets.yourbrand.com/chat`). Customize the copy, colors, and call-to-action to match your campaign.
2. Create the custom widget using the five steps above, setting the **Widget URL** with the `{click_url_encoded}` token (shown below).
3. Test with **Open in new tab** as a test partner, confirm the call-to-action opens your site and records a click, then switch the widget to **Embed in impact.com**.

**Widget URL**

{% code overflow="wrap" %}

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

{% endcode %}

To send visitors to a specific page instead of your default landing page, use the `{click_url_encoded_deeplink}` token in place of `{click_url_encoded}`, or append the destination in your own code as shown in Example 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>Assistant</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>Hi! Looking for our latest deals? Tap below to shop and save.</p>
    <button id="cta">Shop now</button>
  </div>

  <script>
    // impact.com injects the partner's click URL into this page.
    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;
      // Open in a new tab so the click is tracked and attributed to the partner.
      window.open(clickUrl, '_blank', 'noopener');
    });
  </script>
</body>
</html>
```

</details>

## Before you publish

* Host it yourself, over HTTPS. impact.com embeds your page via an iframe or opens it in a new tab — it doesn't host your code. In embedded mode your page runs inside an iframe, so open destination links with `target="_blank"` or `window.open(...)` rather than navigating the parent window.
* Encode the click URL. Pass it as `{click_url_encoded}` and decode it in your page so its own `?` and `&` characters don't break your query string.
* Confirm your deep-link format with your impact.com Integration Engineer, and make sure destinations are covered by your permitted domains for deep linking.

## Additional resources

* [Create & Share Tracking Links with Partners](/brand/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-and-share-tracking-links-with-partners.md) — How to create tracking links and share them with your partners.
* [Tracking Link Parameters Explained](/brand/what-would-you-like-to-learn-about/platform-features/tracking/tracking-explained/tracking-link-parameters-explained.md) — The structure of a tracking link and the parameters you can add, such as sub IDs, shared ID, and deep links.
* [Set Up Permitted Domains for Deep Linking](/brand/what-would-you-like-to-learn-about/account-administration/program-settings/tracking-settings/set-up-permitted-domains-for-deep-linking.md) — Authorize the destination domains partners are allowed to deep link to on your site.
* [Introduction to Asset Types](/brand/what-would-you-like-to-learn-about/platform-features/ads/create-ads/introduction-to-asset-types.md) — The asset types you can offer partners, including where the custom widget fits.
* [Rakuten Advertising to impact.com: Key Transition Steps](/brand/what-would-you-like-to-learn-about/getting-started/rakuten-advertising-to-impact.com-key-transition-steps.md) — What changes when you migrate a program from Rakuten Advertising to 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/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.