React Native Android Integration

Prerequisites

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 eqal 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 pointzi-react --save

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

react-native link pointzi-react

Step 3 - Import pointzi

Import Pontzi module into android/settings.gradle

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

Use the pointzi-react module as a dependency in android/app/build.gradle file

dependencies {
    implementation project(':pointzi-react')
}

Step 4 - 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.pointzi.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 PointziReact.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
            PointziReact.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
          PointziReact.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 PointziReact from 'pointzi-react';

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

import PointziReact from 'pointzi-react';

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

Function Component:

import React, { useEffect } from "react";
import PointziReact from 'pointzi-react';

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

import React, { useEffect } from "react";
import PointziReact from 'pointzi-react';

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

Usage

Tagging

You can tag Contextual installs by the following.

Tag Name	Description
sh_cuid	Use sh_cuid to tag an install with a unique identifier for the install. sh_cuid is needed to link the identity of App Users to Users in your - and the StreetHawk backend. Allows tagging via api call. Used to identify the same User across multiple installs.
Code:	PointziReact.tagCuid('MY USER ABC');
tagString	For tagging any String and Value
Code:	PointziReact.tagString("String key" , "String tag");
tagNumeric	Tagging any Numeric String and double value
Code:	PointziReact.tagNumeric("String key" , 123);

---

Last update: 2024-01-14