React Native

Prerequisites

Please have the following handy before beginning the integration:

• Application identifier generated on the Apxor dashboard for your app (Read more on how to fetch the application identifier from Apxor dashboard)

• App Bundle Id : Every app has a unique application ID that looks like com.example.myapp. This id uniquely identifies the app on the device and also on the app store. (Know more about bundle ids here)

• The list of events to setup triggers and track goals, user properties that allows to personalize messages and to target better. (Read more on how you can setup here)

React Native Integration

Check here the latest release notes.

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

Android Integration

Step 1: 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 2: Add dependencies

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

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

2.1 ApxorSDK dependencies (mandatory)

dependencies {
//...

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


    // Add these for Realtime Actions and Surveys
    implementation 'com.apxor.androidx:apxor-android-sdk-qe:1.8.1@aar'
    implementation 'com.apxor.androidx:apxor-android-sdk-rtm:2.6.1@aar'
    implementation 'com.apxor.androidx:surveys:2.2.1@aar'


    // Helper plugin to create walkthroughs
    implementation 'com.apxor.androidx:wysiwyg:1.6.3@aar'
    
    // Add the below two dependencies to establish an SSE connection for WYSIWYG
    implementation 'com.squareup.okhttp3:okhttp:4.9.0'
    implementation 'com.launchdarkly:okhttp-eventsource:2.5.0'
    
//...
}

2.2 Add exoplayer in your app (optional)

Add exoplayer in your app

Exoplayer enables you to configure Picture In Picture videos from the Apxor dashboard; if you are already using the exoplayer in your app, this step is not needed; otherwise, add the following dependency in the application build.gradle file. To use video pip templates, this is necessary.

For com.apxor.androidx:apxor-android-sdk-rtm:2.3.6@aar version onwards

dependencies {
  //... 

  implementation 'androidx.media3:media3-exoplayer:1.1.1'
  implementation 'androidx.media3:media3-ui:1.1.1'


  //...
  }

For com.apxor.androidx:apxor-android-sdk-rtm:2.3.5@aar and below

dependencies {
  //... 

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

  //...
  }

2.3 Enable uninstall tracking for your users (optional)

Enable uninstall tracking for your users

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

For Firebase Version < 22.0.0

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

Please handle the notifications like 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
            }
        }
    }
}

For Firebase Version >= 22.0.0

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

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

After completing the expandable section, integrate Apxor Push with @react-native-firebase

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 3: 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 4: Disable Dexing Artifact Transformation

Note

In Android Gradle Plugin 3.5.0, we use Gradle artefact transforms for desugaring and dexing, enabling greater parallelism and caching. This process depends on libraries having accurate Maven information since dependencies specified in POM files are used to set up the desugaring classpath. If we encounter issues with missing dependencies during desugaring, it's necessary to disable parallel transformation to facilitate the process by adding the following property:

Add the following to gradle.properties file

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

android.enableDexingArtifactTransform = false

Step 5: 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

You are all set: Verify your SDK integration

We have to verify for two things as follows :

SDK Initialization

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

ApxorSDK(v2**) successfully initialized for: APP_ID

Plugin Initialization

By default, only error logs are enabled. To see debug logs for plugin initialization 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.

iOS Integration

Step 1: Initialize Apxor iOS SDK

Auto initialize SDK (Recommended)

1. Add the following inside your application plist file.

1. Open your application's Info.plist as source code.

1. Copy paste the below piece of code, to create an entry for ApxorSDK

<key>Apxor</key>
<dict>
    <key>Core</key>
    <string>YOUR_APP_ID</string>
    <key>APXSurveyPlugin</key>
    <true/>
    <key>APXRTAPlugin</key>
    <true/>
    <key>APXPushPlugin</key>
    <true/>
    <key>APXWYSIWYGPlugin</key>
    <true/>
    // other plugins which you are using
</dict>

1. To add the APXWYSIWYGPlugin, add the following to your application's .podspec file:

pod 'Apxor-WYSIWYG', '1.02.68'

Note

• If you are unable to find our plugins in your pods, then dopod update

Manually initialize SDK

1. Call ApxorSDK.initialize method in your Application class

//...
#import "ApxorSDK/ApxorSDK.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    [ApxorSDK initializeApxorWithID:@"<YOUR_APP_ID>"];
    // ... your code
}

1. Open your application's Info.plist as source code.

1. Copy paste the below piece of code, to create an entry for ApxorSDK.

<key>Apxor</key>
<dict>
    <key>APXSurveyPlugin</key>
    <true/>
    <key>APXRTAPlugin</key>
    <true/>
    <key>APXPushPlugin</key>
    <true/>
    <key>APXWYSIWYGPlugin</key>
    <true/>
    // other plugins which you are using
</dict>

Note

To get your app ID, please email us at [e-mail] or contact your assigned CSM

Configuring Test Device

• First, you need to configure your app to ensure there is a URL Scheme with your application's bundle identifier as the value.

• If your app already has a URL Scheme with your application's bundle identifier as the value, you can skip this step.

Configure URL Scheme

• To configure URL scheme, go to your project settings, select Targets. Click on the Info tab.

• Select the URL Types, and click on the + button to add a new URL Scheme.

• Add a new URL Scheme with your bundle identifier as the value.

• Your bundle identifier will be in the format, com.xxxx.xxxx

• Use the image below for reference.

Note

Make sure the URL scheme has the value of your bundle identifier that was provided in the dashboard while registering with us. Also, the app must have same bundle identifier.

Handling the deep link

Using AppDelegate

• You'd need to enable Apxor to handle Apxor specific deeplinks.

• In your application's AppDelegate file, in the function application(_:open:options:), add the following code at the beginning,

// ObjC
NSString *urlStr = url.absoluteString;
if ([urlStr containsString:@"add-test-device"]) {
  [ApxorSDK handleDeeplink:url];
}

// Swift
/*
  Apxor's code to handle deeplinks
  */
let urlStr = url.absoluteString
if (urlStr.contains("add-test-device")) {
    ApxorSDK.handleDeeplink(url)
}

• This will ensure the Apxor specific deep links are handle by our SDK.

Using SceneDelegate

• You'd need to enable Apxor to handle Apxor specific deeplinks.

• In your application's SceneDelegate file, add the following code at the beginning,

// ObjC
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
  for(UIOpenURLContext *x in URLContexts) {
    NSURL *url = x.URL;
    if([[url absoluteString] containsString:@"add-test-device"])
    {
      [ApxorSDK handleDeeplink:url];
    }
    break;
  }
}

// Swift
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
  let url = URLContexts.first?.url
  let urlStr = url?.absoluteString
  if (urlStr!.contains("add-test-device")) {
    ApxorSDK.handleDeeplink(url!)
  }
}

You are all set: Verify your SDK Integration

Lookout for the following log

Add-Ons

Now that you have completed the basic integration, you can proceed to set up event triggers, capture data for targeting, add slots for embed cards and stories, and personalize messaging. Include the following sections as needed.

Note

Add the following import statement in every component where you use Apxor APIs

import RNApxorSDK from "react-native-apxor-sdk";

Identifying Users

This section is mandatory if you intend to use Segments and Cohorts.

The Apxor SDK automatically captures device IDs and this is used to identify users uniquely by Apxor. Apart from this, you can log a custom user identifier that you use to uniquely identify users in your app.

This identifier would be very instrumental especially when exporting data of a certain campaign or survey to your analytics system to create a cohort and measure the results of the campaign.

Similarly, when you are importing data to Apxor from your system that your marketing/product / data science team has identified and wants to run campaigns specifically to them the custom user identifier will serve as the bridge to communicate between your systems and Apxor effectively.

Here is how you can set your user identifier for Apxor to recognize your users :

// Syntax
RNApxorSDK.setUserIdentifier("STRING");

