Integration
Product Guides

React Native

Things to keep handy before starting your integration with Apxor

Please have the following handy before beginning the integration:

Note

If you are already using a separate analytics class where you are sending events to different platforms from a single place it is much faster to use our tracking guide to complete event logging to setup triggers and track goals.

In case you are logging events to third parties after each interaction, please use our Third party API guide to migrate all the events that you are sending to one of the supported third parties as listed in the guide.

Getting started

Check here the latest release notes.

Step 1: Getting Started

For React Native version 0.60.0 and higher

Run the following commands

$ yarn add react-native-apxor-sdk react-native-apxor-rtm-plugin

  • react-native-apxor-sdk is to track events and navigatiocodens

  • react-native-apxor-rtm-plugin helps to create and display Walkthrough messages

For React Native version 0.59.0 and lower

Run the following commands

$ npm install react-native-apxor-sdk react-native-apxor-rtm-plugin --save
$ react-native link react-native-apxor-sdk react-native-apxor-rtm-plugin

  1. Open android/app/src/main/java/[...]/MainActivity.java

    • Add following imports statements at the top of the file

      import com.apxor.reactnativesdk.RNApxorSDKPackage;
  import com.apxor.reactnativesdk.RNApxorRTMPackage;
    @Override
protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
            new MainReactPackage(),
            ...
            new RNApxorSDKPackage(), <- ApxorSDK Package
            new RNApxorRTMPackage(), <- ApxorSDK RTM Plugin Package
            ...
    );
}

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

    include ':react-native-apxor-sdk'
project(':react-native-apxor-sdk').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-apxor-sdk/android')
include ':react-native-apxor-rtm-plugin'
project(':react-native-apxor-rtm-plugin').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-apxor-rtm-plugin/android')

Step 2: Configuring View IDs for Views

Note:

This step is necessary to identify the app screens' UI elements/ views. Configuring View IDs will help anchor the Tooltips, Coachmarks, and Badges to the specific UI element.

This step will take 30 minutes to 1 hour, based on the number of screens and views you want to configure ids for.

If you already have view IDs for the views, this step can be skipped.

React Native Apxor RTM plugin (react-native-apxor-rtm-plugin) will show Inline messages (also called as Tooltips) and CoachMark messages for a given View ID/Tag.

In React Native apps, you can mention View IDs for views by adding nativeID attribute to the Components. If any View that does not have nativeID attribute, Inline or Coachmark messages will not be shown.

For example, you want to show tooltip for a button. You can't directly give a unique id for Button. Instead, you need to wrap it up with a View tag like:

<View nativeID="loginButton">
    <Button onPress={this.handlePress}>Login</Button>
</View>

So, the same value for nativeID attribute can be configured in Apxor dashboard to identify the Button and display Inline or Coachmark message.

Android integration

Step 3: Add Apxor Repository

Add Maven URL in root/project level build.gradle

Path: <project>/build.graddle :

// Top-level build file where you can add configuration options 
// common to all sub-projects/modules.

buildscript {
    allprojects {
        repositories {
            maven {
                url "https://repo.apxor.com/artifactory/list/libs-release-android/"
            }
        }
    }
    // ....
}

Step 4: Add Apxor Android SDK to your App

Add the following into the build.gradle file in app-level

Path: <project>/<app-module>/build.gradle:

// ...
apply plugin: 'com.android.application'

android {
    // ...
    defaultConfig {
        minSdkVersion 16 // Minimum Sdk version must be 16 and above
        // ...
    }
    // ...
}

dependencies {
    // ...

    // Event tracking and a must have dependency for other plugins
    implementation 'com.apxor.androidx:apxor-android-sdk-core:3.0.5@aar'

    // Getting a "Could not find" error? Make sure that you've added
    // Apxor's Maven repository to your root-level/project-level build.gradle file
}

Step 5: Add exoplayer in your app (optional)

Exoplayer enables to configure Picture In Picture videos from Apxor dashboard and typically increases the app size by ~1Mb, if you are already using exoplayer in your app this step is not needed else add the following dependency in the application build.gradle file

Path: <project>/android/<app-module>/build.gradle:

  dependendies {
  //... 

  implementation 'com.google.android.exoplayer:exoplayer:2.14.0'

  //...
  }

