Custom HTML

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

Navigate to the Connections
page in your Converge dashboard
Click on
Create New Connection
.
Fill in the Connection name.
In Select app, select the Custom HTML option.
In Setup script, fill in the setup script (if any).
In Event scripts, click Add script
In Select trigger, select the desired event.
Fill in the script.
Click on Create Connection to persist the connection.

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

Custom HTML
<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>

Custom HTML
<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>

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

Custom HTML
<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>

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.

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

Getting started

Sources

Connections

Attribution

Insights & Dashboards

Marketing Sources

Settings

Overview

Installation Instructions

Definitions

HTML Content

Setup script

Examples

Event scripts

Examples

Variables

Converge functionality

Getting started

Sources

Connections

Attribution

Insights & Dashboards

Marketing Sources

Settings

​Overview

​Installation Instructions

​Definitions

​HTML Content

​Setup script

​Examples

​Event scripts

​Examples

​Variables

​Converge functionality

Overview

Installation Instructions

Definitions

HTML Content

Setup script

Examples

Event scripts

Examples

Variables

Converge functionality