// Example
RNApxorSDK.setUserIdentifier("<unique_user_id>");

Log events and user data for Targeting, Triggering and goal Tracking

The product/marketing or the growth team lists out the use cases with an idea of when to launch and to whom to launch. To do this we need to capture data in the form of events. Let us consider the following use case as an example :

App Events​

In the above scenario, we want to trigger the campaign for users who have spent 'x' seconds and haven't tapped on a product. To understand that if the user has tapped the product we should log an event along with its attributes as follows to capture data:

Similarly if you want to send promotions to users who have viewed at least five products of the category shoes in the last three days or you want to measure how many people added an item to a cart from the campaign as a goal all this information is captured in the form of events.

These types of events are classified as app events - the data that is transferred to the servers at Apxor where you can segment users based on historic behaviour or measure your goals as specified above.

Here is how we track app events :

// Syntax
RNApxorSDK.logAppEvent(event_name, properties);

// Example
RNApxorSDK.logAppEvent("ADD_TO_CART", {
  userId: "[e-mail]",
  value: 1299,
  item: "Sony Head Phone 1201",
});

Client Events​

In the below scenario, let's assume you want to launch a survey when the soft back button is pressed asking the user for product feedback. In this, we don't need to capture the data of how many people pressed the back button which is useless and it bloats your event storage as it is a high-frequency event which increases your cost unnecessarily. This data point doesn't potentially answer any of your product questions and hence there is no ROI in storing data from this event.

So for such scenarios where we need the behavioral data to launch a campaign or to collect feedback, which doesn't provide ROI on storing for measuring goals, answering your product questions or segmenting your target audience, we log these events as Client Events which involves zero transfer of data and is used only to set up your triggers on behavioral information from the user.

// Syntax
RNApxorSDK.logClientEvent(event_name, properties);

// Example
RNApxorSDK.logClientEvent("ADD_TO_CART", {
  userId: "[e-mail]",
  value: 1299,
  item: "Sony Head Phone 1201",
});

User Attributes

We can personalize the messaging copy in the experiences we build for the user or target based on his persona using information that is centric to individual users. Let us consider the following example where we know the user is an English with Gold membership.

This information helps to tailor content in English to that specific user and gives us the flexibility to different messaging to different membership tiers. This is how the information captured here is used for segmenting.

Similarly capturing attributes like Name can help to personalize your message copy where it reads Hi {username} can't find your product? where the username is replaced by the attribute value of the property from the nudges dashboard along with providing meaningful defaults in their absence.

This is how you log user information to Apxor :

// Syntax
RNApxorSDK.setUserCustomInfo(properties);

// Example
RNApxorSDK.setUserCustomInfo({
  Age: 10,
  Name: "John Wick",
});

Track Screen

In the scenario discussed in this guide, how will we know if the user has spent thirty seconds on the home screen and did not click on the product? For this reason, it is important to use track the screens to set them up as triggers and also to capture the time spent on the screens.

By using the following API to track the screens in the app you can setup campaigns on inactivity or time spent on those screens:

RNApxorSDK.trackScreen("HomeScreen");

Track Navigation

If you are already using a navigation library like @react-navigation, please follow below mentioned steps for Apxor SDK to automatically track screen navigation

import { useNavigationContainerRef } from "@react-navigation/native"

const navigationRef = useNavigationContainerRef()

return (
  <NavigationContainer
    ref={navigationRef}
    onReady={() => {
      const currentRoute = navigationRef?.current?.getCurrentRoute()
      if (currentRoute) {
        RNApxorSDK.trackScreen(currentRoute.name)
      }
    }}
    onStateChange={() => {
      const currentRoute = navigationRef?.current?.getCurrentRoute()
      if (currentRoute) {
        RNApxorSDK.trackScreen(currentRoute.name)
      }
    }}
  >
   // your screens and navigators
  </NavigationContainer>
)

Note

1. You will need it on both onReady and onStateChange as the SDK needs to log navigation events on the initial app launch and also on futher navigations between screens.