Step 6: Disable Dexing Artifact Transformation

Note

In the Android Gradle Plugin 3.5.0, we desugar & dex using Gradle artifact tranforms, which allow more parallelism and caching. This mechanism relies on libraries having the correct Maven information, because we use dependencies specified in POM files to set up the desugaring classpath. In cases we are unable to see all dependencies when desugaring a class it is required to disable parallel transformation to faciliate the process by adding the property as mentioned below.

Add the following properties gradle.properties file

Path: <project>/android/<app-module>/gradle.properties:

android.enableDexingArtifactTransform = false

Step 7: Add the following in proguard-rules.pro

Note

If you use proguard to obfuscate the classes, you have to add the following to ignore obfuscation for Apxor SDK classes

Configure the below rules in your proguard-rules.pro file

Path: <project>/<app-module>/gradle.properties:

-keep class com.apxor.** { *; }
-dontwarn com.apxor.**

Note:

If you use androidx libraries, add the following property in gradle.properties file

android.enableJetifier = true

Step 8: Initialize Apxor Android SDK

  • Add following meta-data tag inside your application tag in your AndroidManifest.xml file

    <application>
    <!-- You must replace your app-id in android:value attribute -->
    <meta-data android:name="APXOR_APP_ID" android:value="APP_ID" />
</application>

Click here to Add New App and how to get the app id

Step 9: Plugins integration

  1. Add plugin dependencies to your application build.gradle file

    Path: <project>/<app-module>/build.gradle:

    dependendies {

    // Add this to track uninstalls and send push notifications from Apxor dashboard
    // firebase-messaging version >= 11.4.0 needed for push plugin
    implementation 'com.google.firebase:firebase-messaging:20.1.0'
    implementation('com.apxor.androidx:apxor-android-sdk-push:1.3.1@aar') {
        exclude group: 'com.google.firebase'
    }

    // Add these for Realtime Actions and Surveys
    implementation 'com.apxor.androidx:apxor-android-sdk-qe:1.6.9@aar'
    implementation 'com.apxor.androidx:apxor-android-sdk-rtm:2.4.0@aar'
    implementation 'com.apxor.androidx:surveys:2.1.4@aar'

    // Add this to track application crashes
    implementation 'com.apxor.androidx:apxor-android-crash-reporter:1.0.5@aar'

    // Helper plugin to create walkthroughs
    implementation 'com.apxor.androidx:wysiwyg:1.4.9@aar'

    // Add this to log events without attributes at runtime
    implementation 'com.apxor.androidx:jit-log:1.0.0@aar'

    // Getting a "Could not find" error? Make sure that you've added
    // Apxor's Maven repository to your root-level build.gradle file
}

  2. Create plugins.json file in your assets folder (usual path is src/main/assets/plugins.json) and add required JSON configs in it.

    For every plugin dependency you add in dependencies section, there will be a corresponding entry in this file.

    • If an entry for plugin exists in this file and the corresponding dependency doesn't exist in the dependencies section of app/build.gradle file, the SDK silently throws a ClassNotFoundException error log in logcat

    • If the dependency exists in dependencies section of app/build.gradle file and the corresponding entry doesn't exist in this file, that plugin will not initialize at runtime.

    {
  "plugins": [
    {
      "name": "rtm",
      "class": "com.apxor.androidsdk.plugins.realtimeui.ApxorRealtimeUIPlugin"
    },
    {
      "name": "crash",
      "class": "com.apxor.androidsdk.plugins.crash.CrashReporterPlugin"
    },
    {
      "name": "push",
      "class": "com.apxor.androidsdk.plugins.push.PushPlugin"
    },
    {
      "name": "surveys",
      "class": "com.apxor.androidsdk.plugins.survey.SurveyPlugin"
    },
    {
      "name": "wysiwyg",
      "class": "com.apxor.androidsdk.plugins.wysiwyg.WYSIWYGPlugin"
    },
    {
      "name": "jitlog",
      "class": "com.apxor.androidsdk.plugins.jitlog.ApxorJITLogPlugin"
    }
  ]
}

Step 10: Enable uninstall tracking for your users [Optional]

Note

  • If you would like to track uninstalls, you must include apxor-android-sdk-push dependency in app/build.gradle file and corresponding JSON object in assets/plugins.json file

  • Apxor sends silent push notifications to track uninstalls. Please make sure you handle push notifications which will be sent with your SENDER_ID and ignore all notifications other than your SENDER_ID

