Tutorial: Mobile Plugin for Android

Difficulty: Intermediate

Welcome to the tutorial on how to develop your own custom BlueConic Mobile Plugin! This tutorial is meant for Android Developers. There is also a tutorial for iOS 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, which is used to configure the interaction in BlueConic.
  • An Android plugin, which is used to render the interaction on the device.

The result looks like:

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


Creating your BlueConic plugin

Your BlueConic plugin will allow a marketer to create a dialogue for a mobile channel where he can configure a title and a text message for an Android AlertDialog. 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:

mobilealert/
  +-- mobilealert.xml

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

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

XML definition file

The XML definition file lets BlueConic know what the plugin contains. Edit the XML definition file mobilealert.xml as follows:

<?xml version=&quot1.0" encoding="UTF-8"?>
<plugin>
    <id>mobilealert</id>
    <version>1.0.0</version>
    <type>action</type>
    <platformdependency>
        <min>37.0</min>
    </platformdependency>
    <name>
        <label locale="en_US">Mobile alert</label>
        <label locale="nl_NL">Mobiele alert</label>
    </name>
    <description>
        <label locale="en_US">Mobile alert</label>
        <label locale="nl_NL">Mobiele alert</label>
    </description>
    <!--  Backend specific properties. -->
    <backend>
        <parameters>
            <parameter>
                <id>title</id>
                <name>
                    <label locale="en_US">Title</label>
                    <label locale="nl_NL">Titel</label>
                </name>
                <descriptions>
                    <label locale="en_US">Title of the alert.</label>
                    <label locale="nl_NL">Titel van de alert.</label>
                </descriptions>
                <type>string</type>
            </parameter>
            <parameter>
                <id>content</id>
                <name>
                    <label locale="en_US">Content</label>
                    <label locale="nl_NL">Content</label>
                </name>
                <descriptions>
                    <label locale="en_US">Defines the alert content.</label>
                    <label locale="nl_NL">Content voor de alert</label>
                </descriptions>
                <type>textarea</type>
            </parameter>
        </parameters>
    </backend>
    <!-- Mobile specific properties. -->
    <mobile>
        <plugins>
            <plugin type="android">com.blueconic.example.plugins.AlertPlugin</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 <parameter> tags define an edit field for the title and a textarea for the dialog content.
  • Inside the <mobile> tag we can define a <plugin> tag which contains the fully qualified class name of our plugin implemantation in Android. In this tutorial we will only define an Android plugin, but you also could add a plugin tag for iOS. To indicate the type of the plugin, add the attribute type with the value "Android" to the plugin tag, e.g. type="Android"

Packaging the plugin

With the XML definition file in place, packaging the mobilealert 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 mobilealertandroid.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 Android native app plugin

Your Android native plugin will be interacting with your mobile app. It is important to make sure the full qualified path of the plugin matches the plugin tag com.blueconic.example.plugins.AlertPlugin of our example XML.

Implement your Android native plugin

Create the file AlertPlugin in the directory 'com/blueconic/example/plugins'. The structure should look like:

Copy the following content to the file:

package com.blueconic.example.plugins;

import java.util.List;
import java.util.Map;
import android.app.Activity;
import android.app.AlertDialog;

import com.blueconic.BlueConicClient;
import com.blueconic.BlueConicClient.InteractionContext;
import com.blueconic.BlueConicClient.Plugin;

/**
 * Sample AlertDialog plugin.
 */
public class AlertPlugin implements Plugin {
    private BlueConicClient myBlueConicClient;
    private InteractionContext myContext;

    /**
     * {@inheritDoc}
     */
    @Override
    public void init(BlueConicClient client, InteractionContext context) {
        myBlueConicClient = client;
        myContext = context;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void onLoad() {
        // Get the parameter values.
        final String title = getParameterValue("title");
        final String message = getParameterValue("content");

        if (message != null && !"".equals(message)) {
            // 1. Instantiate an AlertDialog.Builder with its constructor.
            Activity activity = myBlueConicClient.getActivity();

            final AlertDialog.Builder builder = new AlertDialog.Builder(activity);

            // 2. Set message and title on the dialog.
            builder.setMessage(message).setTitle(title);

            // 3. Show the dialog.
            if (activity.getWindow().getDecorView().getRootView().isShown()) {
                activity.runOnUiThread(new Runnable() {
                    public void run() {
                        builder.create().show();
                    }
                });
            }
        }
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public void onDestroy() {
    }

    private String getParameterValue(String id) {
        // Get all the parameters from the context.
        Map<String, List<String>> parameters = myContext.getParameters();
        List<String> values = parameters.get(id);
        if (values != null && !values.isEmpty()) {
            return values.get(0);
        }

        return null;
    }
}

To develop plugins it is required to implement the Plugin interface. The init method is called just after an instance of the plugin is created with two parameters:

  • BlueConicClient. Holds the BlueConicClient instance.
  • InteractionContext. Holds an instance of the InteractionContext.

After that the onLoad method is called in which you can implement your interaction.

The code uses the BlueConic Mobile SDK for Android to retrieve the values for the parameters named "title" and "content".

In your app go the main activity and add the following code in your onResume() method:

final Map<String, String> properties = new HashMap<>();
properties.put("location", "MAIN");
myBlueConicClient.createEvent("PAGEVIEW", properties);

You should add this code to every activity for which you want to show interactions. Set the location property so every activity can be identified uniquely. The location can be used to restrict interactions on the "Where"-tab of BlueConic.


Creating a Dialogue for the Plugin

With our custom BlueConic plugin installed and our custom Android 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.

  • Open the "Dialogues" tab in BlueConic.
  • Create a new Dialogue by clicking "Add Dialogue".
  • Name the Dialogue "Hello World Android Dialogue".
  • Select the "Interaction" tab.
  • In the "Properties" widget select your BlueConic plugin "Mobile dialog".
  • Select the channel of your mobile app.
  • Enter some text in the title and content field.
  • Enable the Dialogue.
  • 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 "AlertPlugin" plugin for Android, 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.