Tutorial 1: Hello World!

Difficulty: Beginner

Welcome to the tutorial on how to develop your own custom BlueConic plugin!
This tutorial is meant for beginners starting to program custom components that extend the scope of BlueConic. At the end of this tutorial you will have created your own custom "Hello World" plugin:


Introduction

BlueConic provides a lot of possibilities out of the box, allowing marketers to tap into visitor behavior, define dialogues and guide the visitor on his online journey. While the standard components are really versatile, there will always be cases where custom logic can achieve things beyond the scope of the standard components.

This is why BlueConic can be extended with plugins. These plugins can extend the backend (the BlueConic client) or frontend (the channel where BlueConic is active).

If you want to extend the scope of BlueConic, there are several ways to do this:

  • JavaScript Front-end API
    • Create custom interactions for dialogues
    • Listen to behavior and enrich a profile with values
    • Retrieve values from a profile, for example to prefill form values
  • REST API
    • Interact with BlueConic entities like profile properties, profiles, interactions, channels and domains
  • Mobile App SDKs
    • Listen to behavior and enrich a profile with values
    • Retrieve values from a profile, for example to prefill form values

For example, you could create an interaction that is close and personal to the customer by choosing between serving a message with a more subtle effect like highlighting, or serving the message more 'in your face' with a toaster, floor ad or lightbox.

The JavaScript API is used for interaction with the online visitors and for browser-based additions and extensions. It allows the developer to trigger events, retrieve profile properties or store profile properties. The API automatically takes care of server side persistent storage of the profile.

The Mobile App SDKs are used to retrieve profile properties or store profile properties from within a mobile app. The SDK automatically takes care of server side persistent storage.

The REST API is used for deep integration with BlueConic. It allows the developer to retrieve or programmatically control settings that could otherwise only be done via the BlueConic application itself.


Before you start

To start developing for BlueConic you will need:

The Chrome Extension will allow you to pretend websites are part of the universe on the BlueConic Sandbox. In effect, this allows you to use the BlueConic Sandbox with any website you add to its universe. When you visit the website you can see active Dialogues on it.


Creating your first plugin

Your first plugin will be a glorious one: it will allow a marketer to create a dialogue where he can pick a position on a channel and the text "Hello World!" will magically appear in that position.

To achieve this, we will use the JavaScript Front-end API and we will create the following directory structure:

helloworld/
  +-- helloworld.js
  +-- helloworld.xml

The directory "helloworld" contains the XML definition file and the JavaScript file that together form the plugin.

You can download the ZIP file with the source files here: helloworld.zip

XML definition file

An XML definition file lets BlueConic know what the plugin contains and what to plug in. Create the directory "helloworld" and edit the XML definition file "helloworld.xml" as follows:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
  <id>helloworld</id>
  <version>1.0.0</version>
  <type>action</type>
  <name>
    <label locale="en_US">Hello World</label>
    <label locale="nl_NL">Hallo Wereld</label>
  </name>

  <!-- frontend specific properties -->
  <frontend>
    <script>helloworld.js</script>
    <positiontype>position</positiontype>
  </frontend>

  <!-- backend specific properties -->
  <backend>
    <view>channel</view>
  </backend>
</plugin>

This XML definition file contains the following instructions:

  • The <id> is a unique identifier string so BlueConic can distinguish this plugin from others.
  • The <version> contains a version number. Once you have installed a plugin in BlueConic, you can only update to higher version numbers. So, if you install version "1.0.0" of this plugin, you can update to version "1.0.1" or version "2.27.0". But you cannot install version "1.0.0" again - unless you delete the existing plugin first.
  • The <type> tells BlueConic that this plugin contains an interaction that performs some visual action. See the XML definition file reference for an overview of all available types.
  • The <label> is a friendly name for the plugin. The locale indicates for which of the editing languages the friendly name is. Currently only "en_US" and "nl_NL" are supported.

The following options are specifically for the <frontend>, i.e. for the websites the plugin is activated for.

  • The <script> tag defines the JavaScript file that will be executed to implement the inner workings of the plugin, in this case "helloworld.js".
  • The <positiontype> tells BlueConic where the visual effects of this plugin will take place. The value "position" indicates a specific position should be picked for this particular interaction. See the XML definition file reference for an overview of all available positiontypes.

Finally, an option for the <backend>, in other words for the BlueConic client.

  • The <view> tells BlueConic that the backend should use the "channel" view (i.e. display the website inline) when editing the interaction.

