Custom HTML
Setting up a Custom HTML destination
Overview
Destination Type:
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 or in response to an event. Your custom HTML can also reference event variables allowing you to implement dynamic behavior based on those properties.
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.
Installation Instructions
- In the Converge sidebar, click on Event streamsand then click Create new Destination.
- Select the Custom HTML destination and click Next.
- Give your destination a name (e.g. Custom HTML Destination) and click Next.
- In Setup script, fill in the setup script (if any).
- In Event scripts, click Add Event Script
- In Event name, select the desired event to trigger the script.
- In Event script, fill in the script you want to trigger.
- Click Next.
- Select the sources you want to trigger the Custom HTML, then click Next.
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.
- 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. The content can be injected into your website either during initialization or in response to an event. Regardless of the timing, the content will always be added as the last element of the <body>
tag of your page.
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.
Setup script
Defines a custom HTML that is injected into your website upon initialization. As soon as the 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.
Examples
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.
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.
Examples
Variables
When using 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. 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 |
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.
- by providing a default value, e.g.
- or any other pattern you may prefer.
Converge functionality
This integration supports the following Converge destination functionality.
Converge Feature | Supported |
---|---|
Custom Events | |
Filters | |
Server-side Conversions |