2. The NavigationContainer need not be straight from @react-navigation. It can be from any 3rd party wrapper around NavigationContainer (like BugSnag)

Otherwise use the following API to track navigations on every screen/route change

// Syntax
RNApxorSDK.logNavigationEvent(screen_name);

// Example
RNApxorSDK.logNavigationEvent("LoginScreen");

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.

Embed and Story Slot

Add Embed Card Slot

Note

For using Embed Cards, the versions of the following plugins should be greater than or equal to the ones mentioned below

Android

Core: 3.1.0

qe: 1.7.5

rtm: 2.4.8

WYSIWYG: 1.5.6

react-native-rtm: 1.6.2

react-native-apxor-sdk: 1.7.4

iOS

Core: 2.10.26

CE: 1.05.16

RTA: 1.09.26

WYSIWYG: 1.02.67

react-native-rtm: 1.6.2

react-native-apxor-sdk: 1.7.4

In all areas of the app where you may want to show an in-line widget, insert the following code

<ApxorWidget cardID = {<Tag>}/>

Rename <Tag> to any unique ID (any positive Integer). Ensure that you keep the ID unique across different IDs and across different Apxor-Widget instances.

Add Story Slot

Note

For using Apxor Stories, the versions of the following plugins should be greater than or equal to the ones mentioned below

Android

Core: 3.1.0

qe: 1.7.5

rtm: 2.4.8

WYSIWYG: 1.5.6

react-native-rtm: 1.6.2

react-native-apxor-sdk: 1.7.4

iOS

Core: 2.10.26

CE: 1.05.16

RTA: 1.09.26

WYSIWYG: 1.02.67

react-native-rtm: 1.6.2

react-native-apxor-sdk: 1.7.4

In all areas of the app where you may want to show stories, insert the following code

<ApxorStoryWidget storiesID= {<ID>} />

Replace <ID> with any unique integer(any positive Integer). Ensure that you keep the ID unique across different ApxorStoryWidget instances.

Handle custom redirection using Key-Value pairs

If your app wants to redirect users based on simple key-value pairs instead using Deeplink URLs or Activity, you can follow below approach

import android.app.Application;
import com.apxor.androidsdk.core.ApxorSDK;
import com.apxor.androidsdk.core.RedirectionListener;

import org.json.JSONArray;

public class MyApplication extends Application {
  @Override
  public void onCreate() {

    // Register a redirection listener ONLY ONCE in your app
    // If you register in multiple places, ONLY the last value will be available.
    // Whenever you register a new one, it will override the existing listener
    Apxor.setRedirectionListener(new RedirectionListener() {
      @Override
      public void onActionComplete(JSONArray keyValuePairs) {
        int length = keyValuePairs.length();

        /**
         * [
         *      {
         *          "name": "YourKey",
         *          "value": "YourValue"
         *      },
         *      ....
         * ]
         */
        try {
          for (int i = 0; i < length; i++) {
            JSONObject pair = keyValuePairs.getJSONObject(i);
            String key = pair.getString("name");
            // Values are always String type. You need to convert based on your need
            String value = pair.getString("value");

            // Your logic continues from here
          }
        } catch (JSONException e) {

        }
      }
    });
  }
}

Handle Deeplinks

Follow the instructions given in here to enable deeplinks in your application.

Whenever Apxor React Native SDK sends the deeplink URL to the app, the following callback will be executed and you have to interpret the URL and navigate the user to the necessary page or tab.

Add the following code snippet in your root component to handle deeplink URLs

import { Linking } from "react-native";

function YourRootComponent(props) {
  // Use `componentDidMount` for Class components
  useEffect(() => {
    Linking.addEventListener("url", (event) => {
      const { url } = event;

      // Your custom function which interprets the URL
      // and redirect users to the necessary page or tab
      handleDeeplinkURL(url);
    });
  }, []);
}

Yeah! You are ready to create your first Campaign or Survey