The example above is very basic. For the full documentation on all possible tags and their values, see the XML definition file reference.

JavaScript file

With the plugin XML definition file in place, it is now time to create the JavaScript code that does the actual heavy lifting. Create the JavaScript file "helloworld.js" as follows:

InteractionTypeImpl = InteractionType.extend({

  // Called every time a new interaction of this type is created.
  init: function(blueConicClient, interactionContext) {
    // Store the parameters for later use.
    this.blueConicClient = blueConicClient;
    this.interactionContext = interactionContext;	
  },

  // Called right after the interactions are initialized.
  getContent: function() {
    return '<div>Hello World!</div>';
  },

  // Called when an interaction based on this type is executed.
  onLoad: function() {
    if (typeof this.interactionContext !== 'undefined' && this.interactionContext !== null) {
      // Get the DOM element indicated by the position of the dialogue. 
      var element = this.interactionContext.getDOMElement();

      if (element) {
        element.innerHTML = this.getContent();
      }
    }
  }
});

This JavaScript file contains a number of API functions that allow us to plug in to BlueConic and a bit of our own logic to do the actual work. The lines of code are explained in detail below.

var InteractionTypeImpl = InteractionType.extend({
Every interaction plugin extends the default BlueConic InteractionType. The function extend() takes an object with function definitions as argument. The defined functions will overrule the standard functions of the InteractionType. In the example the API function init() is being overruled and our own function helloWorld() is added.
init: function(blueConicClient, context) {
This line overrules the API function init(blueConicClient, interactionContext). The function is called every time a new interaction of this type is created. The function takes two parametersblueConicClient and interactionContext as arguments. You might need these later on, so we recommend that you create a reference to these parameters to have them accessible throughout your code.
getContent: function() {
This line overrules the API function getContent(). The function will be called at the earliest possible moment while loading a page. The content it returns will be placed at the Position defined in the Dialogue by the marketer.
onLoad: function() {
This line overrules the API function onLoad(). The function is called when the plugin is executed for an interaction of a Dialogue. Our plugin allows the marketer to create a Dialogue and pick a Position where the words "Hello World!" will appear. So we start out by testing if there is an interactionContext available. If there is a context, we use it to retrieve the DOM element indicated by the Position of the Dialogue using getDOMElement(). If that element is available, we finally change its inner HTML to the same content as returned by the getContent() function.

Although the helloworld.js above is fairly simple, it provides a good starting point for building your own plugin.

Packaging the plugin

With the XML definition file and the JavaScript file in place, packaging the HelloWorld plugin is now only a matter of creating a ZIP file with these two files in the top directory. The name of the zip file itself is not important, the file is only a vessel to get its contents to BlueConic.

You should now have a file "helloworld.zip" that contains the two files that we created above.


Installing the plugin

The packaged plugin can be added to BlueConic as follows:

  • Log in to BlueConic
  • Open "Settings > Plugins"
  • Click "Add/Update Plugin"
  • Select "Upload ZIP file"
  • Select the ZIP file
  • Click "Add Plugin"

 


Using the plugin

Before we proceed: are you ready to work with a BlueConic Sandbox? To be specific: have you installed and configured the BlueConic Chrome Extension for use with your BlueConic Sandbox environment and your website?

With our custom plugin installed, we can now create a Dialogue that makes use of it. Make sure your Universe contains a Channel for your test website and that the Channel has at least one Position.

  • Open the "Dialogues" tab in BlueConic.
  • Create a new Dialogue by clicking "Add Dialogue".
  • Name the Dialogue "Hello World Dialogue".
  • Select the "Interaction" tab.
  • In the "Properties" widget, select the Plugin "Hello World".
  • Select the channel of your test website.
  • Pick and Edit a position. Note: No need to edit anything because our plugin does not use the edited content at all. All we are interested in is the position, for now.
  • Save the Dialogue.
  • Click the "Open in Simulator" icon.

In the Simulator the Dialogue should light up and you should read "Hello World!" in the chosen position instead of the original content.

Congratulations on creating your first plugin!


Summary

In this tutorial you learned how to create a custom "Hello World" plugin, how to install it in BlueConic and how to use it in a Dialogue so you can view it on a test website.

From here you can check the Getting Started page for more tutorials to dive deeper into the subject of BlueConic Plugins.