Help Center

XML Definition File for Plugins

A plugin defines how BlueConic interacts with a user, a channel or a visitor when it is triggered (edit or show content, display a banner, display an Insight, and so forth). Plugins are created using XML (in the form of an XML definition file) and JavaScript (in the form of one or more .js files). The XML definition file for a plugin allows BlueConic to learn what the plugin is for and what its properties are. The file also contains a reference to the JavaScript logic for the plugin.

The JavaScript file for an interaction type plugin contains the logic that controls the behavior of the Dialogue on the front-end (channel). The XML definition file contains a reference to the JavaScript file. Each property within the XML definition file is of a specific parameter type (file, date, html, image, string, number, etc.). This specifies how the property appears in the Interaction tab when the BlueConic user is adding an interaction to a Dialogue as well as what the allowable values are for the property. For example, if the property has a parameter type "Number", then only numbers are allowed to be entered into the field and an error message displays if any letters are used.

There are several types of plugins that all use similar tags in their XML definition file. Not all tags are relevant for every plugin type though. The documentation below will highlight the details where needed.

This is a reference manual for XML definition files. If you want to learn how to build your own plugin, be sure to check out the Getting Started section that contains several tutorials on the subject.


XML tags

The following XML tags are used to determine how an interaction type plugin appears in a Dialogue. To start building your new interaction type, create an XML file from the example below and enrich it with the tags described on this page. Example XML file:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
  <id>unique_plugin_id</id>
  <version>3.1.4</version>
  <type>action</type>
  <name>
    <label locale="en_US">My Plugin</label>
    <label locale="nl_NL">Mijn plugin</label>
  </name>
  <description>
    <label locale="en_US">My Plugin allows for flexible dialogues.</label>
    <label locale="nl_NL">Mijn plugin zorgt voor flexibele dialogen.</label>
  </description>

  <!-- frontend specific properties -->
  <frontend>
    ...
  </frontend>

  <!-- backend specific properties -->
  <backend>
    ...
  </backend>

<!-- profile property definitions -->
<profileproperties>
...
</profileproperties>

<!-- timeline event type definitions -->
<timeline>
...
</timeline> </plugin>

<plugin>

The root tag <plugin> identifies a file as an XML definition file for a BlueConic Plugin. For example:

<plugin>
  ...
</plugin>

<id>

The <id> tag specifies the text that appears in the "Id" column in the list of BlueConic interactions in the Plugin Management panel. The id will be the unique identifier by which BlueConic recognizes your plugin, e.g. when updating it. A valid id may consist of lowercase letters, numbers and underscores (_) and must be at least one character long. For example:

<plugin>
  ...
  <id>balloons_insight</id>
  ...
</plugin>

<version>

Specifies the version number of the plugin. It is wise to increase the version number on new releases of the plugin, as BlueConic will only allow the upload of same or higher version numbers and will prevent you from downgrading to older versions accidentally. For example:

<plugin>
  ...
  <version>3.1.4</version>
  ...
</plugin>

<type>

The <type> tag specifies what type of plugin this is. The table below shows all values and what they mean.

Value Description
action The plugin contains an interaction that performs something visually on the frontend.
connection The plugin contains a connection to another system, synchronizing BlueConic with that other system.
insightwidget The plugin contains an Insight widget that can be added to a Dashboard on the Insights tab.
listener The plugin contains logic to monitor the frontend for user behavior, adding information to the user profile.
toolbar The plugin contains an extension that will be used in the toolbar of the inline editor of a Dialogue.

For example:

<plugin>
  ...
  <!-- One of: "action", "connection", "insightwidget", "listener" or "toolbar" -->
  <type>action</type>
  ...
</plugin>

<name>

Specifies a human readable name labels for all the supported edit language locales (e.g. "en_US" and "nl_NL"). The name will appear in BlueConic where the user selects to use the plugin. Use the <label> tag to define a locale specific label. For example:

<plugin>
  ...
  <name>
    <label locale="en_US">Balloon Insight</label>
    <label locale="nl_NL">Balonnen Inzicht</label>
  <name>
  ...
</plugin>

<description>

Using the <description> tag you specify the text that appears in BlueConic where the plugin is being added. Use the <label> tag to define a locale specific label. For example:

<plugin>
  ...
  <description>
    <label locale="en_US">
      Gives insight in how often values are present in the selected profile
      property for the profiles in the selected segment by showing a balloon chart.
    </label>
    <label locale="nl_NL">
      Geeft inzicht in hoe vaak waarden voorkomen in de geselecteerde
      profieleigenschap voor de profielen in het geselecteerde segment door een
      balonnengrafiek te tonen.
    </label>
  </descriptions>
  ...
</plugin>

For example, if the plugin is displayed in the BlueConic Insights gallery, the above examples will look something like this:


<permissionlevel>

(Only relevant for plugins of type "action")
This tag is part of BlueConic's privacy features. For complete information on the privacy features in BlueConic, see Privacy. The tag sets the required permission level that a visitor must have in order for the interaction to be triggered for them. The possible permission levels for an interaction type are:

Permission Level Description
DO_NOT_TRACK (Level 0) The interaction will be triggered for visitors with at least a static permission level (level 0). In other words, this interaction will be triggered for all visitors.
ANONYMOUS (Level 1) The interaction will be triggered for visitors with at least an anonymous permission level (level 1).
PERSONAL (Level 2) The interaction will only be triggered for visitors with a dynamic permission level (level 2).

If no permission level for an interaction type is explicitly defined, then it is by default DO_NOT_TRACK. The implication of setting a permission level for an interaction type is as follows:

Visitor Permission Level Interaction Type Permission Level Interaction Triggered?
Static (Level 0) DO_NOT_TRACK Yes
Static (Level 0) ANONYMOUS No
Static (Level 0) PERSONAL No
Optimized (Level 1) DO_NOT_TRACK Yes
Optimized (Level 1) ANONYMOUS Yes
Optimized (Level 1) PERSONAL No
Dynamic (Level 2) DO_NOT_TRACK Yes
Dynamic (Level 2) ANONYMOUS Yes
Dynamic (Level 2) PERSONAL Yes

For example:

<plugin>
  ...
  <!-- Permission level DO_NOT_TRACK, i.e. trigger this interaction for all visitors. -->
  <permissionlevel>0</permissionlevel>
  ...
</plugin>

 


<profileindependent>

(Only relevant for plugins that don't require access to the profile)
To disable consent management for one plugin, you can use the <profileindependent> tag. Items based on a plugin for which consent management has been disabled can still be placed into all objectives. In this situation, BlueConic will not limit the execution of the item based on the objectives with consent management turned on.

For example:

<plugin>
  ...<profileindependent> true </profileindependent> 
</plugin>

 


<manualviewcounting>

(Only relevant for plugins of type "action")
By default, each time an interaction is triggered, the view count for the interaction increases by one. This is typically not desirable for custom interactions. For example, if your interaction makes client side JavaScript checks to decide whether or not to execute the interaction, you only want a 'VIEW' to be counted upon actual execution. To manually increase the view count via the JavaScript API, use the createEvent() method with eventtype 'VIEW'.

To keep track of 'VIEW' events yourself and disable auto incrementing of views when an interaction is triggered, set this tag to "true".

For example:

<plugin>
...
<frontend> ... <manualviewcounting>true</manualviewcounting> ...
</frontend>
...
</plugin>

Best practice for custom "action" plugins is to set the <manualviewcounting> tag to true and throw VIEW events at the preferred moment.


<status>

Specifies the status of the interaction type. The only valid value for this optional status tag is deprecated. This will block the creation of new interactions based on this plugin. However, existing interactions that were created before an interaction type was deprecated will still work. For example:

<plugin>
  ...
  <status>deprecated</status>
  ...
</plugin>

<frontend>

The <frontend> tag contains subtags that instruct BlueConic on the frontend aspects of the plugin. In other words: what happens in the browser of the visitor visiting one of the channels.


<frontend>

<script>

Within the interaction type XML definition you need to add a reference to the file containing the JavaScript for the plugin. This is a path relative to the XML definition file itself. Generally this file will be in the same directory as the XML definition file itself. It is not mandatory, but good practice to minify the JavaScript to lower the load on the page from the visitors point of view. In this example, the name of the file is "myplugin.min.js":

  <frontend>
    ...
    <script>myplugin.min.js</script>
    ...
  </frontend>

<frontend>

<positiontype>

(Only relevant for plugins of type "action")
The <positiontype> tag has three possible values:

  1. Empty or undefined (the tag is not present in the interaction type XML).
  2. "overlay". Use this value for interactions that are visible to the visitor of the channel but that are not bound to a specific area within the page, for example in a lightbox interaction.
  3. "position". Use this value for interactions that are visible to the visitor of the website and that are presented at a specific area within the page, for example in a banner interaction.

The value of the "positiontype" tag has the following impact:

  1. The presence of the "Position" property on the Where tab. Using the "Position" property, a user can define at which position on the page the interaction will be displayed.
  2. If there are two or more interactions triggered at the same position, then BlueConic will either execute all of them or BlueConic will execute just one of them (following a 'round-robin' scheduling).

The impact that all three values have is:

  1. If the "positiontype" is empty or undefined, then the "Position" property will not appear on the Where tab. If a visitor triggers more than one interaction and the positiontype is empty or undefined, then all these interactions will be executed.
  2. If the "positiontype" has the value "overlay", then the "Position" property will not appear on the Where tab. If a visitor triggers more than one interaction with positiontype "overlay", then only one of these interactions will be executed.
  3. If the "positiontype" has the value "position", then the Where tab will contain the "Position" property. If a visitor triggers more than one interaction with positiontype "position", then only one of these interactions will be executed.
  <frontend>
    ...
    <!-- One of: "position", "overlay" or empty -->
    <positiontype>position</positiontype>
    ...
  </frontend>

<frontend>

<eventTypes>

Define the custom events that this plugin exposes. This or other plugins may be configured to display on these custom events via the "When" tab, which means those plugins will be executed whenever this plugin publishes the event.

  <frontend>
    ...
    <eventTypes>
      <eventType>
        <id>custom_event</id>
        <name>
          <label locale="en_US">Custom Event</label>
          <label locale="nl_NL">Custom Event</label>
        </name>
      </eventType>
      ...
    </eventTypes>
    ...
  </frontend>

To throw the event from the JavaScript in your plugin, use the createEvent() function, e.g.:

// Note: make sure the event type "custom_event" is defined in the XML definition file
blueConicClient.createEvent("custom_event");

<frontend>

<libraries>

When you want to use external libraries like jQuery in the frontend code of your plugin, you should create a dependency to those libraries. To add an dependency to an external library, you must use the <libraries> section of the XML definition file. Use the <library> tag to list the URL or the path relative to the XML definition file for each library. For example:

  <frontend>
    ...
    <libraries>
      <library>https://code.jquery.com/jquery-1.7.2.min.js</library>
    </libraries>
    ...
  </frontend>

The example above shows how to create a dependency to the jQuery 1.7.2 library. All interactions constructed with this Interaction Type will have their own copy of the library. In this case each interaction has its own jQuery object.

  <frontend>
    ...
    <libraries>
      <library url="/jquery/jquery-1.7.2.min.js" type="javascript"/>
      <library url="/fancybox/jquery.fancybox.js" type="javascript"/>
    </libraries>
  </frontend>

The example above shows how to create dependencies on multiple libraries which are shipped with the plugin. If you use relative URLs in the dependency, the URL is prefixed with the location of the plugin on the BlueConic server. The order in which you declare the dependencies will be the order in which the dependencies are added to your plugin. So in the above example jQuery is added to the scope of the interaction and then the fancybox extension is added to it.

Note: Even when you use relative URLs to declare dependencies, BlueConic will always use absolute URLs to identify an external library.

Using an external library in your Plugin

You must only use external libraries in the onLoad method. All global objects and functions which are created by an external library are added to the context of the interaction. This means that all global objects and functions are only accessible via the scope of the interaction. You must use the this keyword to access the scope of the interaction in your plugin.

// jQuery and '$' are added to the scope of the interaction
this.$.fancybox(settings);

The framework removes global objects and functions introduced by external libraries from the global context when these can cause a conflict with the web page. Never rely on global objects created by external libraries!


<backend>

The <backend> tag contains subtags that instruct BlueConic on the backends aspects of the plugin. In other words: what happens in the browser of the BlueConic user, e.g. a BlueConic user setting up a Dialogue.


<backend>

<parameters>

(Only relevant for plugins of type "action")
Using the <parameters> tag and its subtags, you compose the look and feel of the "Interaction" step of a Dialogue by adding editable standard parameters. With this element you can create string fields, number fields, and date fields, upload images and files, and so forth.

Note that plugin developers are not bound to the standard parameter types and their looks. It is possible to define an entirely custom user interface using widgets. See the tutorials under Getting Started for more information on the subject.

The subtags of <parameters> are explained below, but before we delve into them, here is a detailed example of a fully defined parameter and what it looks like in BlueConic:

<plugin>
  ...
  <backend>
    ...
    <parameters>
      <parameter>
        <id>effect</id>
        <name>
          <label locale="en_US">Effect</label>
          <label locale="nl_NL">Effect</label>
        </name>
        <description>
          <label locale="en_US">Choose the effect with 
which the lightbox should appear and disappear.
</label> <label locale="nl_NL">Kies het effect
waarmee de lightbox zal verschijnen en verdwijnen.
</label> </description> <type>String</type> </parameter> ... </parameters> ... </backend> </plugin>

The result of the example code above is the addition of the "Effect" parameter. It also has a description, so a help link in the form of an "i" icon appears behind the parameter name.

When the user clicks on the help link, the help tooltip displays. For example:


<parameters>

<parameter>

The <parameter> tag defines one parameter that will appears on the "Interaction" tab of a Dialogue. The BlueConic user will use the parameter to define or modify the Dialogue itself. Within the <parameter> tag you define the properties of the element.


<parameter>

<id>

The <id> tag defines the identifier for the <parameter>. This identifier should be unique within set of parameters. A valid identifier string may consist of lowercase letters, numbers and underscores (_) and must be at least one character long.


<parameter>

<name>

The <name> tag defines the human readable name for the <parameter>. Use <label> tags to define language specific labels for the supported locales (e.g. "en_US", "nl_NL").


<parameter>

<description>

The <description> tag defines a description for the <parameter>. Adding a description will display a help link "i" icon next to the name in BlueConic. Use <label> tags to define language specific labels for the supported locales (e.g. "en_US", "nl_NL"). The description can contain HTML as long as you make sure it is escaped for XML. This means either using XML entities like &lt;, &lt; and &amp;, or use CDATA to escape a whole string at once (<![CDATA[ ... ]]>).


<parameter>

<type>

The <type> tag specifies which parameter type this element is. The following types are standard BlueConic parameter types:

Parameter Type Description
boolean Displays a checkbox field that can be enabled or disabled.
file Displays a field with a "Browse" button which the user uses to upload a file (Flash animation, PDF, etc.).
html Allows the user to edit a channel inline with a visual editor at the position indicated in the dialogue. Links found in the edited content will be replaced by shortened urls when showing the content to the visitor. There can be only 1 parameter of this type and the use of <view>channel</view> is mandatory.
inserttype Displays a pulldown menu that the user can select one of these values from: "Append", "Prepend" or "Replace".
number Displays an input field into which the user can only input numeric characters.
string Displays an input field into which the user can enter text.
image Displays a field with a "Browse" button which the user uses to upload an image file.

<backend>

<widget>

The <widget> tag contains a path (relative to the XML definition file) to the JavaScript file that defines a Dojo widget. If you want to learn more about widgets, see the Insight Tutorial.

<plugin>
  ...
  <backend>
    ...
    <widget>widgets/PropertiesOverview.js</widget>
    ...
  </backend>
</plugin>

<backend>

<image>

The <image> tag contains a path (relative to the XML definition file) to a square preview image that BlueConic will display in e.g. the Gallery. The image is optional and will be scaled back to a 108x108 pixels box in the Gallery.

<plugin>
  ...
  <backend>
    ...
    <image>preview.png</image>
    ...
  </backend>
</plugin>

<backend>

<layer>

The <layer> tag contains a path (relative to the XML definition file) to a layer file. In development a plugin will typically consist of multiple JavaScript source files. The layer file of a plugin is one consolidated, production ready JavaScript file that consists of all combined and compressed JavaScript source files. 

<plugin>
  ...
  <backend>
    ...
    <layer>layer/insight_propertiesoverviewlayer.js</layer>
    ...
  </backend>
</plugin>

<backend>

<dimensions>

(Only relevant for plugins of type "insightwidget")
The <dimensions> tag contains the definition of the dimensions of the Insight. Insights are placed on a virtual grid that consists of 4 columns, and users can drag them around based on this grid. Three types of dimensions are supported:

Value Description
<width>1<width>
<height>1<height>
The 1x1 Insight is the smallest available size Insight. It spans one column and one row and you can have four of these next to each other on a single row.
<width>2<width>
<height>2<height>
The 2x2 Insight is a medium size Insight. It spans two columns and two rows. Only two of them fit per row.
<width>4<width> The full width Insight spans all four columns. There is no limit to its height because it defines its own row height.
<plugin>
  ...
  <type>insightwidget</type>
  ...
  <backend>
    ...
    <dimensions>
      <width>1</width>
      <height>1</height>
    </dimensions>
    ...
  </backend>
</plugin>

<backend>

<options>

(Only relevant for plugins of type "insightwidget")
The <options> tag may contains one or more of the following option tags:

Value Description
<exportable>true</exportable> Show an export icon in the Insight title bar. This requires the plugin developer to implement the function exportData. Set to false to show no export icon in the title bar.
<timebased>true</timebased> Indicates that the Insight is dependent of the date settings of the Dashboard. This will render a small clock icon on the top left of the Insight. Set to false to indicate the Insight is not dependent on the date settings of the Dashboard.
<title>true</title> Show the title of the widget. Set to false to avoid the title.
<plugin>
  ...
  <type>insightwidget</type>
  ...
  <backend>
    ...
    <options>
      <exportable>false</exportable>
      <timebased>false</timebased>
      <title>true</title>
    </options>
    ...
  </backend>
</plugin>

<profileproperties>

Defines the list of profile properties that the plugin listens for. BlueConic will look up profile properties by their id. If a profile property does not already exist, BlueConic will create the profile property automatically so the listener can start adding values for them.


<profileproperties>

<profileproperty>

This is the container tag within which a profile property is defined. These properties are used to configure the filter options for faceted search on visitors in the Segments page. For example:

<plugin>
  ...
  <type>listener<type>
  ...
  <!-- Profile properties to listen for -->
  <profileproperties>
    <profileproperty>
      ...
    </profileproperty>
    ...
  </profileproperties>
  ...
</plugin>

<profileproperty>

<id>

The identifier for the profile property. A valid identifier may consist of lowercase letters, numbers and underscores (_) and must be at least one character long. For example:

    <profileproperty>
      ...
      <id>engagement_interests</id>
      ...
    </profileproperty>

<profileproperty>

<name>

Specifies the name for the profile property. Use the <label> tag to specify language specific labels for the name in various locales (e.g. "en_US", "nl_NL"). For example:

    <profileproperty>
      ...
      <name>
        <label locale="en_US">Engagement Interests</label>
        <label locale="nl_NL">Engagement interesses</label>
      </name>
      ...
    </profileproperty>

<profileproperty>

<mergestrategy>

This tag is part of BlueConic's profile merge features. For complete information on the profile merge features in BlueConic, see Profile Merging.

Specifies the mergestrategy of a profile property. The possible values are:

Merge Strategy Description
BOTH The values of the property from both of the profiles are retained (default).
KEEP_CURRENT The value of the property in the current profile is retained.
SUM The values of the two profile properties are added together as integers: a single value is retained.
HIGHEST The highest value from the two profile properties is retained.
LOWEST The lowest value from the two profile properties is retained.
LATEST The most recently set value from the two profile properties is retained.
OLDEST The oldest or first stored value between the two profile properties is used. This is the default mergestrategy for the "Origin of profile" properties (level 1, level 2, and level 3), "First visit," and "Entry page" profile properties.

If no mergestrategy for a profile property is explicitly defined, then it is by default BOTH.


<profileproperty>

<permissionlevel>

This tag is part of BlueConic's privacy features. For complete information on the privacy features in BlueConic, see Privacy.

Specifies the minimum level a visitor must have before BlueConic is allowed to set/update the value of the property for that visitor. The possible permission levels are:

Permission Level Description
ANONYMOUS (Level 1) BlueConic will track anonymous profile properties.
PERSONAL (Level 2) BlueConic will track personal and anonymous profile properties.

If no permission level for a profile property is explicitly defined, then it is by default ANONYMOUS (Level 1). The implication of setting a permission level for a profile property is as follows:

Visitor Permission Level Profile Property Permission Level Profile Property Has Value?
Optimized (Level 1) ANONYMOUS Yes
Optimized (Level 1) PERSONAL No
Dynamic (Level 2) ANONYMOUS Yes
Dynamic (Level 2) PERSONAL Yes

<profileproperty>

<mergestrategy>

This tag is part of BlueConic's profile merge features. For complete information on the profile merge features in BlueConic, see Profile Merging.

Specifies the mergestrategy of a profile property. The possible values are:

Merge Strategy Description
BOTH The values of the property from both of the profiles are retained (default).
KEEP_CURRENT The value of the property in the current profile is retained.
SUM The values of the two profile properties are added together as integers: a single value is retained.
HIGHEST The highest value from the two profile properties is retained.
LOWEST The lowest value from the two profile properties is retained.
LATEST The most recently set value from the two profile properties is retained.

If no mergestrategy for a profile property is explicitly defined, then it is by default BOTH.


<profileproperty>

<filtertype>

Defines the segment filter type. The possible types are:

Filter Type Description
SELECT Displays values retrieved from all visitor profiles for the specified property. This allows the user to select one or more values for the profile property that define the segment. The possible values are those retrieved from the property in all visitor profiles. For example, if the profile property is "Entry Page" and the values found in all visitor profiles are "www.gxsoftware.com" and "www.blueconic.com", then these two values will appear in the select filter in the segment. All visitors whose profile property matches the value(s) selected belong to the segment.
RANGE Displays two numeric fields in the segment filter: "Min" (minimum) and "Max" (maximum) field. The user can either enter values in these two fields manually or they can use two dragging sliders to define the range. All visitor profiles that have a value for the property that falls within the specified range belong to the segment. For example, if the profile property is "Age" and the range is from "30" to "50", then all visitors who are between 30 and 50 years of age belong to the segment.
DATETIME Displays options for defining a date range:
  • Date in / Date not in — The user can use this dropdown to indicate if the date has to be in or not in the date range.
  • Period (enter start and end date) — The user can select a start and end date from a calendar in order to define a specific time period.
  • Last x days — The user can enter a value in a numeric field in order to define a specific number of days preceding the current date. If the user enters "0" (zero), then that means all values from today starting at midnight (0:00). If they enter "1", that means all values from yesterday and today. "2" would be all values from 2 days ago up to the present moment, and so forth.
All visitors whose profile property has a date that falls within the specified time period belong to the segment. For example, if the profile property is "Last Login" and the date range is "Date in last 30 days", then all visitors who have logged in within the last 30 days belong to the segment.

<profileproperty>

<unit>

Specifies the unit to use for this profile property. For example, the following XML results in the profile property being shown in the Segment Filters overlay. When "Visits" is selected, the user can then enter integers in the "Min" and "Max" range fields.

    <profileproperties>
      <unit>
        <id>visits</id>
        <name>
          <label locale="en_US">Visits</label>
          <label locale="nl_NL">Bezoeken</label>
        </name>
      </unit>
      <profileproperty>
        <id>visits</id>
        <labels>
          <label locale="en_US">Visits</label>
          <label locale="nl_NL">Bezoeken</label>
        </labels>
        <descriptions>
          <label locale="en_US">The total number of 
visits that the website visitor has made to your channels.
If after 30 minutes the website visitor subsequently visits your channels
again, then that will be counted as a new visit.
</label> <label locale="nl_NL">Het aantal bezoeken dat de
website bezoeker aan het universum heeft gebracht. Als een website bezoeker na 30
minuten weer actief wordt binnen het universum, dan wordt dat als een nieuw bezoek gezien.
</label> </descriptions> <unit>visits</unit> <filtertype>RANGE</filtertype> </profileproperty> </profileproperties>

 

<timeline>

<eventTypes>

Container for one or more event type definitions. The timeline of a profile is a flexible way to store event data coupled with the time the event occurred. In order for BlueConic to be able to work with events, the data structure of each event type needs to be defined first. By defining event types in the XML definition file, they become available in the BlueConic UI for users to select.

  <-- timeline event type definitions -->
  <timeline>
    <eventTypes>
      ...
    </eventTypes>
  </timeline>

<eventTypes>

<eventType>

Event type definition that describes the event and the properties it contains.

  <-- timeline event type definitions -->
  <timeline>
    <eventTypes>
      <-- First event type -->
      <eventType>
        ...
      </eventType>

      <-- Second event type -->
      <eventType>
        ...
      </eventType>

      ...
    </eventTypes>
  </timeline>

An event type definition contains an id, name, description, priority, retentionPeriod, and one or more properties. See additional details on Timeline event priority levels and retention periods.

<id> Required. A machine readable unique identifier string for the event type. A valid id may consist of lowercase letters, numbers and underscores (_) and must be at least one character long.
<name> A human readable name for the event type.
<description> A long form description the event type.
<priority> The priority of the event, which can be either “HIGH”, or “LOW”. The priority has impact on how long the event will be retained (see the “retentionPeriod” property). 
<retentionPeriod>

Number of days an event should be retained; after this period, the event will be deleted from the BlueConic database. This number has a maximum of 365 days. When omitted, LOW priority events will be deleted after 30 days, and HIGH priority will never be deleted.

<properties> One or more property definitions -- see below.
  <-- timeline event type definitions -->
  <timeline>
    <eventTypes>
      <-- Upsert event -->
      <eventType>
        <id>upsert_event</id>
        <name>Upsert event</name>
        <description>Event generated by the example 
connection upon an upsert.</description> <priority>HIGH</priority>
<retentionPeriod>100</retentionPeriod>
<properties> ... </properties> </eventType> </eventTypes> </timeline>

<properties>

<property>

Property type definition for an event type.

<id> Required. A machine-readable unique identifier string for the property type. A valid id can consist of lowercase letters, numbers, and underscores (_) and must be at least one character long.
<type> One of the following:
BOOLEAN The property may contain "true" or "false". Providing a value is optional.
DATETIME The property may contain a timestamp string. Providing a value is optional.
DECIMAL The property may contain a number with a decimal point (.). Providing a value is optional.
NUMBER The property may contain an integer value. Providing a value is optional.
TEXT The property may contain a text value. Providing a value is optional.
<properties>
...
</properties>
A nested data structure definition, following the same definitions as outlined above. You can have multiple nested structure definitions, however, nesting is only allowed one single layer deep.

Note: It is not possible to change the event type of a property and reupload the XML file after it has already been uploaded and is used by timeline events in your BlueConic environment.

  <-- timeline event type definitions -->
  <timeline>
    <eventTypes>
      <-- Upsert event -->
      <eventType>
        <id>upsert_event</id>
        <name>Upsert event</name>
        <description>Event generated by the example 
connection upon an upsert.</description> <properties> <property> <id>source<id> <type>TEXT<type> </property> <property> <id>amount<id> <type>DECIMAL<type> </property> <property> <id>account<id> <type> <-- Nested account properties --> <properties> <property> <id>crm_id<id> <type>TEXT<type> </property> <property> <id>name<id> <type>TEXT<type> </property> <property> <id>since<id> <type>DATETIME<type> </property> ... </properties> ... </type> </property> </properties> </eventType> </eventTypes> </timeline>

Implementing the JavaScript logic

Once you have defined the XML for the new interaction type as described in the topic XML definition file, you have to add the logic that defines the behavior of the interaction type. To do so, you need to implement a class that accesses the BlueConic JavaScript API.

Be sure to visit the Getting Started section, as it provides tutorials to get you started on building your own BlueConic plugins.

The script you have added to your web page will load the BlueConic client asynchronously. When the BlueConic client is loaded, a PAGEVIEW event is triggered. Based on this event all needed interactions are loaded.

Every interaction is a new instance based on its InteractionType. To instantiate a new interaction the init method of the InteractionType is called. The init method is called with two parameters: the blueConicClient and a context.

After all interactions are constructed the getPreloadProperties method is called for each interaction. When all preload profile properties are collected, the framework starts loading these properties. For performance reasons the BlueConic client loads all the properties for the interactions at once. Right after the preload profile properties are collected, the framework calls the getContent method for each interaction. Note that the framework does not wait until the preload profile properties are finished loading.

The onLoad method is called when:

  • The browser executes the Document Ready event.
  • All external libraries, like jQuery for example, are loaded.
  • The profile properties which should be preloaded are loaded.

Note: The main difference between the getContent method and the onLoad method is the moment in time when they are called and how this affects the way you must implement these methods. These methods are described below.


Every InteractionType implementation extends the default BlueConic InteractionType. The default InteractionType is part of BlueConic. The BlueConic JavaScript API contains methods that help you implement your own InteractionType. A basic implementation of an interaction type is shown below. This example displays a loading image on a specified position on your web page.

var InteractionTypeImpl = InteractionType.extend( {
  init : function(blueConicClient, context) {
    this.blueConicClient = blueConicClient;
    this.context = context;
  },

  getPreloadProperties : function() {
    // don't load any properties
    return [];
  },

  getContent : function() {
    return '<div><img src="/loading.gif"/></div>';
  },

  onLoad : function() {
  }
})

void init(blueConicClient, context)

The init method is the constructor for the InteractionType. Every time a new interaction is created based on your InteractionTypeImpl, this method is called to construct a new interaction object.

The init method has two parameters which you might need in your Interaction Type. We recommend that you create a reference to these parameters so that they are accessible throughout your InteractionTypeImpl.

The blueConicClient is a reference to the BlueConic JavaScript API.

The context is a reference to the interaction's context

See the explanation of the BlueConic API in this section for more information.

Example

init : function(blueConicClient, context) {
  this.blueConicClient = blueConicClient;
  this.context = context;
}

string[] getPreloadProperties()

This method is used to load one or more properties for the visitor's profile. In order to use a profile property you must first load this property. By default BlueConic does not load any of the profile's properties. Use the getPreloadProperties to declare for which profile properties BlueConic should preload the values. You should use preloading instead of profile.loadValues when possible. Every call to profile.loadValue results in a new HTTP Request while all preload properties (for all interactions) are retrieved together. This results in better performance because there is only one call to the server in order to retrieve all the properties you need. It is good practice to know which properties you are going to need in your InteractionTypeImpl and preload them. The loaded profile properties are added to the profile.

Example

getPreloadProperties: function() {
  var props = [];
  props.push('visits');
  props.push('visitclicks');
  props.push('keywords');
  return props;
}

You can access a preloaded property directly in the onLoad method:

onLoad: function() {
  var keywords =  profile.getValues('keywords');
}

string getContent()

When implemented this method must return an HTML fragment. BlueConic uses this HTML fragment to update the position configured for the interaction. This method is called by the framework right after the interactions are initialized. This method is useful for updating the content of the interaction's target HTML Element before this element becomes visible. Implementing getContent method has the following restrictions:

  • You cannot use external libraries.
  • You cannot access profile properties.
  • Your implementation must be synchronized.
  • You cannot access the DOM.

Because of these restrictions the framework can use the getContent method to update the web page at the earliest stage possible. Consider implementing this method when you need to display content on a web page and you cannot wait until the onLoad method is called.

Example

getContent: function() {
  var loadingDiv = '<div><img src="/loading.gif"/></div>';
  return loadingDiv;
}

void onLoad()

This is where you implement your interaction type's business logic. This method is called when an interaction based on your interaction type is executed.

Example

onLoad: function() {
  var params = this.context.getParameters();
  var content = params['content'][0];
  var position = this.context.getPosition();

  var element = document.getElementById(position);
  if (element) {
    element.innerHTML = content;
  }
}

Was this article helpful?
0 out of 0 found this helpful