Apxor uses your firebase server key to send silent push notifications to track uninstalls in order to measure outcomes of your campaign. To enable this please do the following :

Path : app/build.gradle

firebase-messaging version >= 22.0.0

  • Add the following dependency in your app/build.gradle

    dependencies {
  // Add this to track uninstalls and send push notifications from Apxor dashboard
  implementation('com.apxor.androidx:apxor-android-sdk-push-v2:1.2.8@aar') {
    exclude group: 'com.google.firebase'
  }
}

  • Add the following in plugins.json file

    {
  "plugins": [
    {
      "name": "push",
      "class": "com.apxor.androidsdk.plugins.push.v2.PushPlugin"
    }
  ]
}
firebase-messaging version < 22.0.0

  • Add the following dependency in your app/build.gradle

    dependencies {
  // Add this to track uninstalls and send push notifications from Apxor dashboard
  implementation('com.apxor.androidx:apxor-android-sdk-push:1.2.8@aar') {
    exclude group: 'com.google.firebase'
  }
}

  • If you are not using FirebaseMessagingService, you can skip this step. Otherwise, add the following

    public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        // Creating Notification Channel
        ApxorPushAPI.createNotificationChannel(this.getApplicationContext(), "Apxor", "Apxor", "Apxor");
        if (remoteMessage.getFrom().equals(YOUR_FCM_SENDER_ID)) {
            // Push Notification receiver with your Sender Id
        } else {
            // Check if Push Notification received from Apxor
            if (ApxorPushAPI.isApxorNotification(remoteMessage)) {
                ApxorPushAPI.handleNotification(remoteMessage, getApplicationContext());
            } else {
                // Silent or Data push notification which you can send through Apxor dashboard
            }
        }
    }
}

  • Add the following in plugins.json file

    {
  "plugins": [
    {
      "name": "push",
      "class": "com.apxor.androidsdk.plugins.push.PushPlugin"
    }
  ]
}

Read here on how to get your firebase sender ID and also FCM server key to share it with apxor to configure uninstall tracking.

Integrating Apxor Push with @react-native-firebase

Note: You must include com.apxor.androidx:apxor-android-sdk-push-v2 dependency in your app/build.gradle file

Add the following block wherever you have AppRegistry.registerComponent(appName, () => App);. Ideally, it's located in your src/index.js or src/index.tsx.

import messaging from "@react-native-firebase/messaging";
import RNApxorSDK from "react-native-apxor-sdk";

messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  if (!RNApxorSDK.handlePushNotification(remoteMessage)) {
    // To ignore silent push notifications
    if (!remoteMessage.data && !remoteMessage.notification) {
      return;
    }
    console.log("You need to handle this push notification");
  }
});

AppRegistry.registerComponent(appName, () => App);

Step 11: Ensuring ApxorSDK is initialised successfully

We have to verify for two things as follows :

SDK Initialisation

On running your android project lookout for the following log in logcat :

ApxorSDK(v2**) successfully initialized for: APP_ID

Plugin Initialisation

By default, only error logs are enabled. To see debug logs for plugin initialisation and to confirm tracking event triggers, user properties. Please run the below command in terminal

adb shell setprop log.tag.Apxor VERBOSE

Note

Apxor uploads data only when the app is minimized to the background. If you are running from Android Studio (emulators or devices), do not stop the app, just press on the "home" button in order for data to be uploaded.

Step 12: Log data to set up triggers and measure goals

Now as we are done with basic integration, we can go ahead to setup event triggers, capture data for targeting and to personalize messaging.

Please follow the guide here to log user properties, events and event properties.

iOS integration

Integrate Apxor React Native iOS SDK

  • To proceed with iOS integration click here

  • Also, to add the APXWYSIWYGPlugin, add the following to your application's .podspec file

  pod 'Apxor-WYSIWYG', '1.02.65'

iOS SDK Push Notifications

  • To add the APXPushPlugin, add the following to your application's .podspec file

  pod 'Apxor-Push', '1.01.01'

Additional Features API Guide

Click here for guides to log user properties, events and event properties.

PreviousTracking Events and Pages for WebNextCordova

Last updated