> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runconverge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom HTML

> Setting up a Custom HTML destination

export const OutboundLink = ({linkText, linkTarget}) => {
  return <a target="_blank" href={linkTarget}> {linkText} 
    <div className="inline h-3 w-3 fill-gray-500 dark:fill-gray-100 text-gray-500 dark:text-gray-300 ml-1 mr-1">
      <svg className="inline w-2.5 h-2.5 bg-gray-500 dark:bg-gray-300" style={{
    maskImage: `url('https://mintlify.b-cdn.net/v6.5.1/solid/up-right-from-square.svg')`,
    maskRepeat: "no-repeat",
    maskPosition: "center center"
  }}></svg> 
    </div>
    </a>;
};

export const IconText = ({name, text, iconSource = "mintlify", iconLocation = "before", iconType = "solid"}) => {
  const sourceUrl = iconSource === 'local' ? `url('/images/icons/${name}.svg')` : `url('https://mintlify.b-cdn.net/v6.5.1/${iconType}/${name}.svg')`;
  return <>
            <div className="inline-block pl-2">
                {iconLocation === 'before' && <div className="h-3.5 w-3.5 fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100 inline-block align-middle mr-2">
                        <svg className="w-4 h-4 bg-gray-800 dark:bg-gray-100 " style={{
    maskImage: sourceUrl,
    maskRepeat: "no-repeat",
    maskPosition: "center center"
  }} />
                    </div>}
                <span className="inline-block align-middle font-semibold fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100 pl-1 pr-2">{text}</span>
                {iconLocation === 'after' && <div className="h-3.5 w-3.5 fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100 inline-block align-middle mr-2">
                        <svg className="w-4 h-4 bg-gray-800 dark:bg-gray-100 pr-3" style={{
    maskImage: sourceUrl,
    maskRepeat: "no-repeat",
    maskPosition: "center center"
  }} />
                    </div>}
            </div>
        </>;
};

export const Icon = ({name}) => {
  return <div className="h-4 w-4 fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100 inline-block align-middle">
            <svg className="w-4 h-4 bg-gray-800 dark:bg-gray-100" style={{
    maskImage: `url('https://mintlify.b-cdn.net/v6.5.1/solid/${name}.svg')`,
    maskRepeat: "no-repeat",
    maskPosition: "center center"
  }} />
        </div>;
};

## Overview

Destination Type: <IconText text="Client-side" name="browser" iconType="duotone" iconLocation="after" />

For cases where the native destinations supported by Converge are not enough for your requirements, the Custom HTML destination allows you to deploy arbitrary HTML code to your website.

Any HTML content (HTML, scripts, styles) can be injected into your website either during [initialization](#setup-script) or in response to an [event](#event-scripts). Your custom HTML can also reference event variables allowing you to implement dynamic behavior based on those properties.

<Warning>
  Notice that any script added through the Custom HTML destination has full access to the website. In addition, scripts may affect performance and potentially break your website.

  As such, make sure to only add content that you trust and to always verify your changes.
</Warning>

***

## Installation instructions

1. In the Converge sidebar, click on <IconText name="arrow-right-from-line" text="Event streams" /> and then click **Create new Destination**.
2. Select the **Custom HTML** destination and click **Next**.
3. Give your destination a **name** (e.g. Custom HTML Destination) and click **Next**.
4. In **Setup script**, fill in the setup script (if any).
5. In **Event scripts**, click **Add Event Script**
6. In **Event name**, select the desired event to trigger the script.
7. In **Event script**, fill in the script you want to trigger.
8. Click **Next**.
9. Select the sources you want to trigger the Custom HTML, then click **Next**.
   <Note>This is a client-side destination, meaning that only client-side sources can be used with this destination. You can still select server-side sources but the events will not trigger the Custom HTML.</Note>
10. Review any issues and click **Submit**.

***

## Definitions

### HTML Content

Any arbitrary HTML can be used, including text, images, styles, and Javascript. The HTML content is dynamically injected into your website by the [Converge pixel](/sources/website-integrations/converge-pixel). The content can be injected into your website either during [initialization](#setup-script) or in response to an [event](#event-scripts). Regardless of the timing, the content will always be added as the last element of the `<body>` tag of your page.

<Info>
  The HTML content follows the same structure as a normal HTML file. As such, always make sure to wrap Javascript code with the `<script>` tag. Otherwise, the content will be rendered as normal text content rather than executed.
</Info>

### Setup script

Defines a custom HTML that is injected into your website upon initialization. As soon as the [Converge pixel](/sources/website-integrations/converge-pixel) is initialized, this content will be injected into your website.

It can be used to add any custom HTML content or execute a script that doesn't depend on any action from the user. For example, to install a pixel/snippet that is not provided natively by Converge or to make any necessary preparation for the handling of events by an [Event script](#event-scripts).

#### Examples

<Accordion icon="clipboard" title="Install PostHog">
  ```Markup Custom HTML theme={null}
  <script>
      !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
      posthog.init('<ph_project_api_key>', {api_host: "<ph_instance_address>"})
  </script>
  ```
</Accordion>

<Accordion icon="clipboard" title="Install Hotjar">
  ```Markup Custom HTML theme={null}
  <script>
      (function(h,o,t,j,a,r){
          h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
          h._hjSettings={hjid:<hjid>,hjsv:<hjsv>};
          a=o.getElementsByTagName('head')[0];
          r=o.createElement('script');r.async=1;
          r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
          a.appendChild(r);
      })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
  </script>
  ```
</Accordion>

### Event scripts

Defines a custom HTML that is injected into your website when a given event occurs. Event scripts are always linked to exactly one **Event** type. The custom HTML will be injected into your website whenever (potentially multiple times) the configured event occurs.

It can be used to add any custom HTML content or execute a script as soon as an event has occurred. For example, to send an event to a pixel/tag that is not provided natively by Converge.

Event scripts can also reference event [variables](#variables).

<Note>
  Note that the Custom HTML destination can only be triggered by events that are implemented client-side. If your event is solely tracked server-side, it will not be compatible with the Custom HTML destination.
</Note>

#### Examples

<Accordion icon="clipboard" title="Viewed Product">
  ```Markup Custom HTML theme={null}
  <script>
  console.log('Viewed Product', {
      product: {
          productId: {{ product_id }},
          productName: {{ name }},
          productPrice: {{ price }}
      },
  })
  </script>
  ```
</Accordion>

<Accordion icon="clipboard" title="Placed Order">
  ```Markup Custom HTML theme={null}
  <script>
  var items = {{ items }} || []
  console.log('Placed Order', {
      totalPrice: {{ total_price }},
      itemsCount: items.reduce((total, item) => total + item.quantity, 0),
      products: items.map(item => ({
          productId: item.product_id,
          productName: item.name,
          productPrice: item.price
      }))
  })
  </script>
  ```
</Accordion>

### Variables

When using [Event scripts](#event-scripts), it's possible to reference event properties by making use of variables. These variables are referenced by wrapping the variable name with double braces: `{{ variable_name }}`.

For each occurrence of an event linked to a Custom HTML script, Converge will resolve all the referenced variables, replace the variables in the template and finally inject the resulting content.

The available variables depend on the selected Event type. For the native events, the list of available properties and their types can be found in the [event spec](/sources/converge-spec). For custom events, all properties sent in the events are available for usage automatically.

As an example, for the **Place Order** event, the following variables are available (among others):

| Property                | Type        | Template                 | Injected                     |
| :---------------------- | :---------- | ------------------------ | ---------------------------- |
| **id**                  | **string**  | `{{ id }}`               | `"123"`                      |
| **total\_price**        | **float**   | `{{ total_price }}`      | `123`                        |
| **items**               | **array**   | `{{ items }}`            | `[{"product_id": ...}, ...]` |
| **\$is\_new\_customer** | **boolean** | `{{ $is_new_customer }}` | `true`                       |

<Note>
  Notice that variables can be undefined. As such, it's important to always validate the variable value to avoid runtime errors. This can be done, for example:

  * by checking the value directly. e.g.

  ```
  if ({{ variable_name }} != null) { ... }
  ```

  * by providing a default value, e.g.

  ```
  var items = {{ items }} || []
  ```

  * or any other pattern you may prefer.
</Note>

***

## Converge functionality

This integration supports the following Converge destination functionality.

| Converge Feature        |       Supported       |
| :---------------------- | :-------------------: |
| Custom Events           | <Icon name="xmark" /> |
| Filters                 | <Icon name="xmark" /> |
| Server-side Conversions | <Icon name="xmark" /> |