SDK Integration

👍

Supported RN, iOS, Android, and Expo versions

  • Fully supported and tested on React Native v0.68+
  • Fully supported on iOS 13+
  • Fully supported on Android Lollipop (API 21) and later. You can integrate Smartlook on Android Jelly Bean (API 18), however, you will not be able to record user sessions.
  • Fully supported on Expo Development Builds and Expo Prebuild. For more info, see Using Expo with Smartlook.

Installing the Smartlook SDK

The Smartlook React Native SDK fully supports both the new and the old architecture. To begin recording user sessions on your mobiles apps, integrate the SDK.

  1. Install the Smartlook SDK package using npm or yarn:
npm install react-native-smartlook-analytics --save
yarn add react-native-smartlook-analytics
  1. Install the iOS native code components:
cd ios && pod install

🚧

iOS version

The native iOS Smartlook 2.0+ SDK requires iOS 13 as the minimal version. Set platform :ios, '13' in your Podfile to meet this requirement.

📘

Xcodeproject Generated duplicate UUIDs: Warning

If you see this warning while installing the pod install phase on SmartlookAnalytics-Swift.h headers, Smartlook recommends setting install! 'cocoapods', :deterministic_uuids => false in your Podfile. You receive this warning due to the structure of the headers in Smartlook's native frameworks and how they are handled by Cocoapods.

Using Expo with Smartlook

You can use Expo to set up Smartlook in your project.

If you use Expo development builds or Expo prebuild, you do not need a config plugin.

🚧

Expo Go

You cannot use the Expo Go app with a Smartlook project because the Smartlook SDK uses custom native code.

You can now continue to Setting up the Smartlook SDK to complete your Smartlook setup.

If you need to install the Smartlook SDK using a different React Native architecture:

Installing the Smartlook SDK using the old React Native architecture

The library is auto-linked meaning that no additional steps are required.

You can now continue to Setting up the Smartlook SDK to complete your Smartlook setup.

Installing the Smartlook SDK using the new React Native architecture on v0.70+

Make sure your application is set up to work with the new architecture.

Install the Smartlook SDK package using npm or yarn and install the iOS native code components with the new architecture enabled:

cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

The library is auto-linked meaning that no additional steps are required.

You can now continue to Setting up the Smartlook SDK to complete your Smartlook setup.

Installing the Smartlook SDK using the new React Native architecture on v0.68.x or v0.69.x

Make sure your application is set up to work with the new architecture.

Install the Smartlook SDK package using npm or yarn and install the iOS native code components with the new architecture enabled:

cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

Android auto-linking doesn’t work out of the box with the new architecture on RN v0.68.x and v0.69.x. You need to perform the following steps to manually link our TurboModules and Fabric components:

  1. Open the your-application/android/app/build.gradle file and update the file as follows:

        "PROJECT_BUILD_DIR=$buildDir",
        "REACT_ANDROID_DIR=$rootDir/../node_modules/react-native/ReactAndroid",
    -   "REACT_ANDROID_BUILD_DIR=$rootDir/../node_modules/react-native/ReactAndroid/build"
    +   "REACT_ANDROID_BUILD_DIR=$rootDir/../node_modules/react-native/ReactAndroid/build",
    +   "NODE_MODULES_DIR=$rootDir/../node_modules/"
        cFlags "-Wall", "-Werror", "-fexceptions", "-frtti", "-DWITH_INSPECTOR=1"
        cppFlags "-std=c++17"
    
  2. Open the your-application/android/app/src/main/jni/Android.mk file and update the file as follows:

        # If you wish to add a custom TurboModule or Fabric component in your app you
        # will have to include the following autogenerated makefile.
        # include $(GENERATED_SRC_DIR)/codegen/jni/Android.mk
    -   # include $(CLEAR_VARS)
    +
    +   # Includes the MK file for `react-native-smartlook-analytics`
    +
    +   include $(NODE_MODULES_DIR)/react-native-smartlook-analytics/android/build/generated/source/codegen/jni/Android.mk
    +   include $(CLEAR_VARS)
    
  3. In the same file (Android.mk), go to the LOCAL_SHARED_LIBRARIES setting and add the following line:

        libreact_codegen_rncore \
    +   libreact_codegen_SmartlookAnalytics \
        libreact_debug \
    
  4. Open the your-application/android/app/src/main/jni/MainApplicationModuleProvider.cpp file and update the file as follows to enable the Smartlook TurboModule:

    1. Add the import for the turbo module base:

          #include <answersolver.h>
      +   #include <SmartlookAnalytics.h>
      
    2. Add the following check in the MainApplicationModuleProvider constructor:

          // auto module = samplelibrary_ModuleProvider(moduleName, params);
          // if (module != nullptr) {
          //    return module;
          // }
      
      +    auto module = SmartlookAnalytics_ModuleProvider(moduleName, params);
      +    if (module != nullptr) {
      +        return module;
      +    }
      
          return rncore_ModuleProvider(moduleName, params);
      }
      
  5. Open the your-application/android/app/src/main/jni/MainComponentsRegistry.cpp file and update the file as follows to support our Fabric-based Sensitivity view:

    1. Add the import for the component definition descriptor:

          #include <react/renderer/components/answersolver/ComponentDescriptors.h>
      +   #include <react/renderer/components/SmartlookAnalytics/ComponentDescriptors.h>
          #include <react/renderer/components/rncore/ComponentDescriptors.h>
      
    2. Enable the Fabric view in the sharedProviderRegistry constructor:

          auto providerRegistry = CoreComponentsRegistry::sharedProviderRegistry();
      
          // Custom Fabric Components go here. You can register custom
          // components coming from your App or from 3rd party libraries here.
          //
          // providerRegistry->add(concreteComponentDescriptorProvider<
          //        AocViewerComponentDescriptor>());
      +   providerRegistry->add(concreteComponentDescriptorProvider<SmartlookSensitiveViewComponentDescriptor>());
      
          return providerRegistry;
      }
      

