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

# Crea un widget personalizzato

Sviluppa strumenti dinamici che consentano ai partner di promuovere il tuo brand. I widget personalizzati ti permettono di incorporare strumenti o pagine ospitati esternamente direttamente nell'interfaccia di impact.com tramite un iframe. Usa questa guida per creare e configurare un widget di contenuto personalizzato che fornisca risorse personalizzate e un'esperienza di brand coerente per i tuoi partner.

{% stepper %}
{% step %}

## Accedi al creatore di widget personalizzati

1. Dal menu di navigazione a sinistra, seleziona ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage]** → **Contenuto** → [**Widget**](https://app.impact.com/secure/advertiser/engage/ads/list-widget-tool-flow.ihtml)**.**
2. Nell'angolo in alto a destra, seleziona **Crea widget** → **Personalizzato**.
   {% endstep %}

{% step %}

## Inserisci i dettagli del widget

1. Inserisci un **Nome** del widget personalizzato.
2. Facoltativamente, inserisci un **Descrizione** per il widget personalizzato.
3. Facoltativamente, inserisci un **Etichetta** per il widget personalizzato.
4. Se necessario, ![](https://1043985218-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) **\[Attiva] Limita l'accesso dei partner** per specificare partner e gruppi individuali che devono avere accesso al widget.
   * **Partner:** Inserisci il nome dei partner che possono accedere al widget personalizzato.
   * **Gruppi:** Inserisci il nome dei gruppi che possono accedere al widget personalizzato.
     {% endstep %}

{% step %}

## Configura il widget

1. Seleziona il comportamento del widget dalle opzioni di visualizzazione:
   * **Apri in una nuova scheda:** Apre l'URL ospitato in una scheda separata.
   * **Incorpora in impact.com:** Mostra il widget direttamente nell'interfaccia della piattaforma.
2. Facoltativamente, da **Immagine di anteprima** sezione, seleziona **Scegli file** per caricare una miniatura. Assicurati che il file sia un GIF, JPG o PNG e non superi 512 KB.
3. Nel **URL del widget** campo, inserisci l'indirizzo web in cui è ospitato il tuo widget.
4. Dalla ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[Menu a discesa]**, seleziona il protocollo (ad es. https\://) che corrisponde alla sicurezza del tuo sito.
5. Facoltativamente, seleziona ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-6282f271b7521383385339243690b303086736d9%2F3b5a585dd2895bdf1c30d1236c72ba590dddd18717863b27074c8d313d05ae20.svg?alt=media) **\[Aggiungi] Inserisci campi dinamici** per espandere l'elenco dei token.
6. Individua il token che desideri usare e seleziona **Inserisci**. La piattaforma aggiungerà automaticamente il token (ad es. {irpid}) al tuo **URL del widget**. Fai riferimento a [Token dei campi dinamici](#dynamic-field-tokens) sezione sottostante per una descrizione di ciascun token.
   {% endstep %}

{% step %}

## Aggiorna le impostazioni avanzate

Dalla **Lingua** ![](https://1043985218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c2cb550b55c51ea1eeff0acbd6f437a03b621a2c%2F60d033ae8a04c14498d5229c3c0160ac05feea7f605dbd770741793c900469f0.svg?alt=media)**\[Menu a discesa]**, seleziona la lingua in cui verrà visualizzato questo widget.
{% endstep %}

{% step %}

## Finalizza il widget personalizzato

Seleziona **Crea** per salvare il widget. I partner possono trovare questo widget in *Widget di contenuto*.
{% endstep %}
{% endstepper %}

<details>

<summary>Token dei campi dinamici</summary>

| Token                          | Descrizione                                               |
| ------------------------------ | --------------------------------------------------------- |
| `{click_url_encoded}`          | URL del clic codificato                                   |
| `{click_url}`                  | URL del clic non codificato                               |
| `{irimpurl}`                   | Il nostro URL di impressione                              |
| `{irpid}`                      | ID partner                                                |
| `{subid1}`                     | Sub ID partner 1                                          |
| `{subid2}`                     | Sub ID partner 2                                          |
| `{subid3}`                     | Sub ID partner 3                                          |
| `{sharedId}`                   | ID condiviso                                              |
| `{iradid}`                     | ID annuncio                                               |
| `{ircid}`                      | ID programma                                              |
| `{click_url_encoded_deeplink}` | URL del clic codificato con parametro deep link aggiunto. |

</details>

## Esempi pratici

{% hint style="info" %}
**Informazioni su questi esempi:** I widget personalizzati sono creati e ospitati da te — impact.com si limita a incorporare la pagina ospitata e a inserirvi dati live del partner. Copia le implementazioni di riferimento qui sotto, ospitale sul tuo dominio e adattale. I partner non modificano mai alcun codice; aprono semplicemente il widget finito da *Widget di contenuto*.
{% endhint %}

### Come i token dei campi dinamici raggiungono il tuo widget

Quando aggiungi un token di campo dinamico al **URL del widget**, impact.com lo sostituisce con i valori reali di ciascun partner prima di caricare la tua pagina. La tua pagina legge quei valori dalla stringa di query e li usa per creare link tracciabili.

Ad esempio, se imposti il **URL del widget** per `https://widgets.yourbrand.com/search?partner={irpid}&clickurl={click_url_encoded}`, impact.com carica quanto segue per un partner il cui 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" %}
Passa l'URL del clic come `{click_url_encoded}`, non `{click_url}` — un URL del clic non codificato contiene a sua volta i propri `?` e `&` caratteri, che interrompono la tua stringa di query. Decodificalo nella tua pagina prima dell'uso.
{% endhint %}

### Esempio 1: widget di ricerca

Consente a un partner di cercare nel tuo catalogo e copiare un link tracciabile per qualsiasi prodotto senza uscire da impact.com. Tu ospiti la pagina di ricerca; impact.com passa l'ID del partner e l'URL del clic, così ogni link risultato viene attribuito a quel partner.

1. Ospita la pagina di ricerca su un dominio che controlli, tramite HTTPS (ad es., `https://widgets.yourbrand.com/search`). Sostituisci l'array demo `CATALOG` con una chiamata al tuo catalogo prodotti o alla tua API di ricerca.
2. Crea il widget personalizzato usando i cinque passaggi sopra. In **Configura il widget**, imposta il **URL del widget** alla tua pagina con i `{irpid}` e `{click_url_encoded}` token (mostrati di seguito).
3. Prova con **Apri in una nuova scheda**, esegui una ricerca come partner di prova e conferma che i link dei risultati conducano al tuo sito e registrino un clic. Quindi imposta il widget su **Incorpora in impact.com**.

**URL del widget**

{% 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>Ricerca prodotti</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="Cerca prodotti..." />
    <button id="go">Cerca</button>
  </div>
  <div id="results"></div>

  <script>
    // 1. Leggi i valori che impact.com ha inserito nell'URL del widget.
    var params    = new URLSearchParams(window.location.search);
    var partnerId = params.get('partner') || '';
    var clickUrl  = decodeURIComponent(params.get('clickurl') || '');

    // 2. Sostituisci questo array demo con una chiamata al tuo catalogo prodotti / API di ricerca.
    var CATALOG = [
      { name: 'Scarpa Trail Runner',   url: 'https://www.yourbrand.com/products/trail-runner' },
      { name: 'Giacca impermeabile',   url: 'https://www.yourbrand.com/products/waterproof-jacket' },
      { name: 'Calze da trekking in lana merino', url: 'https://www.yourbrand.com/products/merino-socks' }
    ];

    // 3. Crea un deep link tracciabile: l'URL del clic del partner + la pagina di destinazione.
    //    Conferma il formato esatto del deep link del tuo programma prima di pubblicare (vedi "Prima di pubblicare").
    function buildTrackingLink(destinationUrl) {
      if (!clickUrl) return destinationUrl;            // fallback: nessun tracciamento se il token è mancante
      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>Nessun prodotto trovato.</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 + '">Copia 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>

### Esempio 2: annuncio rich media dinamico (widget chat flottante)

Un annuncio rich media dinamico è qualsiasi asset HTML interattivo che ospiti e incorpori come widget. In questo esempio, creerai una bolla chat flottante che si espande in un messaggio promozionale e una call-to-action. Quando il visitatore seleziona il pulsante, viene reindirizzato tramite l'URL del clic del partner, così il clic viene tracciato e attribuito.

1. Ospita la pagina su un dominio che controlli, tramite HTTPS (ad es., `https://widgets.yourbrand.com/chat`). Personalizza il testo, i colori e la call-to-action in modo che corrispondano alla tua campagna.
2. Crea il widget personalizzato usando i cinque passaggi sopra, impostando il **URL del widget** con il `{click_url_encoded}` token (mostrato di seguito).
3. Prova con **Apri in una nuova scheda** come partner di prova, conferma che la call-to-action apra il tuo sito e registri un clic, quindi imposta il widget su **Incorpora in impact.com**.

**URL del widget**

{% code overflow="wrap" %}

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

{% endcode %}

Per inviare i visitatori a una pagina specifica invece della tua landing page predefinita, usa il `{click_url_encoded_deeplink}` token al posto di `{click_url_encoded}`, oppure aggiungi la destinazione nel tuo codice come mostrato nell'Esempio 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>Assistente</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>Ciao! Cerchi le nostre ultime offerte? Tocca qui sotto per fare acquisti e risparmiare.</p>
    <button id="cta">Acquista ora</button>
  </div>

  <script>
    // impact.com inserisce in questa pagina l'URL del clic del partner.
    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;
      // Apri in una nuova scheda in modo che il clic venga tracciato e attribuito al partner.
      window.open(clickUrl, '_blank', 'noopener');
    });
  </script>
</body>
</html>
```

</details>

## Prima di pubblicare

* Ospitalo tu stesso, tramite HTTPS. impact.com incorpora la tua pagina tramite un iframe o la apre in una nuova scheda — non ospita il tuo codice. In modalità incorporata la tua pagina viene eseguita all'interno di un iframe, quindi apri i link di destinazione con `target="_blank"` o `window.open(...)` anziché navigare la finestra padre.
* Codifica l'URL del clic. Passalo come `{click_url_encoded}` e decodificalo nella tua pagina in modo che i suoi `?` e `&` caratteri non interrompano la tua stringa di query.
* Conferma il formato del tuo deep link con il tuo Integration Engineer di impact.com e assicurati che le destinazioni siano incluse nei domini consentiti per il deep linking.

## Risorse aggiuntive

* [Crea e condividi link di tracciamento con i partner](/brand/it/what-would-you-like-to-learn-about/platform-features/reach-out-to-partners/generate-leads/create-and-share-tracking-links-with-partners.md) — Come creare link di tracciamento e condividerli con i tuoi partner.
* [Parametri dei link di tracciamento spiegati](/brand/it/what-would-you-like-to-learn-about/platform-features/tracking/tracking-explained/tracking-link-parameters-explained.md) — La struttura di un link di tracciamento e i parametri che puoi aggiungere, come sub ID, ID condiviso e deep link.
* [Configura i domini consentiti per il deep linking](/brand/it/what-would-you-like-to-learn-about/account-administration/program-settings/tracking-settings/set-up-permitted-domains-for-deep-linking.md) — Autorizza i domini di destinazione a cui i partner sono autorizzati a creare deep link sul tuo sito.
* [Introduzione ai tipi di asset](/brand/it/what-would-you-like-to-learn-about/platform-features/ads/create-ads/introduction-to-asset-types.md) — I tipi di asset che puoi offrire ai partner, incluso il ruolo del widget personalizzato.
* [Da Rakuten Advertising a impact.com: passaggi chiave della transizione](/brand/it/what-would-you-like-to-learn-about/getting-started/rakuten-advertising-to-impact.com-key-transition-steps.md) — Cosa cambia quando migri un programma da Rakuten Advertising a 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/it/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.