react-native-blueconic

This package, authored and owned by GX Software, allows one to use BlueConic in a React Native app.

Deprecated

This package is deprecated and receives limited support from GX Software. Use of the official BlueConic npm package @blueconic/blueconic-react-native is recommended.

react-native-blueconic

Installation

iOS

Download the BlueConic SDK for iOS here and add the BlueConicClient framework to the app by dragging the BlueConicClient.framework folder into the Embedded Binaries section of the General tab in XCode.
Locate your app's Information Property List file under "Supporting Files". To the file,
- Add a new row with the following key-value pair:
  - key: bc_server_url
  - value: The URL of the hostname of your BlueConic server, e.g. http://example.blueconic.net
- Add a new row.
  - Set the key name to URL Types. This creates an array that contains more property rows.
  - Open the 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 key name of the new row to URL Schemes. This creates another array. Add a new row to this array’s ’Item 0’ and enter your app’s ’Bundle Identifier’, e.g. com.blueconic.testApp.
  - A full example of the URL Types is shown below.
- Optionally, add a debug key for BlueConic. To do so, add a new row with the 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 this key is optional; if you do not want to receive debug logs from the SDK, you do not need to add it.
Run the following command in your project's root folder:
$ npm install react-native-blueconic
In XCode, add the .xcodeproj file of the RNBlueConic library to the Libraries group of the project. You can find RNBlueConic.xcodeproj in your app's node_modules folder in node_modules/react-native-blueconic/ios.
Add the libRNBlueConic.a library to the Link Binary with Libraries section of the Build Phases of the app target.
This package assumes that the BlueConicClient.framework is saved in the ios folder of your app project. If this is incorrect, or if the RNBlueConic library is unable to find the BlueConicClient, add the path to the BlueConicClient.framework to the Framework Search Paths Build Setting of the RNBlueConic target.
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 {YourApp}/ios/Pods/Headers/Public in case react-native is used through CocoaPods. If the react-native headers are saved elsewhere, add the path to the Header Search Paths Build Setting of the RNBlueConic target.
Make sure your app contains a Swift file and a Bridging-Header file. Both may be empty, but the Bridging-Header must be listed as the Objective-C Bridging-Header Build Setting of the app target.

To enable BlueConic simulator functionality, select the AppDelegate class.

For Swift, add the import

import BlueConicClient

and the following method:

func application(_ application: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] ) -> Bool {    BlueConicClient.getInstance(nil).setURL(url)

to AppDelegate.swift.

For Objective-C, add the import

#import <BlueConicClient/BlueConicClient-Swift.h>

and the following method

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  [[BlueConicClient getInstance:nil] setURL:url];
  return YES;
}

to AppDelegate.m.

Android

Download the BlueConic SDK for Android here and add the blueconic-lib-{version}.aar file to the directory {YourApp}/android/app/libs. Make sure this directory contains only one BlueConic SDK and that its name starts with blueconic-lib.

Edit the AndroidManifest.xml of the app.

Add the following permissions:

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

To enable BlueConic simulator functionality, add the following intent filters:

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

Create a configuration file for BlueConic named blueconic_configuration.xml in {YourApp}/android/app/src/main/res/values/ containing the following:
```
<?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 your BlueConic server.
- Optionally, add a debug node to the file to receive debug logs from the BlueConic SDK. This leads to the following example configuration file:
```
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="bc_server_url">http://example.blueconic.net</string>
  <bool name="bc_debug">true</bool>
</resources>
```
Run the following command in your project's root folder:
$ npm install react-native-blueconic
Open up android/app/src/main/java/[...]/MainApplication.java
- Add import com.gxsoftware.reactblueconic.BlueConicReactPackage; to the imports of the file.
- Add new BlueConicReactPackage() to the list returned by the getPackages() method.

Append the following lines to android/settings.gradle:

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

Insert the following line inside the dependencies block in android/app/build.gradle:
```
implementation project(':react-native-blueconic')
```

Usage

The react-native-blueconic package allows one to use BlueConic in a React Native app. The package provides Native Modules for iOS and Android that expose a number of methods to the JavaScript to allow the user to send events to BlueConic and show BlueConic dialogues. The Native Modules are exposed under the name BlueConic and can hence be used as NativeModules.BlueConic provided the following import is present in the JavaScript:

import { NativeModules } from "react-native";

The rest of this section covers the exposed JavaScript functions and event objects. Section 3 gives a functional overview of which functions to use in which scenario, along with several technical and non-technical examples.

Exposed JavaScript functions

The Native Modules expose the following JavaScript functions:

registerPageView(String screenName)
This function must be called on every screen change, as it loads all the necessary plugins (i.e. listeners and interactions) that must be active on that screen. None of the other exposed functions will work properly if registerPageView() isn't called first.
registerClickEvent(String identifier)
This function creates a ClickEvent with an identifier and publishes it to BlueConic. A listener that uses a click/tap rule can listen to this event, e.g. a behavior listener. Note that this function does not support sending data along with this event, other than the information that a certain element was clicked.
registerClickEventWithContext(String identifier, [String] values)
This function creates a ClickEvent with an identifier and an Array of String values to be sent along with the event as its context. A listener that uses a click/tap rule can listen to this event, e.g. a behavior listener. To write the values in the context of the event into profile properties, one must select the "Value from context of an event" option from the expert value settings of the listener rule. This will be covered in more detail in section 3.
Note that using this functionality requires a BlueConic iOS / Android SDK of version 2.5.0 / 2.3.0 or higher.
registerUpdateValuesEvent(String identfier, String value)
This function creates an UpdateValuesEvent with an identifier and a value, and publishes it to BlueConic. A Rule Based Form Listener can be configured to listen to such an event. This event does send data along with it, which can be used to change profile properties.
registerAdvancedEvent(String eventName, [String] values)
This function creates an AdvancedEvent with a name and an Array of values to be sent along with the event as its context. This can be used in Interest Ranking Listener rules to match values of the context with interests configured in the listener. It can also be used in a Behavior Listener to add the context to a profile property.
registerDialogueEvent(String eventType, String interactionId)
This function is used to register views, clicks, and conversions for BlueConic dialogues. The allowed values for the eventType are VIEW, CLICK, and CONVERSION. The interactionId parameter is used to identify the interaction. It is a non-configurable property of the dialogue event object, with name interactionId.
registerCustomEvent(String eventName)
This function is used to register any custom event that you want to publish to BlueConic. The published event can be used to trigger dialogues if selected on the "When"-tab of the dialogue. Note that this requires at least BlueConic SDK version 2.4.0 (Android) or 2.6.0 (iOS).
setProfileValues(String propertyName, [String] values)
This function sets the value of the profile property directly from the app.
addProfileValues(String propertyName, [String] values)
This function adds the specified values to the existing values of the profile property.
getProfileValues(String propertyName, Function callbackFunction)
This function gets the values in the specified profile property. Note that functions of native modules cannot return values. Instead, a callback function can be used to use the values obtained in the native module. The String parameters passed to the callback function from the native module are the obtained profile property values. Since it is not known how many parameters will be passed to the callback, it is advised to use rest parameter syntax in the callback function.
getProfileValuesAsPromise(String propertyName)
This function gets the values in the specified profile property. This function differs from the previous in that instead of using a callback function, the result is returned to the JavaScript as a Promise. Hence, one can use async/await syntax to obtain the values returned by this function.
getProfileId(Function callbackFunction)
This function gets the ID of the BlueConic profile and passes it to the callback function.
getProfileIdAsPromise()
This function gets the ID of the BlueConic profile and returns the ID as a Promise.
destroyPlugins()
On Android, this function detroys the active plugins (listeners and interactions) of the screen. The BlueConic SDK automatically destroys all active plugins when registerPageView is called, in order to clean up the plugins from the previous page. Hence, destroyPlugins need only be called if one wishes to clean up the active plugins at some other time. On iOS, there is no option to manually tell the SDK to clean up the active plugins. Nonetheless, the iOS Native Module does expose this method, to allow you to call NativeModules.BlueConic.destroyPlugins() without resorting to platform-specific code.

Events sent to JavaScript

The functions listed above mostly relate to enriching user profiles by collecting data. To show the user of the app a BlueConic Dialogue, a different mechanism is used. The package contains an implementation of such a dialogue, that uses the Native Modules to send an event to the JavaScript once the onLoad() method of the BlueConic Dialogue has been called. The event contains the parameters of the dialogue, which can be configured in the BlueConic environment. The name of the event is onReceivedBlueConicPluginParameters.

To make use of this feature, one must create a BlueConic plugin XML file that defines which parameters can be configured in BlueConic. For more information on the XML, see this and this for iOS and Android, respectively. It is important to add the following to the XML file inside the plugin node:

<mobile>
    <plugins>
        <plugin type="android">com.gxsoftware.reactblueconic.BlueConicDialogue</plugin>
        <plugin type="iOS">RNBlueConic.BlueConicDialogue</plugin>
    </plugins>
</mobile>

The parameters that you define in the XML will be configurable within Blueconic. The values will be available on the onReceivedBlueConicPluginParameters event object. This package adds three further parameters to the object:

interactionId
positionId
profileId

These contain the interactionId, selected position identifier of the dialogue, and profileId of the corresponding profile, respectively. To avoid conflicts, make sure that you do not define parameters with these identifiers in the plugin XML. Moreover, to be able to use the positionId property, make sure to add the following line to the frontend node in the XML:

<positiontype>position</positiontype>

In order to subscribe to the event, one must create an event emitter object in the JavaScript of the component. For iOS, this is done by calling the constructor of NativeEventEmitter, with the Native Module as its argument. For Android, the emitter must be the DeviceEventEmitter. One then adds a listener to this emitter, specifying the event to listen to and the function to execute once the event is received. For example:

import { DeviceEventEmitter, NativeEventEmitter, NativeModules, Platform } from 'react-native';
// other imports here

class SomeClass extends React.Component {
  constructor() {
    super();
    const eventEmitter = Platform.select({
      ios: new NativeEventEmitter(NativeModules.BlueConic),
      android: DeviceEventEmitter
    });

    this.blueConicDialogueSubscription = eventEmitter.addListener("onReceivedBlueConicPluginParameters", (event) => {
      // Do something with the event object containing the parameters as configured in BlueConic, e.g.
      this.setState({
        dialogueTitle: event.title,
        dialogueContent: event.content,
        dialogueId: event.interactionId,
        dialoguePosition: event.positionId
      });
    });
  }

  // It is important to unsubscribe, typically when the component unmounts
  componentWillUnMount() {
    this.blueConicDialogueSubscription.remove();
  }

  // render() etc.
}

One can create a dialogue in BlueConic and configure it to be active on certain screens only. Typically, one would then add the event listener as described above to the component of the screen. When BlueConic has passed the parameters to the Native Module, the event will be published and the JavaScript can use the parameters of the dialogue.

When the BlueConic dialogue should be destroyed according to the settings of the dialogue in BlueConic, the Native Modules publish an event with the name onBlueConicPluginDestroyed. One can subscribe to this event in a similar fashion as above, using the event as a signal to remove the dialogue from the screen. This event contains the same properties as the onReceivedBlueConicPluginParameters event described earlier.

Overview

Note: a PDF version of this README is available in the root-level directory of this package. The PDF contains useful images illustrating how to configure listeners in BlueConic.

What can a BlueConic enabled React Native app do?

For starters, BlueConic can listen to the app by monitoring page views. Apart from this, the BlueConic SDK supports the following listeners:

Global listener
The global listener collects general data such as app ID and version, hardware infor- mation, visit dates, visited channels, and much more.
Interest Ranking & Scoring listener
These listeners allow you to add interests or scores to a profile property based on a points-based system.
Form listener
The rule-based form listener allows you to write values based on user input into profile properties.
Behavior listener The behavior listener allows you to modify a visitor’s profile based on their behavior. Behavior, in this case, relates to visitor clicks and views, or custom events.

Moreover, a BlueConic enabled React Native app is able to personalize the user experience by displaying dialogues.

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

Assuming you have installed the node package as described in section 1, the next step to make BlueConic work in your app is to register page views.

Make sure you always register page views in your app!

Calling the registerPageView method is essential to making the BlueConic work in your app, as it triggers the BlueConic SDK to load all listeners and dialogues that ought to be active on that screen.

Registering the page views enables BlueConic to track the visited screens. If you wish to store these in a profile property, you can configure a behavior listener to do so. The screen name as registered using the registerPageView method can be retrieved by a listener using the regular expression (.*) in the Value from URL / mobile screen (regular expression) field of a URL / mobile screen listener rule.

Enabling advanced operations

In the previous section, the app was enabled for basic operations. This means that the marketer can now listen to the basics of your app, e.g. measure views, determine the visited screens 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!

Sending events to BlueConic

The node package allows you to send events to BlueConic. This allows you to keep BlueConic informed of what is happening in your app. This is also how you send data to BlueConic that can be read by listeners.

There are three event types that are supported by this package:

ClickEvent
This event signals BlueConic that a specific component has been clicked. It is possible to supply this event with a context, i.e. data that can be stored in profile properties. This is not necessary though.

To send a ClickEvent to BlueConic, use either registerClickEvent or registerClickEventWithContext, depending on whether you want to add data to the event.

For example, to indicate that the user has clicked a certain button, one would add the following line of code to the JavaScript of the app:
```
NativeModules.BlueConic.registerClickEvent("#nextButton");
```
This allows the marketer to save a certain value in a profile property when this event is received. To do so, a click / tap listener rule must be configured in a behavior listener, in which the selector of the click area matches the specified identifier (#nextButton in this example).

If you would like to save a certain value to be determined in the app, one can instead add the following line of code:
```
NativeModules.BlueConic.registerClickEventWithContext("#nextButton", ["SomeValue"]);
```
This allows the marketer to save the specified value in a profile property when the event is received. To do so, the expert setting Value from context of an event must be selected in the listener rule.
UpdateValuesEvent
This event signals BlueConic that the value of a specific component has been updated. The event contains a selector to specify the component, as well as a value to be used in a listener.

To send an UpdateValuesEvent to BlueConic, add the following line of code to the app:
```
NativeModules.BlueConic.registerUpdateValuesEvent("#emailAdress", "test@test.com");
```
To add the value to a profile property, a rule-based form listener ought to be configured. The selector of the form field should match the specified identifier (#emailAdress in this case), and the Form field value changes box must be selected.
AdvancedEvent
This allows you to send a custom event to BlueConic with its own specific name and a list of values.

To send an AdvancedEvent to BlueConic, add the following line of code to the app:
```
NativeModules.BlueConic.registerAdvancedEvent("#someEventName", ["value_1", "value_2"]);
```
To add the context of the event to a profile property, a behavior listener should be configured that contains an Advanced Event rule. The name of the Custom defined event field must match the name attached to the event.

An AdvancedEvent can also be used for interest ranking. To do so, the marketer should configure an interest ranking listener that contains an Advanced Event scoring rule.

Working with profile properties directly

In the previous examples, it was illustrated how to configure listeners to change profile properties when events were received from the app. It is also possible to work with profile properties directly, without the need for listeners.

Note that in many cases, using events and listeners is the preferable method of working with profile properties, as this is configurable from BlueConic and changes can easily be made in the BlueConic environment.

Nonetheless, 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 be able to do so, you first need to know the ID of the profile property in question. Next, one can use the setProfileValues, addProfileValues, and getProfileValues methods to work with the property directly.

react-native-blueconic

react-native-blueconic

Deprecated

Table of contents

Installation

iOS

Android

Usage

Exposed JavaScript functions

Events sent to JavaScript

Overview

What can a BlueConic enabled React Native app do?

Before you start

Enabling basic operations

Enabling advanced operations

Sending events to BlueConic

Working with profile properties directly

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

react-native-blueconic

react-native-blueconic

Deprecated

Table of contents

Installation

iOS

Android

Usage

Exposed JavaScript functions

Events sent to JavaScript

Overview

What can a BlueConic enabled React Native app do?

Before you start

Enabling basic operations

Enabling advanced operations

Sending events to BlueConic

Working with profile properties directly

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads