4. Initialization

This document refers to deprecated parts of the platform and has been left intact to help customers with legacy integrations. In order to access the latest platform features and documentation, please go to https://docs.sentiance.com.

Initializing the Sentiance SDK creates the native components necessary to do proper detections. The first SDK initialization additionally creates a unique Sentiance user on the device, identified by a Sentiance user ID. During the initialization process, this Sentiance user can be linked to your app-specific user on the Sentiance platform, making sure that you can properly track your users across both platforms. Additionally, linking allows your users to migrate to new devices, or reinstall your app without losing any historical data. Check our comprehensive user linking guide to find out more about how this works.

To make user linking possible, we provide a React Native method to initialize the SDK in your javascript code. However, since the Sentiance SDK can run in the background without any user interaction, we also require that you initialize the SDK natively during app startup.

Native Initialization

In order for SDK detections to work in the background, you must initialize the Sentiance SDK natively during app startup. Doing so ensures that Sentiance can properly detect the user's activity even when the user does not have your app open.

We initialize the SDK natively only after a previous React Native initialization was successfully complete. This makes sure that our first SDK initialization happens in React Native, allowing us to perform user linking.

iOS

The correct way to natively initialize on iOS is to do it inside the didFinishLaunchingWithOptions method of the AppDelegate class.

...
#import <RNSentiance.h> // Import Sentiance React Native bridge module

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

  RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:launchOptions];
  RCTRootView *rootView = [[RCTRootView alloc] initWithBridge:bridge
                                                   moduleName:@"ReactNativeApp"
                                            initialProperties:nil];

  // Read SENTIANCE_APP_ID and SENTIANCE_APP_SECRET from any safe source
  NSString * SENTIANCE_APP_ID = @"";
  NSString * SENTIANCE_APP_SECRET = @"";

  // Check if native initialization is enabled. In your JS code, there's an equivalent
  // setter that you can use to enable it, after successfully initializing the SDK there.
  BOOL isNativeInitializationEnabled = [[bridge moduleForName:@"RNSentiance"] isNativeInitializationEnabled];
  
  if (isNativeInitializationEnabled) {
    // initialize the SDK
    [[bridge moduleForName:@"RNSentiance"] initSDK:SENTIANCE_APP_ID secret:SENTIANCE_APP_SECRET baseURL:nil shouldStart:YES resolver:nil rejecter:nil];
  }
  
  ...

  return YES;
}
...

Android

The correct way to natively initialize on Android is to do it inside the onCreate() method of the Application class.

...
import com.sentiance.react.bridge.RNSentianceHelper;

public class MainApplication extends Application implements ReactApplication {

  @Override
  public void onCreate() {
    super.onCreate();
    ...
    
    String SENTIANCE_APP_ID = "";
    String SENTIANCE_APP_SECRET = "";

    RNSentianceHelper rnSentianceHelper = RNSentianceHelper.getInstance(getApplicationContext());
  
    // Check if native initialization is enabled. In your JS code, there's an equivalent
    // setter that you can use to enable it, after successfully initializing the SDK there.
    boolean isNativeInitializationEnabled = rnSentianceHelper.isNativeInitializationEnabled();
    
    if (isNativeInitializationEnabled) {
      // initialize the SDK
      rnSentianceHelper.initializeSentianceSDK(
              SENTIANCE_APP_ID,
              SENTIANCE_APP_SECRET,
              true, // auto start
              null, // init callback
              null // start callback
      );
    }
  }

  ...
}

React Native Initialization

Having implemented the native SDK initialization, we're now ready to implement the React Native SDK initialization.

Initializing the SDK in React Native should normally happen only once, when the Sentiance SDK will be initialized for the first time. This first initialization creates a Sentiance user on the device, and allows you to link your app-specific user to this Sentiance user.

async initSDK() {
  const sdkNotInitialized = await RNSentiance.getInitState() === "NOT_INITIALIZED";

  if (sdkNotInitialized) {
    const appId = "";
    const appSecret = "";

    // Before initializing, subscribe to receive the user linking event.
    subscribeSDKEvents();

    // Initialize the SDK.
    await RNSentiance.initWithUserLinkingEnabled(
      appId,
      appSecret,
      null,
      true
    );

    // Now that initialization has succeeded, enable native initialization so
    // that the SDK is initialized from the native code upon next app startup.
    await RNSentiance.enableNativeInitialization();
  }
  ...
}

Notice that we enable the native SDK initialization after we successfully initialize the SDK, by calling RNSentiance.enableNativeInitialization(). This will result in the isNativeInitializationEnabled check we added in the native code to succeed next time.

When you reset the Sentiance SDK, native initalization will be automatically disabled, so you don't need to manually call RNSentiance.disableNativeInitialization().

In the above snippet, while initWithUserLinkingEnabled executes, the Sentiance SDK will publish an SDKUserLink event allowing you to perform user linking.

const rnSentianceEmitter = new NativeEventEmitter(RNSentiance);

subscribeSDKEvents() {
  this.userLinkListener = rnSentianceEmitter.addListener(
    "SDKUserLink",
    id => {
      const { installId } = id;
      this.linkMetaUser(installId);
    }
  );
}

async linkMetaUser(installId) {
  // Supply the 'installId' to your server, which should then initiate
  // a user linking request with the Sentiance backend.
  ...
  
  // Inform the Sentiance SDK about the user linking result.
  RNSentiance.userLinkCallback(success);
}

The RNSentiance.userLinkCallback(boolean) call is important. Without it, the Sentiance SDK will not complete the initialization. If linking succeeds, this SDKUserLink event does not get emitted during subsequent SDK initializations, unless the SDK gets reset.