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.


The following XML tags are used to determine how an interaction type plugin appears in the Interaction tab 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>
</plugin>

<plugin>

The root tag <plugin> identifies a file as a 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 panel, 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>

<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>
  ...
  <manualviewcounting>true</manualviewcounting>
  ...
</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 the the XML definition file for each library. For example:

  <frontend>
    ...
    <libraries>
      <library>http://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.

Please note that 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 marketeer 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 in the Getting Started section.

<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 tofalse 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 facetted search on visitors in the Segments panel. All defined profile properties are included in the export of profiles in the Segments panel. 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.

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 calender 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 valules 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:

    <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 universe. If after 30 minutes the website
               visitor subsequently visits the universe 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>

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:


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

Please note that 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;
  }
}