Help Center

This article explains how to develop your own custom BlueConic Mobile Plugin. This walkthrough is meant for Android Developers. There is also a walkthrough 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.

The end result after following this article is that you 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 walkthrough. 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 your team to create a dialogue for a mobile channel where they 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 create the following directory structure:

mobilealert/
  +-- mobilealert.xml

The directory mobilealert only contains an 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 implementation 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 content 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:

1. Log in to BlueConic.
2. Select Settings > Plugins from the BlueConic navigation bar.
3. Click Add/Update Plugin.
4. Select "Upload Zip file".
5. Select the Zip file.
6. 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 this:

Copy the following content to the file:

package com.blueconic.example.plugins

import android.app.Activity
import android.app.AlertDialog
import com.blueconic.BlueConicClient
import com.blueconic.BlueConicClient.InteractionContext
import com.blueconic.testapp.R

class AlertPlugin : BlueConicClient.Plugin {
    private lateinit var blueConicClient: BlueConicClient
    private lateinit var context: InteractionContext

    override fun init(
       client: BlueConicClient, 
       interactionContext: InteractionContext
    ) {
        blueConicClient = client
        context = interactionContext
    }

    override fun onLoad() {
        // Get the parameter values.
        val title: String = getParameterValue("title")
        val message: String = getParameterValue("content")
        val activity: Activity = blueConicClient.activity
        val builder: AlertDialog.Builder = AlertDialog.Builder(activity)

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

        builder.setPositiveButton("Ok") { dialog , _ -
            val properties = mutableMapOf<string, string="String">().apply {
                put("interactionId", context.interactionId)
            }
            blueConicClient.createEvent("CLICK", properties)
            dialog.dismiss()
        }

        // 3. Show the dialog.
        if (activity.window.decorView.rootView.isShown) {
            activity.runOnUiThread {
                builder.create().show()
                val properties = mutableMapOf<string, string="String">().apply {
                    put("interactionId", context.interactionId)
                }
                blueConicClient.createEvent("VIEW", properties)
            }
        }
    }

    override fun onDestroy() {
    }

    private fun getParameterValue(id: String): String {
        // Get all the parameters from the context.
        val parameters: Map<string, list="List"> = context.parameters
        val values = parameters[id]
        return if (!values.isNullOrEmpty()) {
            values[0].ifEmpty { id }
        } else id
    }
}

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 blueConicClient;
    private InteractionContext context;

    /**
     * {@inheritDoc}
     */
    @Override
    public void init(BlueConicClient client, InteractionContext context) {
        blueConicClient = client;
        context = 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 = blueConicClient.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 = context.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:

val properties: MutableMap<String, String> = HashMap()
properties["location"] = "MAIN"
blueConicClient.createEvent("PAGEVIEW", properties)

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

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 tenant contains a BlueConic Channel for your mobile app.

1. Select Dialogues from the BlueConic navigation bar.
2. Create a new Dialogue by clicking Add Dialogue.
3. Name the Dialogue "Hello World Android Dialogue".
4. Select the Who tab.
5. In the "Properties" widget, select your BlueConic plugin "Mobile dialog".
6. Select the channel of your mobile app.
7. Enter some text in the title and content field.
8. Enable the Dialogue.
9. 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.