How do I enable my App for BlueConic?

What: The BlueConic SDK for iOS or Android makes it easy for developers to collect profile data from their apps, and/or customize their apps based on known and anonymous user segmentation and profile data.

About BlueConic: BlueConic is a Customer Data Platform that harnesses the data required to power the recognition of an individual at each interaction, and then synchronizes their intent across the marketing ecosystem. Click here to learn more.

Why: Message known and anonymous users with products and offers that are relevant to them based on their real-time interactions with your website. Acquire more customers with consistent messaging from your digital campaigns, save cart abandoners with right-time relevancy, and increase lifetime value with recommendations and communications based on behavioral data.

How: This document will describe how to enable your mobile App for use with BlueConic. This is a technical document meant for mobile App (iOS or Android) developers, and it contains code examples to help you modify your own App.

BlueConic can work with different types of channels, for example websites, mobile apps or other systems. To gather data from any channel, the channel needs to communicate with the BlueConic server using the Javascript Front-end API or the REST API

To enable a website, this means the BlueConic script needs to be placed on its pages. The script will take care of all communication with the BlueConic server.

Your mobile app might use a web view to display the contents of a website, but typically it does not. The script can not be added and another approach is needed to enable your app. If you are developing for Android or iOS, SDKs are available for this purpose.

 

What can a BlueConic enabled App do?

Before we delve into technical details: what exactly can a BlueConic enabled App do?

For starters, BlueConic can listen to the App by monitoring page views and visitor behavior (e.g. clicking buttons or entering values) in the App. BlueConic supports mobile apps from the following listeners:

The App can also send events to signal BlueConic that something specific happened, e.g. the user clicked a button, signed up for a newsletter or watched a video.

The information in BlueConic helps a marketer to know the individual and drive better outcomes.

For example, marketers can create lightbox dialogues in BlueConic to conditionally show lightbox content in the App. Custom dialogues for apps can be created by using the BlueConic SDK for iOS or Android to create a custom plugin. The creation of a custom plugin is described in Tutorial: Mobile Plugin for iOS and Tutorial: Mobile Plugin for Android.

Before you start

Before you start changing code in your app, start in BlueConic by setting up the new mobile channel for your App, or ask the marketer to do it for you. BlueConic will not work with your Mobile App unless it has been set up as a channel.

Enabling basic operations

To enable your App for use with BlueConic, you have to add the BlueConic SDK (iOS, Android) to your App as described under Getting Started of the SDK. Adding the SDK will automatically enable in-App page view recording for the standard BlueConic listeners. The PAGEVIEW event is central to making listeners work, as it acts as a central hub to register events and listeners. Example 1 shows how to implement the PAGEVIEW event.

Make sure you always implement the PAGEVIEW event for your App!

To enable more mobile features some additional actions need to be taken, as explained in Enabling advanced operations.

When your App has been enabled for basic operations, the listeners of the BlueConic SDK work similar to how they work on the web. Configuring a listener in BlueConic works the same way for apps as for web. There are differences between web and app that you need to be aware of, though. For example: a value from a web page is often retrieved using a jQuery selector. Because of the architectural differences between web and app, jQuery selectors will not work in your App. Instead, you will have to define named positions for BlueConic to locate objects on your App's screen.

To illustrate this, below are a couple of examples.

Example 1: Defining a value from URL / Mobile Screen by regular expression

A web page has a URL to determine the location in a website, however an App does not have something similar. Instead, the screenName property sent via a PAGEVIEW event is used by BlueConic to identify the location in the App.

  • iOS (Swift):

    let myBlueConicClient = BlueConicClient.getInstance(self)
    
    // Set screen name to identify the ViewController.
    myBlueConicClient.createEvent("PAGEVIEW", properties: ["screenName": "Main/Section1"])
    
  • iOS (Objective-C):

    BlueConicClient *myBlueConicClient = [BlueConicClient getInstance:self];
    
    // Set screen name to identify the ViewController.
    [myBlueConicClient createEvent:@"PAGEVIEW" properties:@{@"screenName": @"Main/Section1"}];
    
  • Android:

    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);
    

Now the marketer can retrieve the screen name "Main/Section1" as a value like so (using the regular expression (.*)):

Or the marketer can add values when the Mobile Screen name contains certain words. Create a rule of type "URL / Mobile Screen" and configure the Mobile Screen name to listen to:

Example 2: Defining a value from page by custom selector

In this example we assume some screens of our mobile App contain a chapter number that we would like to pick up in BlueConic. To do this, create a new Behavior Listener in BlueConic and and add a content rule. Define the value as "Value from Page (custom selector)" with a human readable name, e.g. "Chapter".

As selector, use one of the following:

  • iOS: use the id of a component defined as @IBOutlet variable and prepend it with a # sign. E.g. use #chapterNumber in BlueConic when your App code defines a "chapterNumber" outlet:

    // Swift:
    @IBOutlet weak var chapterNumber: UILabel!
    
    // Objective-C:
    @property (weak, nonatomic) IBOutlet UILabel *chapterNumber;
  • Android: use the id of a resource, replacing @+id/ or @id/ with a # sign. Only textview or button components will be recognized. E.g. use #chapterNumber in BlueConic when your App code defines a textview component like this:

    <TextView
        android:id="@+id/chapterNumber"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="1" />

This allows the marketer to define values:

It allows the marketer to define a custom area that should contain words:

 

Example 3: Mobile screen

The marketer can listen for appearance of words on the mobile screen:

When the mobile screen is refreshed BlueConic will retrieve the components present on the page and scan their values for a match. Only certain components are taken into account:

  • iOS: UILabel and UIButton components
  • Android: textview and button components

 

Enabling advanced operations

In the previous section your App was enabled for basic operations. This means the marketer can now listen to the basics of your App, e.g. measure views, determine if terms appear on the screen, determine if a specific screen was visited, display a lightbox, etc.

But what if you want to pass on a value to BlueConic when a specific action happens in your App?

Events to the rescue!

The BlueConic SDK allows you to send events to BlueConic. This allows you to keep BlueConic informed of what is happening in your App, even when it happens outside the scope of the basic operations.

Events are sent using the BlueConicEventManager's publish() function (iOS, Android). Several kinds of events can be published:

ClickEvent
This event signals BlueConic that a component with a specific id has been clicked in your App.
UpdateContentEvent
This event signals BlueConic that the content of a component with a specific id has updated its content and also passes on the updated content.
UpdateValuesEvent
This event signals BlueConic that a component with a specific id has received an updated list of values and passes on these updated values.
FormSubmitEvent
This event signals BlueConic that the form with a specific id has been submitted.
AdvancedEvent
This allows you to send a custom event to BlueConic with its own specific name and a list of values.

 

Below are some examples to illustrate the use of events.

Example 4: Click

BlueConic allows the marketer to indicate the button that defines the click area in a Click / Tap rule as follows:

To facilitate the marketer, add the following code to your App:

  • iOS (Swift):

    import BlueConicClient
    
    // Define click event for selector "#nextButton"
    let event = ClickEvent(selector: "#nextButton")
    
    // Use EventManager to publish the event to BlueConic
    let eventManager:EventManager = BlueConicClient.EventFactory.getInstance()
    eventManager.publish(event)
    
  • iOS (Objective-C):

    // Define click event for selector "#nextButton"
    ClickEvent *event = [[ClickEvent alloc] initWithSelector:@"#nextButton"];
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
    [eventManager publish:event];
  • Android:

    import com.blueconic.plugin.events.BlueConicEventFactory;
    import com.blueconic.plugin.events.BlueConicEventManager;
    import com.blueconic.plugin.events.ClickEvent;
    
    // Define click event for selector "#nextButton"
    ClickEvent event = new ClickEvent("#nextButton");
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager eventManager = BlueConicEventFactory.getInstance();
    eventManager.publish(event);

 

Do note that by publishing the 'Click' event, you only let BlueConic know that the user clicked. You can't send a value along with the 'Click' event, which should be pushed into the profile when the user clicks. You can let the listener read a value from the app screen though when the 'Click' event is published, see Example 2 on this page on how to do this. 

Example 5: Updating content

BlueConic allows the marketer to detect words on the mobile screen:

The BlueConic SDK will scan the mobile screen upon loading the view for the first time. But what if you change the contents of the screen without reloading the view?

To facilitate the marketer, publish an UpdateContentEvent. Add the following code to your App:

  • iOS (Swift):

    import BlueConicClient
    
    // FIXME: Replace with the real new content
    let newContent = "..."
    
    // Define update content event for UILabel or UIButton component "body"
    let event = UpdateContentEvent(selector: "#body", content: newContent)
    
    // Use EventManager to publish the event to BlueConic
    let eventManager:EventManager = BlueConicClient.EventFactory.getInstance()
    eventManager.publish(event)
    
  • iOS (Objective-C):

    // FIXME: Replace with the real new content
    NSString *newContent = @"...";
    
    // Define update content event for UILabel or UIButton component "body"
    UpdateContentEvent *event = [[UpdateContentEvent alloc] initWithSelector:@"#body" content:newContent];
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
    [eventManager publish:event];
  • Android:

    import com.blueconic.plugin.events.BlueConicEventFactory;
    import com.blueconic.plugin.events.BlueConicEventManager;
    import com.blueconic.plugin.events.UpdateContentEvent;
    
    // FIXME: Replace with the real new content
    String newContent = "...";
    
    // Define update content event for textview or button component "body"
    UpdateContentEvent event = new UpdateContentEvent(newContent, "#body");
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager eventManager = BlueConicEventFactory.getInstance();
    eventManager.publish(event);

Example 6: Updating values

BlueConic allows the marketer to create a form listening rule that updates a profile property when a form field changes its value:

On iOS most of the field classes will automatically pick up value changes provided you define them as an @IBOutlet. This is the list of supported fields:

  • UISegmentedControl
  • UIDatePicker
  • UIStepper
  • UISwitch
  • UISlider
  • UITextField

UIPickerView is not supported! This means you have to add code to pick up value changes for such field, as defining it as @IBOutlet will not be enough.

On Android "TextView" and "Spinner" widgets will automatically pick up value changes. All other field types have to be facilitated with code within your app.

To facilitate the marketer for non-supported fields, add the following code to your App:

  • iOS (Swift):

    import BlueConicClient
    
    // UITextField is supported; value change will automatically be picked up
    // by listening to selector "#emailAddress" in BlueConic.
    @IBOutlet weak var emailAddress: UITextField!
    
    // UIPickerView is not supported; value change will not automatically be
    // picked up by listening to selector "#numberOfPersons" in BlueConic.
    @IBOutlet weak var numberOfPersons: UIPickerView!
    
    // Determine the value of the numberOfPersons picker, manually detect the value change
    if let newValue = numberOfPersonsContent[numberOfPersons.selectedRowInComponent(0)] where newValue != oldValue {
        oldValue = newValue
    
        // Define update values event for selector "#numberOfPersons"
        let event = UpdateValuesEvent(selector: "#numberOfPersons", values: [newValue])
    
        // Use EventManager to publish the event to BlueConic
        let eventManager: BlueConicEventManager = BlueConicEventFactory.getInstance()
        eventManager.publish(event)
    }
    
  • iOS (Objective-C):

    #import <BlueConicClient/BlueConicClient-Swift.h>
    
    // UITextField is supported; value change will automatically be picked up
    // by listening to selector "#emailAddress" in BlueConic.
    @property (weak, nonatomic) IBOutlet UITextField *emailAddress;
    
    // UIPickerView is not supported; value change will not automatically be
    // picked up by listening to selector "#numberOfPersons" in BlueConic.
    @property (weak, nonatomic) IBOutlet UIPickerView *numberOfPersons;
    
    // Determine the value of the numberOfPersons picker
    NSInteger selectedRow = [self.numberOfPersons selectedRowInComponent: 0];
    NSString *newValue = [numberOfPersonsContent objectForKey: [NSNumber numberWithInt: selectedRow]];
    
    // Manually detect the value change
    if (newValue != oldValue) {
        oldValue = newValue;
    
        // Define update values event for selector "#numberOfPersons"
        UpdateValuesEvent *event = [[UpdateValuesEvent alloc] initWithSelector: @"#numberOfPersons" values: @[newValue]];
    
        // Use EventManager to publish the event to BlueConic
        BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
        [eventManager publish: event];
    }
  • Android:

    import com.blueconic.plugin.events.BlueConicEventFactory;
    import com.blueconic.plugin.events.BlueConicEventManager;
    import com.blueconic.plugin.events.UpdateValuesEvent;
    
    // FIXME: Retrieve this from the actual component instead
    String email = "test@test.com";
    
    // Define update values event for selector "#emailAddress"
    UpdateValuesEvent event = new UpdateValuesEvent("#emailAddress", Collections.singletonList(email));
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager eventManager = BlueConicEventFactory.getInstance();
    eventManager.publish(event);
    

