Writing your own Placeholders
Now that you've seen how Placeholders work, you might want to write your own placeholder, either because our existing list of Placeholders does not include your third party, or if you want to design a Placeholder that's more inline with your site's design.
Base Placeholder HTML Template
The author and title <meta> tags are required so that we may identify your placeholder.
<!DOCTYPE html>
<html>
<head>
<meta name="author" content="Your Company Name"/>
<meta name="title" content="Placeholder name"/>
<script src="https://placeholders.confirmic.com/confirmic-api.js"></script>
</head>
<body>
<!-- Your Placeholder content here -->
</body>
</html>
Browser Support
If you execute any JavaScript inside your Placeholders, remember to either transpile it using Babel or write ES5 for maximum browser support.
We provide a Promise polyfill as part of the
confirmic-api.jsfile, but you must include anything else that you want to polyfill.
Declaring Parameters
Placeholders don't have to be static HTML files, and can accept some parameters to change how they look. To let users of your placeholder know what kinds of parameters are accepted by your Placeholder, you can declare them using meta tags inside the <head>.
Each parameter must, in its content attribute, must have the following syntax name={value}, type={value}, default={value}. This is used to name your parameter, give it a default value, and declare its type so that it may be changed from the Confirmic dashboard.
Possible values for type are: string, integer, float, color, date and boolean.
<meta name="mtm:param" content="name=color, type=color, default=#0d71bb"/>
Requesting Consent
As a placeholder is rendered in place of some blocked content, its power comes from being able to let your user request for consent at its position, giving the user full context of what they are consenting to.
Most placeholders will therefore have a button that users can click on, presenting them with some information about what they are consenting to, and which 3rd party will receive their data. The easiest way to enable this functionality is by adding the data attribute data-mtm-button to any element in your placeholder (even the <body>). When users interact with that button, they'll then be presented with one of several ways to give their consent.
If the data-mtm-button doesn't serve your needs completely, the confirmic-api.js file provides a few lower level APIs for you to use.
Ways of obtaining consent
When a request for consent is made, Confirmic draws a modal on top of the page, giving the user context about what data is being sent to the relevant third party, and if cookies are sent along.
<!DOCTYPE html>
<html>
<head>
<meta name="author" content="Your Company Name"/>
<meta name="title" content="Placeholder name"/>
<script src="https://placeholders.confirmic.com/confirmic-api.js"></script>
</head>
<body data-mtm-button>
Enable content
</body>
</html>
There are some cases in which showing a full modal may be a jarring experience, and showing a tooltip on hover might be more appropriate. To enable this functionality, add the one-click configuration option set to the value of tooltip to your placeholder:
<!DOCTYPE html>
<html>
<head>
<meta name="author" content="Your Company Name"/>
<meta name="title" content="Placeholder name"/>
<script src="https://placeholders.confirmic.com/confirmic-api.js"></script>
<meta name="mtm:one-click" content="tooltip" />
</head>
<body data-mtm-button>
Enable content
</body>
</html>
Tooltips on Mobile
On mobile devices (or any device that does't support hover), Confirmic falls back to the modal
one-clickvariant so that users are not surprised when they interact with your Placeholder.
Configurations
one-click is an example of the different ways that you can configure your Placeholder. These are different from parameters in that configurations are predefined by Confirmic, and provide a standardised way of rendering your Placeholder and its interactions, whereas parameters are up to you to define and use in your Placeholder.
All configuration names must be prefixed with mtm: , and you may programmatically add configurations at run-time with the API.setConfiguration(name, content) method.
As part of the Placeholder lifecycle, API.applyConfiguration() is called automatically once the Placeholder is fully loaded. If you make a call to API.setConfiguration(name, content) after the initial lifecycle (for example, on a user event), you must call API.applyConfiguration() for those configurations to be applied.
Currently, only 2 configurations are supported:
| Name | Description | Values |
|---|---|---|
| container-style | Sets the style of the placeholder's container. Allowing you position and resize the placeholder as needed. | Accepts any css properties delineated by semicolons. See cssText |
| one-click | Sets the interaction of how a user may give consent. | unset or tooltip. |
Applying configurations
In general, configurations are applied in the DOM order of the
<meta>tags representing them. However, if you have acontainer-styleconfiguration, it always gets applied first since it may trigger a re-layout of your Placeholder, and thus affect how the subsequent configurations take effect.
Placeholder Lifecycle
┌──────────────────┐
│ │
│ Blocked Script │
│ │
└──────────────────┘
│
│ Placeholder activation
│ begins
│
▼
┌─────────────────────────────────────┐
│ │
│ Blocked element converted to │
│ <iframe src="MyPlaceholder.html" /> │
│ │
└─────────────────────────────────────┘
│
│ iframe's `onload` fired
│ by browser
|
▼
┌─────────────────────────────────────┐
│ │
│ API.onReady() called │
│ │
└─────────────────────────────────────┘
│
│ Any Promise
│ returned resolves
|
▼
┌─────────────────────────────────────┐
│ │
│ API.applyConfiguration() called │
│ │
└─────────────────────────────────────┘
Updated almost 5 years ago