Help Center

BlueConic SDK for Android

How to use the BlueConic SDK for Android to develop custom CDP applications for mobile apps The BlueConic SDK for Android makes it easy for developers to collect profile data from their apps. This section explains how to integrate BlueConic into Android apps. If you are looking for information on iOS apps, see the BlueConic SDK for iOS.

You can use the SDK to do the following:

Set and retrieve profile property values
Serve (custom) dialogues
Track user behavior using listeners

The BlueConic SDK for Android provides the basis for communication with BlueConic. It provides possibilities to develop your own interactions by creating mobile plugins. Developers can create their own mobile plugins and implement them in their Android app. For a tutorial on how to create an Android Plugin, refer to Tutorial: Mobile plugin for Android.

Before you begin

Before you start implementing the SDK, make sure you have the following:

The Android SDK (available for Windows, Mac OS X, and Linux)
An Android app that you can use to implement the BlueConic SDK for Android

Note: The use of the BlueConic Simulator is restricted to Debug mode only.

To test your mobile app, you will need access to a BlueConic environment. There are two options:

Are you working on behalf of a BlueConic Customer that has a BlueConic environment set up? Ask a representative of the BlueConic Customer to request a Sandbox environment in which you can test your mobile app.
Alternatively, request a free Pyxis environment yourself, and test your mobile app with that instance of BlueConic.

Getting started with the BlueConic SDK for Android

Before you start implementing the SDK, perform the following tasks:

Add the SDK dependency under your app build.gradle:

dependencies {    
    implementation 'com.blueconic:blueconic-android-lib:4.0.0'
}

Add permissions to the AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Add intent filters to the AndroidManifest.xml for connecting to the simulator:
Configure your appId at the android:scheme attribute in the code fragment below. For example "com.test.testapp".

<activity android:name=".MainActivity" android:label="@string/app_name">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
  </intent-filter>
  <!-- Filter added for connecting to the simulator through mail .-->
  <intent-filter>
    <action android:name="android.intent.action.SEND"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <data android:mimeType="text/plain"/>
  </intent-filter>
  <!-- Filter added for connecting to the simulator through a QR scan. -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="<Your appId>"/>
  </intent-filter>
</activity>

Add the configuration file for BlueConic:
Create a file named blueconic_configuration.xml in /res/values/:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="bc_server_url">[BlueConic server url]</string>
</resources>

Replace [BlueConic server url] with the protocol and hostname of the BlueConic server. For example "https://example.blueconic.net":

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="bc_server_url">https://example.blueconic.net</string>
</resources>

Optionally, enable debug mode:
Add the following node to the configuration file

<bool name="bc_debug">true</bool>

Note: Setting Debug to true will provide more logging and enable the use of the BlueConic Simulator.
Example configuration file:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="bc_server_url">https://example.blueconic.net</string>
    <bool name="bc_debug">true</bool>
</resources>

Warning: When you publish your apps, Debug should always be set False.

Using the BlueConic Android SDK

Create a page view event each time the user switches screens.
Typically, you want to create a BlueConic page view event each time the 'onResume' method of an Activity is called. When switching screens without actually switching Activities, you can still call the page view event. Just make sure that a unique screen name is passed in the call. The screen name is shown in the BlueConic Simulator, and it can be used to restrict dialogue interactions to specific screens.

Make sure that you provide the current Activity as argument when invoking "getInstance" on the BlueConicClientFactory. If no Activity is available, pass an empty Activity.

import android.app.Activity;
import android.os.Bundle;

import com.blueconic.BlueConicClient;
import com.blueconic.BlueConicClientFactory;

public class ExampleActivity extends Activity {
  private BlueConicClient myBlueConicClient;

  @Override
  public void onResume() {
    super.onResume();
    // Get the BlueConicClient instance.
    myBlueConicClient = BlueConicClientFactory.getInstance(this);
	
    // Set screen name to identify the activity.
    final Map<String, String> properties = new HashMap<>();
    properties.put("screenName", "Main/Section1");
    myBlueConicClient.createEvent("PAGEVIEW", properties);
  }
}

Cleaning up BlueConic interactions when the user navigates to another Activity:
Creating a page view event will dynamically load interactions (dialogues and listeners) in the app. These interactions will be active until the 'onPause' method of the Activity is called, at which point the interactions are destroyed. For apps where page views are called without switching Activities, it is necessary to explicitly call 'destroyPlugins' on the BlueConicClient when the user switches screens.
```
myBlueConicClient.destroyPlugins();
```

Retrieving and storing profile properties:
The BlueConic SDK for Android enables you to set and retrieve profile property values for a BlueConic profile. These methods can be used anywhere in the app. The following example counts the number of times a specific activity is opened and stores this number in the BlueConic profile:

import android.app.Activity;
import android.os.Bundle;

import com.blueconic.BlueConicClient;
import com.blueconic.BlueConicClientFactory;

public class ExampleActivity extends Activity {
  // Id of the property to store the number of activities in.
  private final static String PROPERTY_ID = "activityviews";
  private BlueConicClient myBlueConicClient;

  @Override
  public void onResume() {
    super.onResume();

    // Get an instance of the BlueConicClient.
    myBlueConicClient = BlueConicClientFactory.getInstance(this);

    // Set screen name to identify the activity.
    final Map<string, string="String"> properties = new HashMap<>();
    properties.put("screenName", "ExampleActivity");

    /**  
     * Invoke PAGEVIEW in order to initialise the SDK, optionally pass a callback to retrieve 
     * values from the profile. Callback will be invoked after init is finished. 
    */
    myBlueConicClient.createEvent("PAGEVIEW", properties) {
      final String profileValue = myBlueConicClient.getProfileValue(PROPERTY_ID);

      int newValue = 1;
      if (profileValue != null && !"".equals(profileValue)) {
          try {
            // Increase the current value in the profile.
            newValue = Integer.parseInt(profileValue) + 1;
          } catch (NumberFormatException e) {
            // Start counting at 1.
          }
      }
      // Set the new value in the profile.
      myBlueConicClient.setProfileValue(PROPERTY_ID, String.valueOf(newValue));
    }
  }

  @Override
  public void onPause() {
    super.onPause();
	
    // This call is only required when supporting Android API versions below 14.
    myBlueConicClient.destroyPlugins();
  }
}

Register events:
Calls to register an event can be done in the onLoad of a custom developed Plugin. The code fragment shows how to trigger a click event. Possible events are: "CLICK", "VIEW", and "CONVERSION".

public class ExamplePlugin implements Plugin {
  private BlueConicClient myBlueConicClient;
  private BlueConicClient.InteractionContext myContext;

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

  @Override
  public void onLoad() {
    // Returns the View on the position that is configured at the interaction.
    final View component = myContext.getView();
    final Button button = (Button) component;
		
    button.setOnClickListener(new View.OnClickListener() {
      public void onClick(View v) {
        final Map<String, String> properties = new HashMap<>();
        properties.put("interactionId", myContext.getInteractionId());
        myBlueConicClient.createEvent("CLICK", properties);
     } 
   });
  }
  
  @Override
  public void onDestroy() {
  }
}

For more information, be sure to check out the following:

Configuring BlueConic

This section describes how to add the channel for your mobile application as well as how to define your custom profile properties so that you can use them in BlueConic segments.

Add your mobile channel

Before you can start measuring activity in your mobile applications and maintain values in visitor profile properties, the channel for your mobile application must be added to a domain in your BlueConic tenant. The very first time that you start your application, BlueConic will detect it. It must then be added as a channel of the type "Mobile App" in a domain.

Custom profile properties

If you want your mobile application to be able to add custom properties to visitor profiles and use them in BlueConic segments, those custom profile properties must be added to your plugin. For complete information on writing a custom plugin, see Plugin Types. For information about adding custom profile properties, see profile properties.

BlueConic SDK for Android Release Notes

To see a list of updates and bug fixes for the SDK, see the BlueConic SDK for Android Release Notes.

BlueConicClientFactory

getInstance
```
public static BlueConicClient getInstance(android.app.Activity context)
```
Get an instance of the BlueConic client.

Parameters:

context - The application context.

Returns:

The BlueConic client instance.

Throws:

NullPointerException - when the context is null.

getInstance
```
public static BlueConicClient getInstance(android.app.Application application)
```
Get an instance of the BlueConic client.

Parameters:

application - The application.

Returns:

The BlueConic client instance.

Throws:

NullPointerException - when the context is null.

BlueConicClient

addProfileValue
```
void addProfileValue(String property,
                   String value)
```
Adds a single property value to the profile. If there are already values for a property the new value will be added. Values for a property need to be unique; passing the same value multiple times will have no effect.
```
 // Add "tennis" to the values for the "hobbies" profile property
 myBlueConicClient.addProfileValue("hobbies", "tennis");
 
```
Parameters:

property - The profile property to add the values for.

value - The property value to add to the profile.

addProfileValues
```
void addProfileValues(String property,
                    Collection<String> values)
```
Adds property values to the profile. The values from the collection are added to the profile. If there are already values for a property the new values will be added. Values for a property need to be unique; passing the same values multiple times will have no effect.
```
 // Add "tennis" and "soccer" to the values for the "hobbies" profile property
 myBlueConicClient.addProfileValues("hobbies", 
                               Arrays.asList(new String[]{"tennis", "soccer"}));
 
```
Parameters:

property - The profile property to add the values for.

values - The property values to add to the profile.

createEvent
```
void createEvent(String eventType,
               Map<String,String> properties)
```
Registers an event of the specified type with the given properties.

For a "PAGEVIEW" event a screen name can be passed, so interactions can be restricted on the Dialogue Where tab in BlueConic. For example:
```
 properties.put("screenName", "Main/Test");
 myBlueConicClient.createEvent("PAGEVIEW", properties);
 
```
For a "VIEW", "CLICK", or "CONVERSION" event, an interactionId should be passed to register the event for. For example:
```
 properties.put("interactionId", myContext.getInteractionId());
 myBlueConicClient.createEvent("CLICK", properties);
 
```
Parameters:

eventType - The event type. e.g. {"PAGEVIEW", "VIEW", "CLICK", "CONVERSION"}

properties - A map with properties for the event.

destroyPlugins
```
void destroyPlugins()
```
Triggers a call to onDestroy on every plugin that was retrieved at the last pageview.
Note: When it is needed to support Android API versions before API 14, this method must be called in the onPause of every Activity.

Parameters:

activity - The activity the plugins were loaded for.

getProfileId

String getProfileId()

Returns the ID of the BlueConic Profile

 // Returns the ID of the BlueConic Profile"
 final String profileId = myBlueConicClient.getProfileId();

Returns:: The ID of the BlueConic profile.

getActivity
```
android.app.Activity getActivity()
```
Returns the current activity.

Returns:

The current activity.

getProfileValue

String getProfileValue(String property)

Returns the first value for a given profile property.

 // Returns the first value in the list of hobbies, e.g. "tennis"
 final String oneHobby = myBlueConicClient.getProfileValue("hobbies");

Parameters:: property - The profile property to get the values for.
Returns:: The first value.

getProfileValues

Collection<String> getProfileValues(String property)

Returns the values for a given profile property.

 // Returns all the values in the list of hobbies, e.g. {"tennis", "soccer"}
 final Collection<String> allHobbies = 
                          myBlueConicClient.getProfileValues("hobbies");

Parameters:: property - The profile property to get the values for.
Returns:: A collection containing the values.

getScreenName

String getScreenName()

Returns the screenName either set in the createEvent or the Activity's title. For example:

Map<String, String> properties = new HashMap<>();
properties.put("screenName", "MAIN/Activity1");
String screenName = myBlueConicClient.getScreenName();

Returns:: The screen name.

getView
```
android.view.View getView(String expression)
```
Returns a view component based on the given identifier or null is no match is found.

Parameters:

expression - The identifier, e.g. '#button1".

Returns:

The view or null.

setLocale
```
void setLocale(String locale)
```
Setter for the locale to get the parameters for. By default, the default locale configured in BlueConic is used. Note: The only valid locales currently are 'en_US' and 'nl_NL'.

Parameters:

locale - The locale, e.g. 'en_US'.

setProfileValue
```
void setProfileValue(String property, String value)
```
Sets a value on the profile. Passing a property that was already set with values will cause for the old values to be removed.
```
 // Set "tennis" as the value for the "hobbies" profile property.
 myBlueConicClient.setProfileValue("hobbies", "tennis");
 
```
Parameters:

property - The profile property to add the value for.

value - The profile value to store.

setProfileValues

void setProfileValues(String property, Collection<String> values)

Sets values on the profile. Passing a property that was already set with values will cause for the old values to be removed.

 // Set "tennis" and "soccer" as the values for the "hobbies" profile property
 myBlueConicClient.setProfileValues("hobbies", 
                               Arrays.asList(new String[]{"tennis", "soccer"}));

Parameters:: property - The profile property to add the values for.; values - The profile values to store.

incrementProfileValue
```
void incrementProfileValue(String property, String value)
```
Increments a single property value to the profile. If there are already values for a property, the new value will be the sum of all values.
```
 // Increment "1" to the values for the "hobbies" profile property
myBlueConicClient.incrementProfileValue("hobbies", "1");
 
```
Parameters:

property - The profile property to increment the values for.

value - The property value to increment to the profile.

BlueConicClient.InteractionContext

getInteractionId
```
String getInteractionId()
```
Returns the interaction id.

Returns:

the interaction id.

getParameters
```
Map<String,List<String>> getParameters()
```
Returns the interaction parameters in a map.

Returns:

the parameters.

getConnection
```
BlueConicClient.Connection getConnection(String id)
```
Returns a connected connection.

Parameters:

id - The UUID of the connection.

Returns:

The connection when found, otherwise null.

getView
```
android.view.View getView()
```
Returns a view component for the interaction.

Returns:

The view component matching the selector or the position of the interaction or null if no match is found.

getPositionIdentifier
```
String getPositionIdentifier()
```
Returns the 'selector' of the position.

Returns:

The selector, e.g. "#position_1"

Using getPosition Identifier to define a position

To define a position in your app, follow the instructions for defining a new position. You need to define a position with selectors using elements. Then you use getPositionIdentifier to retrieve the positions. See the Android developer documentation to learn about layout resources.

BlueConicClient.Plugin

init
```
void init(BlueConicClient client, BlueConicClient.InteractionContext context)
```
"Constructor" method for plugins.

Parameters:

client - The BlueConic client

context - The interaction context

onLoad
```
void onLoad()
```
Invoked when the interaction should execute.

onDestroy
```
void onDestroy()
```
Invoked when the interaction should close.

BlueConicClient.Connection

getId
```
String getId()
```
Returns the connection id.

Returns:

The connection id.

getParameters
```
Map<String,List<String>> getParameters()
```
Returns the parameters for the connection. The parameters are returned as a map from parameter ids to the values.

Returns:

The parameters.