Now, when the user enters an e-mail address in your App, it will be picked up in BlueConic as well.

Example 7: Submitting a form

BlueConic allows the marketer to listen to in-App form submits as follows:

To facilitate the marketer, add the following code to your App:

  • iOS (Swift):

    import BlueConicClient
    
    // Define form submit event for selector "#loginForm"
    let event = FormSubmitEvent(selector: "#loginForm")
    
    // Use EventManager to publish the event to BlueConic
    let eventManager:EventManager = BlueConicClient.EventFactory.getInstance()
    eventManager.publish(event)
    
  • iOS (Objective-C):

    // Define form submit event for selector "#loginForm"
    FormSubmitEvent *event = [[FormSubmitEvent alloc] initWithSelector:@"#loginForm"];
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
    [eventManager publish:event];
  • Android:

    import com.blueconic.plugin.events.BlueConicEventFactory;
    import com.blueconic.plugin.events.BlueConicEventManager;
    import com.blueconic.plugin.events.FormSubmitEvent;
    
    // Define form submit event for selector "#loginForm"
    FormSubmitEvent event = new FormSubmitEvent("#loginForm");
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager eventManager = BlueConicEventFactory.getInstance();
    eventManager.publish(event);

Example 8: Custom defined event

BlueConic allows the marketer to set profile property values when a custom defined event is received. It even allows to check for specific values in the context of the event: 

To facilitate the marketer, add the following code to your App:

  • iOS (Swift):

    import BlueConicClient
    
    let valueList = ["blueberry", "sushi", "pancakes"]
    
    // Define advanced event with the name "video_started"
    let event = AdvancedEvent(eventName: "video_started", context: valueList)
    
    // Use EventManager to publish the event to BlueConic
    let eventManager = BlueConicEventFactory.getInstance()
    eventManager.publish(event)
    
  • iOS (Objective-C):

    NSMutableArray *valueList = [NSMutableArray array];
    [valueList addObject:@"blueberry"];
    [valueList addObject:@"sushi"];
    [valueList addObject:@"pancakes"];
    
    
    // Define advanced event with the name "video_started"
    AdvancedEvent *event = [[AdvancedEvent alloc] initWithEventName:@"video_started" context:valueList];
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
    [eventManager publish:event];
  • Android:

    import com.blueconic.plugin.events.BlueConicEventFactory;
    import com.blueconic.plugin.events.BlueConicEventManager;
    import com.blueconic.plugin.events.AdvancedEvent;
    
    List valueList = new ArrayList<>();
    valueList.add("blueberry");
    valueList.add("sushi");
    valueList.add("pancakes");
    
    // Define advanced event with the name "video_started"
    AdvancedEventevent = new AdvancedEvent("video_started", valueList);
    
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager eventManager = BlueConicEventFactory.getInstance();
    eventManager.publish(event);

Let's examine this advanced event example in detail. The App publishes an event with the name "video_started" and a list of three values ("blueberry", "sushi" and "pancakes") is added as context. Adding values is optional, it provides extra information to allow the marketer to make more specific rules.

On the BlueConic side, the example rule in the screenshot says "... if event video_started is received with a context with contains blueberry, raspberry for any value". The published example event contains one of those values (blueberry) for the event, which means there is a match. As a result, BlueConic will add the value "fruit" to the profile property "Food Preferences" of the profile for this particular App user.

Setting profile properties directly

In the examples above you have learned how to allow the marketer to make his own rules in BlueConic on when to set what profile property and with what value. But sometimes you simply want to get or set a profile property directly from inside your Mobile App.

This is also supported by the BlueConic SDK. Ask the marketer for the id of the profile property in BlueConic and use one or more of the following BlueConicClient methods from the SDK (iOS, Android):

  • getProfileValue
  • getProfileValues
  • addProfileValue
  • addProfileValues
  • setProfileValue
  • setProfileValues

A common use case for setting profile properties directly is to store attributes of the user, especially those that can be used for profile merging across devices. To do this, you would first need to note the ID of the user and email address profile properties you wish to populate (e.g. user_id and email). Then, the setProfileValue method should be used to populate these profile properties accordingly.

See the SDK documentation for code examples that explain the usage of each method.