Knowledge Base

The BlueConic SDK for React Native makes it easy for developers to collect profile data from their Android and/or iOS native apps. This section explains how to integrate BlueConic into your React-Native apps. If you are looking for information on Android apps, see the BlueConic SDK for Android. And, if you are looking for information on iOS apps, see the BlueConic SDK for iOS.

You can use the React Native SDK to do the following:

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

BlueConicClient Framework

The BlueConicClient Framework provides the basis for communication with BlueConic. It provides possibilities to develop your own interactions by creating mobile plugins. BlueConicClient Framework allows you to make use of the standard BlueConic plugins. It contains several plugins that are mobile variants of the standard BlueConic Listeners plugins.  

Before you begin

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

• The latest version of Xcode
• The Android SDK (available for Windows, Mac OS X, and Linux)
• The latest version of BlueConic SDK for Android
• An iOS app that you can use to implement the BlueConicClient SDK for iOS

Notes about upgrading an existing implementation

When upgrading your implementation keep these points in mind:

• When upgrading to 1.2.0, a migration step might be required when you are using dialogues. The structure of these events is now equal on both platforms (iOS/ Android), where all interaction parameters are added to the nested property "parameters".
• When upgrading to 2.0.0, please make sure the latest versions of both the Android and iOS SDKs are included in your app. For Android, include the latest .aar file; for iOS, use pod update when using CocoaPods.

Testing your mobile app

To test your mobile app you will need to have 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? If so, ask someone from 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.

Getting Started

Before you start implementing the SDK, use the following steps to set up your environment:

React-Native

Run the following command in your React Native project's root folder

$ npm install @blueconic/blueconic-react-native

Or include it to your React Native project's package.json:

{
  "react": "*",
  "react-native": "*",
  "@blueconic/blueconic-react-native": "<latest version>"
}

Note: To determine the latest version, see https://www.npmjs.com/package/@blueconic/blueconic-react-native?activeTab=versions.

iOS implementation of the React Native App

1. Add the BlueConicClient framework to your app:
   There are two ways to do this:
   1. (Recommended) Install with CocoaPods.
      Add pod 'BlueConicClient' to your Podfile.
      Open the Podfile and add the following line in your app-target

      pod 'BlueConicClient'

      In the terminal, make sure you have the pods installed by the following command:

      pod install

   2. Add the .xcodeproj file of the ReactNative BlueConicClient library.
      
      1. In Xcode, add the .xcodeproj file of the BlueConicClient library to the Libraries group of the project, you can find the BlueConicClient.xcodeproj in your app's node_modules in 
         

         node_modules/@blueconic/blueconic-react-native/ios

         To do this, drag and drop the .xcodeproj file to the Libraries group in Xcode
      2. The .xcodeproj will include a Product folder, make sure the libBlueConicClient.a library is added to the Link Binary with Libraries section of the Build Phases of the app's target
      3. The package is dependent on react-native. It searches for the react-native headers both in your project’s node modules/react-native/React directory, as well as in ./ios/Pods/Headers/Public in case react-native is used through CocoaPods. If the react-native headers are saved elsewhere, add the correct path to the Header Search Paths Build Setting of the BlueConicClient target.
2. Add the configuration key for BlueConic:
   Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right-clicking the top row and selecting "Add row". Set the following key name:
   

   bc_server_url

   Double-click the value field and enter the URL for the hostname of your BlueConic server. For example:

   https://example.blueconic.net

3. Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right-clicking the top row and selecting "Add row". Set the following key name:
   

   URL types

   This creates an array that contains more property rows. Open "URL types" by clicking the triangle icon in front of the name to display the rows. Right-click "Item 0" and select "Add row". You can also add a new item, and add the new row within that item. Set the following key name:
   

   URL Schemes

   This creates another array. Add a new row to this array's "Item 0" and enter your apps "Bundle Identifier", for example:

   com.blueconic.testApp

   Full example of the URL Schemes:
   

   

4. Optionally, add a debug key for BlueConic:
   Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right clicking the top row and selecting "Add row". Set the following key name:
   

   bc_debug

   Click the type and select 'Boolean'. Set the value to "YES" if you want to receive debug logs from the BlueConic SDK. Adding a debug key is optional; if you do not want to receive debug logs from the SDK, you do not need to add it.
5. Import BlueConic:
   The BlueConic SDK for iOS enables you to set and retrieve profile property values for a BlueConic profile and enables interactions specific to this BlueConic profile. These methods can be used anywhere in the app. Make sure that you import the framework and get the instance before using the BlueConicClient methods:

   // Swift:
   import BlueConicClient
   
   let client = BlueConicClient.getInstance(self)
   
   // Objective C:
   // If using cocoapods
   @import BlueConicClient;
   
   // If using .framework - embedded libraries
   #import <BlueConicClient/BlueConicClient-swift.h>
   
   BlueConicClient *client = [BlueConicClient getInstance];

6. After you have added the URL Scheme value, select the AppDelegate class, and add the following method to enable simulator functionality:

   // Swift: in the AppDelegate.swift file
   func application(_ application: 
   UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] )
    -> Bool 
   {    
       BlueConicClient.getInstance().setURL(url)    
       return true
   }
   
   // Objective-C: in the AppDelegate.m file
   - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url 
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id class="s1">> *)options 
   {
       [[BlueConicClient getInstance] setURL:url];
       return YES;
   }
   

Android implementation of the React Native App

1. Add the Android SDK blueconic-lib-.aar to your app project as a gradle module:

   • Create a blueconic directory in your project's android root directory.
     Add the build.gradle file with these contents:

     configurations.maybeCreate("default") 
     artifacts.add("default", file('blueconic-lib-<version>.aar'))

   • Add the .aar file to the 'blueconic' directory, alongside the build.gradle. You now have a gradle module called 'blueconic' that can be used in your app as well as in the BlueConic react-native NPM module.

2. Include the React Native project in the settings.gradle.

   
   

   Append the following lines to the android/settings.gradle file:

   include ':blueconic'
   include ':blueconic_blueconic-react-native'
   project(':blueconic_blueconic-react-native').projectDir = 
           new File(rootProject.projectDir,
           '../node_modules/@blueconic/blueconic-react-native/android')

   This loads both the BlueConic React Native library and the BlueConic Android SDK.

3. (Optionally) Set the "allow backup"-option to true in the AndroidManifest.xml.

   It could be that the IDE requires to override the "allowBackup" options in order to build.
   Add or change this option in the AndroidManifest.xml:

   android:allowBackup="true"

4. Add permissions to the AndroidManifest.xml:

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

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

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

   
   

7. Optionally, enable debug mode:

   Add the following node to the configuration file:

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

   Example of the complete 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>

Using the BlueConicClient SDK in React Native apps:

1. Import NativeModules in the app.
   Import the BlueConicClient module within your app
   

   // React Native: in the Example.js file
   import {
     NativeModules
   } from "react-native";
   const {BlueConicClient} = NativeModules;
   

2. Create a page view event each time the user switches screens. 
   To keep track of every page viewed in the app, you are able to do so by creating a page view event. Make sure that a unique screen name is passed in the call. The screen name can be used in listener rules or to restrict interactions to specific screens. 

   // React Native: in the Example.js file
   // Simple screen names, like 'main' pages
   BlueConicClient.registerPageView("main");
   
   // Unique screen names, e.g. per article
   BlueConicClient.registerPageView("news/article/" + UID);

3. Retrieve and store profile properties:
   The BlueConic SDK for React native 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 page has been opened and stores this number in the BlueConic profile:

   // React native: in the ExampleScreen.js file
   import React, { Component } from 'react';
   import {
     Text,
     View,
     NativeModules
   } from 'react-native';
   const {BlueConicClient} = NativeModules;
   const PROPERTY_ID = "pageCount";
   
   export default class ExampleScreen extends Component {
     constructor() {
       super();
       this.state {
         pageCount: 0
       };
       this.updatePageCount();
     }
     updatePageCount = async() => {
       const getProfileResult = await BlueConicClient.getProfileValue(PROPERTY_ID);
       let pageCountValue = parseInt(getProfileResult) ?? 0;
       BlueConicClient.setProfileValue(PROPERTY_ID, ++pageCountValue);
       
       this.setState({
         pageCount: pageCountValue
       });
     }
   }

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

   // React native: in the ExamplePlugin.js file
   
   // Register Dialogue events
   BlueConicClient.registerDialogueEvent("VIEW", this.interactionId);
   BlueConicClient.registerDialogueEvent("CLICK", this.interactionId);
   BlueConicClient.registerDialogueEvent("CONVERSION", this.interactionId);
   
   // Register events through 'createEvent'
   BlueConicClient.createEvent("VIEW", {
     "interactionId": this.interactionId
   }
   
   

Configuring BlueConic

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

Add the 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. See Managing channels for complete information.

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.

BlueConicClient Methods

Implementation of the BlueConic client, handling profile retrieval and storage. This may be from cache, persistent storage on the client or direct requests to the BlueConic server.

import {
 NativeModules
} from "react-native";
const {BlueConicClient} = NativeModules;

// with promise:
const profileId = await BlueConicClient.getProfileId();

// with callback:
BlueConicClient.getProfileIdWithCallback(profileId => {

});

// with promise:
const hobby = await BlueConicClient.getProfileValue("hobby");

// with callback:
BlueConicClient.getProfileValueWithCallback("hobby", hobby => {

});

// with promise:
const hobbies = await BlueConicClient.getProfileValues("hobbies");

// with callback:
BlueConicClient.getProfileValuesWithCallback("hobbies", hobbies => {

});

BlueConicClient.addProfileValue("hobbies", "tennis");

// Swift:
const hobbyArray = ["tennis", "soccer"]
BlueConicClient.addProfileValues("hobbies", ["tennis", "soccer"]);

BlueConicClient.setProfileValue("hobby", "tennis");

// Swift: 
BlueConicClient.setProfileValues("hobbies", ["tennis", "soccer"]);

BlueConicClient.setLocale("en_US");

BlueConicClient.createEvent("PAGEVIEW", {
  "screenName": "Main/HOMETAB"
});
BlueConicCLient.createEvent("VIEW", {
  "interactionId": this.interactionId
}):

BlueConicClient.incrementProfileValue("hobbies", "1");

Register Methods

Methods to register events and page views

BlueConicClient.registerPageView("Main/HOMETAB");

BlueConicCLient.registerDialogueEvent("VIEW", this.interactionId):

BlueConicClient.registerClickEvent("#homeButton");

BlueConicClient.registerClickEventWithContext("#homeButton", 
     ["contextA","contextB"]);

BlueConicClient.registerUpdateValuesEvent("#updateHobby", ["tennis","soccer"]);

BlueConicClient.registerAdvancedEvent("facebookLike", ["+1"]);