Help Center

XML Definition File for Plugins

In BlueConic, a plugin defines how the platform 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.

Each property within the XML definition file is of a specific parameter type (i.e., file, date, html, image, string, number). 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, but not all tags are relevant for every plugin type. The documentation below will highlight the details where needed.

This is a reference manual for XML definition files.

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 front end.
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 front end 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 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 the disable auto incrementation 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:

Empty or undefined (the tag is not present in the interaction type XML).
"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.
"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:

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.
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:

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.
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.
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.

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 <, < and &, 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>

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

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

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.

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. 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;
  }
}

Help Center

XML Definition File for Plugins

XML tags

<plugin>

<id>

<version>

<type>

<name>

<description>

<permissionlevel>

<profileindependent>

<manualviewcounting>

<status>

<frontend>

<frontend>

<script>

<frontend>

<positiontype>

<frontend>

<eventTypes>

<frontend>

<libraries>

Using an external library in your Plugin

<backend>

<backend>

<parameters>

<parameters>

<parameter>

<parameter>

<id>

<parameter>

<name>

<parameter>

<description>

<parameter>

<type>

<backend>

<image>

<backend>

<dimensions>

<backend>

<options>

<profileproperties>

<profileproperties>

<profileproperty>

<profileproperty>

<id>

<profileproperty>

<name>

<profileproperty>

<mergestrategy>

<profileproperty>

<permissionlevel>

<profileproperty>

<mergestrategy>

<profileproperty>

<filtertype>

<profileproperty>

<unit>

<timeline>

<eventTypes>

<eventTypes>

<eventType>

<properties>

<property>

Implementing the JavaScript logic

void init(blueConicClient, context)

Example

string[] getPreloadProperties()

Example

string getContent()

Example

void onLoad()

Example

Related articles