Tutorial: Mobile Plugin for iOS

Difficulty: Intermediate

Welcome to the tutorial on how to develop your own custom BlueConic Mobile Plugin! This tutorial is meant for iOS Developers, there is also a tutorial 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 prefill form values
  • Create custom interactions for dialogues

At the end of this tutorial you will 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 tutorial. 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 a marketer to create a Dialogue for a mobile channel where he 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 use the JavaScript back-end API and 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 plug in. 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 interaction.

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

  • 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>, inside this option we can define <plugin> tags. In this tutorial 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 which 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 contents 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:

  • Log in to BlueConic
  • Open "Settings > Plugins"
  • Click "Add/Update Plugin"
  • Select "Upload ZIP file"
  • Select the ZIP file
  • 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:

For Swift:

ProjectName
  >-- HelloWorldiOS.swift

For Objective C:

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:

For Swift:

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

For Objective-C:

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

For Swift:

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

For Objective-C:

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

Creating a Dialogue for the Plugin

With the our 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 Universe contains a Channel for your mobile app 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 iOS Dialogue".
  • Select the "Interaction" tab.
  • In the "Properties" widget select your BlueConic plugin "Hello World iOS".
  • Select the channel of your mobile app.
  • Select the positions in the "Interaction tab".
  • Enter some text in the text field.
  • Save the Dialogue.

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

Summary

In this tutorial 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 tutorials to dive deeper into the subject of BlueConic Plugins.