React Native - Android

Requirements

This setup assumes you have already setup your App Key on the Dashboard, see prerequisites for more on this.

1. Your App must be targeted for at least Lollipop (21) and above;
2. Your app’s compileSdkVersion must be set to 28 or higher;
3. Contextual supports React Native 0.60 or more recent, older versions might have incompatibility issues;

4. Contextual uses Java 1.8 features, please make sure your app uses it as well:

   android {
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
       kotlinOptions {
           jvmTarget = "1.8"
       }
   }
   

5. Contextual UI is based on Google's Material Components library. Please ensure your app's theme inherits from Theme.MaterialComponents or its subthemes.

6. Verify that your app uses a version equal or more recent to 1.1.0

   dependencies {
       implementation (group: "com.google.android.material", name: "material", version: "1.1.0")
   }
   

7. Make sure that inside your app/res/values/styles.xml (or equivalent) the parent of AppTheme is part of the Theme.MaterialComponents theme. Here is an example from the Wikipedia's app:

   <style name="BaseAppTheme" parent="Theme.MaterialComponents.Light.NoActionBar"> 
       <...>
   </style>
   <style name="AppTheme" parent="BaseAppTheme">
       <...>
   </style>
   

Tip

If you are having issues with using Material with Contextual please check instructions here, specially step 4

Integration Steps

Step 1 - Native Integration

Setup the Android native SDK requirements.

Step 2 - Install the npm module:

npm install react-native-contextual-mobile-sdk --save

Link the dependency (not necessary in ReactNative version >0.60):

react-native link react-native-contextual-mobile-sdk

Step 3 - Set your Contextual AppKey

Set Contextual App Key in the android/app/src/main/AndroidManifest.xml

Under the application tag, add the following meta-data tag replacing APP_KEY with your app key:

<application
    android:name=".MainApplication">
    <meta-data
        android:name="com.contextu.al.APP_KEY"
        android:value="APP_KEY" />
</application>

React Native has only one Activity, when the user switches from page 1 to page 2 on your App the native side will not know what to name Page 1 and Page 2. Sometimes naming them the same or with non friendly names.

To fix this and allow Contextual to work properly you should add ContextualReact.viewWillRender('VIEW_NAME'); on the JS side of your app, changing VIEW_NAME with the name of the view or a variable that contains it.

Call this method when there there is a page transition, this will allow the SDK to know that there was a View change and its name. A Few Examples showcasing how to do this can be found below.

React Navigation's NavigationContainer:

      <NavigationContainer
      ref={navigationRef}
      onReady={() => { 
          if (navigationRef !== undefined && navigationRef.current !== undefined) {
            routeNameRef.current = navigationRef.current.getCurrentRoute().name;

            // Let Contextual know about the first view
            ContextualReact.viewWillRender(navigationRef.current.getCurrentRoute().name);
          }
      }}
      onStateChange={() => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.current.getCurrentRoute().name

        if (previousRouteName !== currentRouteName) {
          // Let Contextual know about the change
          ContextualReact.viewWillRender(currentRouteName);
        }

        // Save the current route name for later comparision
        routeNameRef.current = currentRouteName;
      }}
      >
        <...>
      </NavigationContainer>

Tab pages:

onTabSelect(tab: Tab) {
    if (this.props.tab !== tab) {
      this.props.onTabSelect(tab);
    }
    console.log('I entered into a new Page called: ' + JSON.stringify(tab))
    PointziReact.viewWillRender(JSON.stringify(tab));
  }

Or in some React Native projects, when a page has changed componentWillMount() is called upon page enter.

Class Component:

import Contextual from "react-native-contextual-mobile-sdk";

class PageOne extends Component {
//...
 componentWillMount() {
      console.log('When user enters here, Contextual will call this view PageOne')
      ContextualReact.viewWillRender('PageOne');
   }
//...
render() {
    return (
     //...
     );
   }
}

import Contextual from "react-native-contextual-mobile-sdk";

class PageTwo extends Component {
//...
 componentWillMount() {
      console.log('When user enters here, Contextual will call this view PageTwo')
      ContextualReact.viewWillRender('PageTwo');
   }
//...
render() {
    return (
     //...
     );
   }
}

Function Component:

import React, { useEffect } from "react";
import Contextual from "react-native-contextual-mobile-sdk";

const PageOne = () => {
//...
useEffect(() => {
    ContextualReact.viewWillRender('PageOne');
  }, []);
//...
  return (
    //...
  );
}

import React, { useEffect } from "react";
import Contextual from "react-native-contextual-mobile-sdk";

const PageTwo = () => {
//...
useEffect(() => {
    console.log('When user enters here, Contextual will call this view PageTwo')
    ContextualReact.viewWillRender('PageTwo');
  }, []);
//...
  return (
    //...
  );
}

Usage

Tagging

Prerequisite: - Contextual#init is successful

You can tag Contextual installs by the following.

Tag Name	Description
Code:	ContextualReact.tagUserId('MY USER ABC');
tagString	For tagging any String and Value
Code:	ContextualReact.tagString("String key" , "String tag");
tagNumeric	Tagging any Numeric String and double value
Code:	ContextualReact.tagNumeric("String key" , 123);
tagDateTime	Tagging any date time. Ensure the date time format is in ISO-8601
Code:	ContextualReact.tagDatetime("String key" , "2024-01-22T09:49:14.568208+11:00");
removeTag	Removing any tags
Code:	ContextualReact.removeTag("String key");
incrementTag	Increment tag by a value of 1.
Code:	ContextualReact.increment("String key");

---

Last update: 2024-01-30