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. For example, 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")
    let eventWithContext = ClickEvent(selector: "#nextButton", context ["value"]) // Use EventManager to publish the event to BlueConic let eventManager:EventManager = BlueConicEventFactory.getInstance() eventManager.publish(event)
    eventManager.publish(eventWithContext)
  • iOS (Objective-C):

    // Define click event for selector "#nextButton"
    ClickEvent *event = [[ClickEvent alloc] initWithSelector:@"#nextButton"];
    ClickEvent *eventWithContext [[ClickEvent alloc] initWithSelector: @"#nextButton" context: @[@"value"]];
    // Use EventManager to publish the event to BlueConic
    BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance];
    [eventManager publish:event];
    [eventManager publish:eventWithContext]
  • 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");
    ClickEvent eventWithContext = new ClickEvent("#nextButton", Collections.singletonList("value")); // Use EventManager to publish the event to BlueConic BlueConicEventManager eventManager = BlueConicEventFactory.getInstance(); eventManager.publish(event);
    eventManager.publish(eventWithContext);

 

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 = BlueConicEventFactory.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 email 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")
    let eventWithContext = FormSubmitEvent(selector: "#loginForm", context: "value") // Use EventManager to publish the event to BlueConic let eventManager:EventManager = BlueConicEventFactory.getInstance() eventManager.publish(event)
    eventManager.publish(eventWithContext)
  • iOS (Objective-C):

    // Define form submit event for selector "#loginForm"
    FormSubmitEvent *event = [[FormSubmitEvent alloc] initWithSelector:@"#loginForm"];
    FormSubmitEvent *eventWithContext = [[FormSubmitEvent alloc] initWithSelector; @"#loginForm" context:@[@"value"]]; 
    
    // Use EventManager to publish the event to BlueConic BlueConicEventManager *eventManager = [BlueConicEventFactory getInstance]; [eventManager publish:event];
    [eventManager publish:eventWithContext];
  • 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");
    FormSubmitEvent eventWithContext = new FormSubmitEvent("#loginForm", Collections.singletonList("value")); // Use EventManager to publish the event to BlueConic BlueConicEventManager eventManager = BlueConicEventFactory.getInstance(); eventManager.publish(event);
    eventManager.publish(eventWithContext)

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 that 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.

Adding context to a mobile event and using it in BlueConic Listeners

Adding context to an event makes it a lot easier to develop and configure which values a mobile developer is able to use and send through the event to BlueConic, where the event context can be used with BlueConic Listeners. Previously, this had to be configured by using a public UI element in order to retrieve data from a mobile app. Now mobile developers can use private or dynamic values and apply them directly as context to an event. This gives you more control and flexibility to publish BlueConic events within an app, and the marketing team can use them to define BlueConic Listeners, without having to know about the internal UI IDs of the mobile app.

Creating events in a mobile app and in your BlueConic environment

Mobile developers can develop these events in their code, for example to publish a ClickEvent whenever a customer clicks on his favorite sport (code shown below). In addition, you can define a BlueConic Listener to keep track of a customer's favorite category or sport.

You can add the ClickEvent to a function in your app, for example, by adding a click handler a customer interacts with in the UI or when they navigate to a different page. In the example code shown below, a click event is placed in the logic whenever a customer navigates to a specific category:

  • iOS (Swift):

    func navigateToCategory(category: SportCategory) {
    // Create a click event with context, e.g.: ClickEvent(selector: "#favoriteSport", context: ["soccer"])
    let sportsClickEvent = ClickEvent(selector: "#favoriteSport", context: [category.name])
    // Publish the event, so listeners can execute their rules
    // when they have subscribed to the #favoriteSport selector
    BlueConicEventFactory.getInstance().publish(sportsClickEvent)
    // Execute the rest of the function...
    }
  • iOS (Objective-C):

    - (void)navigateToCategory: (SportCategory *)category {
    // Create a click event with context, e.g.: [[ClickEvent alloc] initWithSelector:@"#favoriteSport" context: @[@"soccer"]];
    ClickEvent *sportClickEvent = [[ClickEvent alloc] initWithSelector:@"#favoriteSport" context: @[@"soccer"]];
    // Publish the event, so listeners can execute their
    // rules when they have subscribed to the #favoriteSport selector
    [[BlueConicEventFactory getInstance] publish:sportClickEvent];
    // Execute the rest of the function...
    }
  • Android:

    private void navigateToCategory(final SportCategory category) {
    // Create a click event with context, e.g.: new ClickEvent("#favoriteSport", Collections.singletonList("soccer"));
    final ClickEvent sportClickEvent = new ClickEvent("#favoriteSport", Collections.singletonList("soccer"));
    // Publish the event, so listeners can execute their
    // rules when they have subscribed to the #favoriteSport selector

    BlueConicEventFactory.getInstance().publish(sportClickEvent);
    // Execute the rest of the function...
    }

Once the developer adds the events within the app, the marketer can define BlueConic Listeners to keep track of these events and store data to the profile. To create listeners for these events, the marketer just has to know the selectors the developer used in their events (e.g. “#favoriteSport”).

Marketers can use the event feature in any of the following BlueConic Listeners:

  • Behavior listener
  • Interest Ranker listener
  • Rule Based Form listener
  • Scoring listener

mobile-listeners-set.png

Inside these listeners, marketers can define the following rules with the event option:

  • Click/tab rule
  • Form Submit rule (only accessible in the Rule-Based Form Listener)
  • Advanced rule

When setting up the BlueConic Listener, under “Expert Settings,” you select the “Value from context of an event” option, as shown here:

behavior-listener.png

For more information on how to set up a click event and allow it to listen to clicks in your app, see example 4.

To learn how to set up a submit form event and allow it to listen to app form submits in your app, see example 7.

Setting profile properties directly

In the examples above you have learned how to allow marketers to make their own rules in BlueConic on when to set what profile property and with what value. But sometimes you just want to get or set a profile property directly from inside your mobile app.

The BlueConic SDK supports the ability to get or set a profile property directly from inside the app. 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: