Help Center

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:

hello-world-screen-2.png


Introduction

BlueConic provides a lot of possibilities out of the box, allowing marketers to tap into visitor behavior, define dialogues to personalize content, and guide customers and visitors on their online journeys. You can employ custom code to achieve things beyond the scope of the standard components.

You can extend BlueConic via custom plugins. These plugins can extend the backend (the BlueConic client) or frontend (the channel where BlueConic is active).

There are several ways to extend the scope of BlueConic:

  • 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 pre-fill form values
  • REST API
    • Interact with BlueConic entities such as profile properties, profiles, interactions, channels, and domains
  • Mobile App SDKs for Android and iOS
    • 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 dialogue.

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 allows you to use the BlueConic Sandbox with any website you add to its BlueConic channel. 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 marketers to create a dialogue where they 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:

  1. Log in to BlueConic.
  2. Open Settings > Plugins.
  3. Click Add/Update Plugin.
  4. Select "Upload ZIP file".
  5. Select the ZIP file.
  6. Click Add Plugin.

 


Using the plugin

Before we proceed: Are you ready to work with a BlueConic Sandbox? Specifically, 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 BlueConic dialogue that makes use of it. Make sure you have added a channel for your test website and that the channel has at least one position.

  1. Choose Dialogues from the BlueConic navigation bar.
  2. Create a new Dialogue by clicking Add Dialogue.
  3. Name the Dialogue "Hello World Dialogue".
  4. Select the What tab.
  5. In the "Properties" widget, select the Plugin "Hello World".
  6. Select the channel of your test website.
  7. 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.
  8. Save the Dialogue.
  9. 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.

 

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