Help Center

This article explains how to develop your own custom BlueConic Mobile Plugin. This tutorial is meant for iOS Developers; there is also a walkthrough for Android Developers.

BlueConic provides a lot of possibilities for integration with your mobile native app:

• Listen to behavior and enrich a profile with values.
• Retrieve values from a profile, for example to pre-fill form values.
• Create custom interactions for dialogues.

The end result after following this article is that you have created two plugins:

• A BlueConic plugin to communicate with an iOS native app.
• An iOS plugin to communicate with BlueConic.

The creation of the iOS native app itself is beyond the scope of this walkthrough. For more information on working with BlueConic from an iOS native app, see the BlueConic SDK for iOS.

Creating your BlueConic plugin

Your BlueConic plugin will allow your team to create a Dialogue for a mobile channel where they can configure a text message. This text message will be picked up and displayed by your app.

If you are not yet familiar with the basics of creating a BlueConic plugin, have a look at Tutorial 1: Hello World!

To create the BlueConic plugin, we will create the following directory structure:

helloworldios/
  +-- helloworldios.xml

The directory "helloworldios" contains only a XML definition file. By itself it is the entire plugin.

You can download the Zip file with the source file here: helloworldios.zip

XML definition file

The XML definition file lets BlueConic know what the plugin contains and what to input. Create the directory "helloworldios" with an XML definition file, and and edit the XML definition file helloworldios.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
  ...
  <!-- frontend specific properties -->
  <frontend>
    <positiontype>position</positiontype>
  </frontend>

  <!-- backend specific properties -->
  <backend>
    <parameters>
        <parameter>
          <id>text</id>
          <name>
            <label locale="en_US">Text</label>
            <label locale="nl_NL">Tekst</label>
          </name>
          <type>textarea</type>
        </parameter>
     </parameters>
  </backend>

  <!-- mobile specific properties -->
  <mobile>
    <plugins>
      <plugin type="iOS">ProjectName.HelloWorldiOS</plugin>
    </plugins>
  </mobile>
</plugin>

The example above only shows the XML tags relevant for our BlueConic plugin. For the full documentation on all possible tags and their values, see the XML definition file reference. Our XML definition file contains the following instructions:

The following option is specifically for the <frontend>, i.e. for the mobile channel the plugin is activated for:

• The <positiontype> tells BlueConic where the visual effects of this plugin will take place. The value position indicates a specific position on the mobile channel should be picked for this particular dialogue interaction.

An option for the <backend>, or the BlueConic client, is as follows:

• The <parameter> creates a textarea at the dialogue, so that you can change the shown text in your mobile app.

And finally, the option for <mobile>, and inside this option we can define <plugin> tags. In this walkthrough we will only define an iOS plugin, but you also could add a plugin tag for Android. To indicate the type of the plugin, add the attribute type="iOS". The value ProjectName should be equal to the Project name that you use to define your app plugin. This could be an external library that you include to your mobile app, or this could be your mobile app itself. In our example, the value HelloWorldiOS is the name of our Class name.

Packaging the plugin

With the XML definition file in place, packaging the HelloWorldiOS BlueConic plugin is now only a matter of creating a Zip file with the single file in the top directory. The name of the Zip file itself is not important; the Zip file is only a vessel to get its content to BlueConic.

You should now have a file helloworldios.zip that contains the single file that we created above.

Installing the BlueConic plugin

The packaged plugin can be uploaded to BlueConic:

1. Log in to BlueConic.
2. Select Settings > Plugins from the BlueConic navigation bar.
3. Click Add plugin.
4. Select Upload ZIP file.
5. Select the ZIP file.
6. Click Add plugin.

Creating your iOS native app plugin

Your iOS native app plugin will be interacting with your mobile app. It is important to make sure that your project name and class name are equal to the project name and class name defined in your XML file. To match the plugin ProjectName.HelloWorldiOS of our example XML:

• The name of your project should be ProjectName.
• The name of your plugin class should be HelloWorldiOS.

As a result, your Project navigator should display the following structure:

ProjectName
  >-- HelloWorldiOS.swift

ProjectName
  >-- HelloWorldiOS.h
  >-- HelloWorldiOS.m

Note: Above we only mention files relevant for our example. There should be more files in your project structure.

Implement your iOS native app plugin file

After the file is created, it is time to define your plugin as follows:

import Foundation
import BlueConicClient

public class HelloWorldiOS: Plugin {
    private var _client: BlueConicClient?
    private var _context: InteractionContext?

    public override convenience init(client: BlueConicClient, 
        context: InteractionContext) {
        self.init()
        self._client = client
        self._context = context
    }

    public override func onLoad() {
        println("[BlueConicExamplePlugins] Alert.onLoad")
        let alert =  UIAlertView(title: "Hello World!", 
        message: self.getValueFromParameters("text"), 
        delegate: nil, cancelButtonTitle: nil, otherButtonTitles: "OK")
        alert.show()
    }

    private func getValueFromParameters(key: String) -> String? {
        if let parameters: Dictionary<String, [String]> = 
            self._context?.getParameters(),
            let values = parameters[key],  values.count > 0 && values[0] != "" {
            return values[0]

        }
        return nil
    }
}

// HelloWorldiOS.h
#import <BlueConicClient/BlueConicClient-Swift.h>
#import <BlueConicClient/BlueConicPlugin.h>

@interface HelloWorldiOS: Plugin

- (instancetype) initWithClient: (BlueConicClient *)client 
context:(InteractionContext *)context;
- (void) onLoad;

@end

// HelloWorldiOS.m

#import "HelloWorldiOS.h"

@interface HelloWorldiOS ()

@property BlueConicClient* _client;
@property InteractionContext* _context;

@end

@implementation HelloWorldiOS

- (instancetype) initWithClient: (BlueConicClient *)client 
context:(InteractionContext *)context {
    self = [super init];
    if (self) {
        self._client = client;
        self._context = context;
    }
    return self;
}

- (void) onLoad {
    UIAlertView *alert = [[UIAlertView alloc] 
initWithTitle:@"Hello World" message:[self getValueFromParameters:@"text"] 
delegate:nil cancelButtonTitle:nil otherButtonTitles:@"ok", nil];
    [alert show];
}

- (NSString *) getValueFromParameters: (NSString *)key {
    NSDictionary* parameters = [self._context getParameters];
    NSArray* values = [parameters objectForKey:key];
    if (values != nil && values.count > 0) {
        return values[0];
    }
    return @"";
}
@end

The code uses the BlueConic SDK for iOS to retrieve the value for a parameter named "text" and display its value as a message.

In your app go the ViewController and implement the following method call in your viewDidLoad function:

let client = BlueConicClient.getInstance(self)
client.createEvent("PAGEVIEW", properties: ["location": "Main/HomeTab"])

lueConicClient* client = [BlueConicClient getInstance:self];
[client createEvent:@"PAGEVIEW": properties:@{@"location": @"Main/HomeTab"}];

Creating a Dialogue for the Plugin

With the custom BlueConic plugin installed and our custom iOS plugin integrated in our app, we can now create a Dialogue that makes use of it. Make sure your tenant contains a Channel for your mobile app and that the Channel has at least one Position.

1. Select Dialogues from the navigation bar in BlueConic.
2. Create a new Dialogue by clicking Add dialogue.
3. Name the Dialogue "Hello World iOS Dialogue".
4. Select the What tab.
5. In the Properties widget select your BlueConic plugin "Hello World iOS".
6. Select the channel of your mobile app.
7. Select the positions in the What tab.
8. Enter some text in the text field.
9. Save the Dialogue.

Now you can test your Dialogue in your mobile app using the Simulator.

Summary

In this walkthrough you learned how to create a custom "Hello World" plugin for iOS, how to install it in BlueConic, and how to use it in a Dialogue so you can view it on a mobile app.

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