This article explains how to develop your own custom BlueConic Plugin for Android. 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 or CTV 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 or CTV channel where they can configure a title and a text message for an Android AlertDialog. This text message will be displayed by your app.
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 find the Zip file as an attachment at the bottom of this article.
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="1.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>
<!-- CTV specific properties. -->
<ctv>
<plugins>
<plugin type="fireTV">com.blueconic.example.plugins.AlertPlugin</plugin>
<plugin type="androidTV">com.blueconic.example.plugins.AlertPlugin</plugin>
</plugins>
</ctv>
</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 that contains the fully qualified class name of our plugin implementation in Android. In this tutorial, we will only define an Android plugin, but you could also 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".
Inside the <ctv> tag, we can define a <plugin> tag which contains the fully qualified class name of our plugin implementation in Amazon Fire TV or Android TV.
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:
Log in to BlueConic.
Select Settings > Plugins from the BlueConic navigation bar.
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 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.Rclass 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 } }
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 SDK for Android to retrieve the values for the parameters named "title" and "content".
In your app, go to the main activity and add the following code in your onResume() method:
blueConicClient.createPageViewEvent("MAIN", activity)
Note: 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 dialogue interactions on the Where tab of BlueConic dialogues.
Creating a Dialogue for the Plugin
With our custom BlueConic plugin installed and our custom Android plugin integrated into our app, we can now create a Dialogue that makes use of it. Make sure your tenant contains a BlueConic Channel for your mobile or CTV app.
Select Dialogues from the BlueConic navigation bar.
Create a new Dialogue by clicking Add Dialogue.
Name the Dialogue "Hello World Android Dialogue".
Select the Who tab.
In the "Properties" widget, select your BlueConic plugin "Mobile dialog".
Select the channel of your mobile or CTV app.
Enter some text in the title and content fields.
Enable the Dialogue.
Save the Dialogue.
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 or CTV app.
From here, you can check the Getting Started page for more tutorials to dive deeper into the subject of BlueConic Plugins.