Custom HTML
Setting up a Custom HTML connection
Overview
Connection Type: Client-side
For cases where the native connections supported by Converge are not enough for your requirements, the Custom HTML connection 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 connection 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
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 connection 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 connection.
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.
For 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.
if ({{ variable_name }} != null) { ... }
- by providing a default value, e.g.
var items = {{ items }} || []
- or any other pattern you may prefer.
Converge functionality
This integration supports the following Converge connection functionality.
| Converge Feature | Supported |
|---|---|
| Custom Events | |
| Filters | |
| Server-side Conversions |