Help Center

Most dialogues in BlueConic add extra HTML to your page so that the dialogue content appears as an overlay or alongside the other content. However, one specific dialogue, the Properties-Based Dialogue, works differently; rather than injecting HTML (or CSS) onto your page, it offers the content via JSON so your organization can determine exactly how it's used.

Visually, the flow of the Properties-Based Dialogue works as illustrated here:

Use cases for the Properties-Based Dialogue

There are several use cases when HTML injection is not possible or not the preferred solution and using the Properties-Based Dialogue would be the better option:

• You want complete control of how the content is rendered. Rendering is often controlled by your Web development team.
• Your website uses a front-end framework, causing a conflict. If your website uses a framework like React or Vue, manipulating the HTML often causes issues because the framework expects to control the DOM node. A conflict then arises if you want to change content in a position of the site that is controlled by the framework.
• You prefer to use content from your CMS (and not have content/styling in BlueConic). This becomes visible in cases where a restyling is rolled out and your content and styling in BlueConic doesn’t match the restyling. (The customer script first calls the CMS API to get the content, rather than using content from BlueConic directly; the result of this call is used to render content on the Web page.)
• Your dialogue doesn’t actually show content. It may be used to trigger some functionality instead, such as a chat client.

Installing the Properties-Based Dialogue

By default, the Properties-Based Dialogue is not installed in BlueConic. To install it, navigate to BlueConic settings > Plugins, click the Add plugin button at the top right, and register the following external URL:

https://plugins.blueconic.net/dialogue_properties_based/index.xml

For more detailed instructions, review the article Overview: What are BlueConic plugins?. And if you need further assistance, reach out to BlueConic Support.

Adding and configuring a Properties-Based Dialogue

To add a Properties-Based Dialogue to your tenant, follow these steps:

1. Click Dialogues from the BlueConic navigation menu.
2. Click the Add dialogue button at the top right.
3. In the window that opens, find and select the Properties based dialogue option.

Once the dialogue is added, use the main dialogue tabs to create the content and configure where and when it should appear:

• Who: Create an audience for the dialogue by selecting conditions (profile properties, group properties, etc.) that shape the segment of profiles to view the content.
• When: Select the dialogue priority, and schedule the times to show the dialogue.
• Where: Select a BlueConic channel where the dialogue should appear.
• What: Input your JSON. For detailed instructions, review the next section Defining dialogue content on the What tab.
• Why: Add a conversion moment to track click-through or view-through conversions.

Defining dialogue content on the What tab

Before defining and inputting the dialogue content, you first need to work with your Web development team to create an example JSON for the text and imagery you want. For instance, if you want the dialogue to have a specific image and title, your Web developer could deliver something like this:

{
  "img": "https://www.mysite.com/sample.png",
  "title": "Title of the image"
}

Tip for Web developers: Refer to the following information on consuming the JSON (which displays in BlueConic next to "How to use" on the What tab):

You can listen to the Properties-Based Dialogue event to get access to the data.

The data can be consumed in two ways. First, by registering an Event Listener to the web event. Note: Make sure the Event Listener is added before the BlueConic event is triggered.

window.addEventListener("BlueConic:propertiesDialogue", function(data) {

  // you can use "data.detail" to get access to the JSON, the position and variant ID

});

Second, by subscribing to the BlueConic event using the BlueConic frontend API. Make sure to wait for the BlueConic client to be available. It doesn’t matter if the subscribe event occurs before or after the event is thrown. In both cases, the handler will be triggered.

window.blueConicClient.event.subscribe("propertiesDialogue", this, function(event, data) {

  // you can use "data" to get access to the JSON, the position and variant ID

});

Note: It is up to the website what to do with the data (for example, to get data from the CMS). Also, the website is responsible for registering clicks using the BlueConic API. Since the rendering is happening outside of the scope of BlueConic, the platform doesn’t know when a click happens.

Adding a template to the Definition field

When your JSON is ready, navigate to the What tab and input it as an individual template in the Definition field. The first available template you have stored in BlueConic may appear for the Definition–click the Select other link to use your own.

Clicking this link opens the “Select definition” menu, where you can create a template by clicking the Add new template button. You can also select any previously saved template here.

Once you click Add new template, an “Edit new definition” window opens; this is where you copy and paste your JSON into the main input field (as shown below with the earlier example).

Make sure to also click into the “New definition” title field at the top and give your template a distinguishable name. (Optionally, click Show meta data at the top right to add a description and/or thumbnail for your template; that metadata will appear with the template listing in the “Select definition” menu to help differentiate between templates.)

When finished, click Save definition at the bottom.

Whatever template you add or select will appear next to the Definition field on the What tab. You can make any changes to the JSON by clicking that linked title, which reopens the “Edit definition” window.

Using the input fields

Once you define a template in the Definition field, a series of fields appear underneath it; these fields are created based on that selected template, using the following logic:

• When the value ends with PNG, JPEG, JPG, or GIF, a file upload option is shown.
• When the value is an array of strings (e.g., [“interest1”, “interest2”]), a multi-value field is shown.
• When the value is a number, a number input field is shown.
• When the value is an array of objects, an Add button is shown to add a new object. For each object, the same logic is applied.
• When the value is an object, the object is shown as an indented value. (Otherwise a text input field is shown.)

If you need to add values or make changes to the template and want your Web development team to review the updated JSON, input new values in these fields and check the “Show output” box. This opens an output section to the right with the updated JSON that you can send them.

Notes:

• If personalization is configured in the JSON (using {{propertyID}} in the content), the placeholders are defined with the values from the profile. For example, if you have Hello, {{firstName}} in a text box, the dialogue will replace the {{firstName}} placeholder with the value from the profile property with ID firstName. 
• The BlueConic user has to select a position through the Where tab, and this position has to exist on the Web page, otherwise the dialogue will not be triggered. Because BlueConic is not rendering the content, BlueConic doesn’t know when a click or other action is happening. This means your Web development team is responsible for logging click and conversion events using the BlueConic front-end API. For example:

if (somethingHappened) {
  // blueConicVariantId is received in the event
  blueConicClient.createEvent('CLICK', blueConicVariantId);
}

if (somethingElseHappened) {
  // blueConicVariantId is received in the event
  blueConicClient.createEvent('CONVERSION', blueConicVariantId);
}