Knowledge Base

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: The BlueConic customer data platform harnesses the data required to power the recognition of an individual at each interaction and then synchronizes their intent across the marketing ecosystem.

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 article describes 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, we'll describe what exactly a BlueConic enabled app can 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 BlueConic Listeners:

• Global Listening
• Interest Ranking
• Scoring
• Form Listening
• Behavior Listening

The app can also send events to signal to 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 you get to know the individual and drive better outcomes.

For example, you can create lightbox dialogues in BlueConic to conditionally show lightbox content in your app. You can create custom dialogues for your apps by using the BlueConic SDK for iOS or Android to create a custom plugin.

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 a BlueConic user at your site to do it for you. BlueConic will not work with your mobile app unless it has been set up as a BlueConic mobile 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.

Important: 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 similarly 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 the web and an 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 BlueConic user can retrieve the screen name "Main/Section1" as a value like so (using the regular expression (.*)):

Or the BlueConic user 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 BlueConic user to define values:

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

 

Example 3: Mobile screen

The BlueConic user 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 BlueConic user 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 enables users to indicate the button that defines the click area in a Click / Tap rule as follows:

To make this work for your BlueConic users, 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 enables you 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 enable this for the BlueConic users at your site, 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 enables you 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 make this work for your BlueConic users 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 enables you to listen to in-app form submits as follows:

To enable this for your BlueConic users, 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 enables you 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 enable this feature for your BlueConic users, 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 BlueConic users at your site 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, BlueConic users at your site can define BlueConic Listeners to keep track of these events and store data to the profile. To create listeners for these events, they just has to know the selectors the developer used in their events (e.g. “#favoriteSport”).

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

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

Inside these listeners, BlueConic users 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:

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 enable BlueConic users at your site 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 your BlueConic users 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:

• BlueConic SDK for iOS
• BlueConic SDK for Android