Setting up the Smartlook SDK

Enter your unique projectKey and call the start() method to start recording your user sessions. If you do not know your project key, you can find it in the mobile project settings on the Smartlook Dashboard

import Smartlook from 'react-native-smartlook-analytics'

Smartlook.instance.preferences.setProjectKey(
  'your-unique-project-key'
);
Smartlook.instance.start();

To start recording when the user opens the app, call the Smartlook SDK's methods in your App.js/tsx filem or in its useEffect / constructor methods:

import React from 'react';
import { Button, SafeAreaView } from "react-native";
import Smartlook, { Properties } from 'react-native-smartlook-analytics';

Smartlook.instance.preferences.setProjectKey(
  'your-unique-project-key'
);
Smartlook.instance.start();

const SampleApp = () => {
  return (
    <SafeAreaView>
      <Text>This app is now being recorded!</Text>
    	<Button
        title="Magic button"
        onPress={() => {
    			const props = new Properties();
          props.putString('prop1', 'Prop from Magic Button');
          props.putString('prop2', 'Another prop from Magic Button');

          Smartlook.instance.analytics.trackEvent(
            'magic-button-press-event',
            props
          );
				}
      />
    </SafeAreaView>
  );
}

export default SampleApp;

📘

region property

The region property identifies the location of the data center where metadata for your organization is stored. However, this does not ensure that all user data is stored in this region. When implementing the SDK, be sure to input the REGION parameter value as shown in the Smartlook project settings. For more information on where to find your region, see Organization settings.

Smartlook can store metadata in the EU and North America. If you want to change your data storage location, contact Smartlook Sales or Support.

📘

Adaptive frame rate

Due to reported issues with video responsiveness on iOS, we recommend turning off the Adaptive Frame Rate feature, e.g. Smartlook.instance.preferences.setAdaptiveFrameRateEnabled(false);.

Smartlook now records all user sessions in your application. All new user sessions will appear in the Smartlook player.

Troubleshooting

If you see the following messages when installing Smartlook in your app:

  • ⚠️id: Could not find or use auto-linked library 'swiftCompatibility56'
  • ❌id: symbol(s) not found for architecture x86_64

Upgrade to the latest Xcode and/or Xcode Command Line Tools. This error generally occurs if your app does not have fully updated Swift libraries.

Recording when on a mobile network

The Smartlook SDK only uploads sessions when the device is connected to wifi. If you would like to upload your data when the device is on mobile data, you can enable Upload on mobile (cellular) data in project settings. For more information, see When will session recordings appear on my dashboard?

Mobile upload

Third party tools for crash reports

Smartlook recommends that you include debug symbols (dSYMs) from the Smartlook SDK in any third-party tools you use for handling crashes. For more information, see iOS: Crash reports using third-party services.

SDK update & migrations

The Migration guide describes the migration from version 1.x.x to version 2.x.x.