SDK Initialization

How to initialize the Upshot.ai React Native SDK in your application.

Overview

You should initialize the Upshot.ai every time the app is launched or app comes to foreground from background. For every initialization you will get authentication status by addListener with UpshotAuthStatus. A session is created every time the SDK is initialized.

Basic Initialization

Initialize the SDK with your app credentials:

JavaScript

import Upshot, { UpshotInitOptions } from "react-native-upshotsdk";

// Initialize SDK in your App.js or index.js
const initializeUpshot = () => {
  const options = {
    [UpshotInitOptions.AppId]: "Application Id given by Upshot.ai",
    [UpshotInitOptions.OwnerId]: "Owner Id given by Upshot.ai",
    [UpshotInitOptions.EnableLocation]: true,
    [UpshotInitOptions.EnableCrashLog]: true,
    [UpshotInitOptions.ExternalStorage]: false,
  };

  // Initialize SDK
  Upshot.initializeUpshotUsingOptions(JSON.stringify(options));

  // Add authentication status listener
  Upshot.addListener("UpshotAuthStatus", handleAuthStatus);
};

const handleAuthStatus = (response) => {
  // response is JSON Object
  console.log("Auth Status:", response);
  if (response.status) {
    console.log("SDK initialized successfully");
  } else {
    console.error("SDK initialization failed:", response.error);
  }
};

// Call in your app's entry point
initializeUpshot();

TypeScript

import Upshot, { UpshotInitOptions } from "react-native-upshotsdk";

interface AuthResponse {
  status: boolean;
  error: string;
}

// Initialize SDK in your App.tsx or index.tsx
const initializeUpshot = (): void => {
  const options = {
    [UpshotInitOptions.AppId]: "Application Id given by Upshot.ai",
    [UpshotInitOptions.OwnerId]: "Owner Id given by Upshot.ai",
    [UpshotInitOptions.EnableLocation]: true,
    [UpshotInitOptions.EnableCrashLog]: true,
    [UpshotInitOptions.ExternalStorage]: false,
  };

  // Initialize SDK
  Upshot.initializeUpshotUsingOptions(JSON.stringify(options));

  // Add authentication status listener
  Upshot.addListener("UpshotAuthStatus", handleAuthStatus);
};

const handleAuthStatus = (response: AuthResponse): void => {
  // response is JSON Object
  console.log("Auth Status:", response);
  if (response.status) {
    console.log("SDK initialized successfully");
  } else {
    console.error("SDK initialization failed:", response.error);
  }
};

// Call in your app's entry point
initializeUpshot();

Configuration Options

Available initialization options and their descriptions:

{
  // Required
  [UpshotInitOptions.AppId]: "Application Id given by Upshot.ai",     // Application ID provided by Upshot.ai (can be viewed on dashboard)
  [UpshotInitOptions.OwnerId]: "Owner Id given by Upshot.ai",         // Account ID provided by Upshot.ai (can be viewed on dashboard)

  // Optional
  [UpshotInitOptions.EnableLocation]: true,        // Enable location tracking (disabled by default)
  [UpshotInitOptions.EnableCrashLog]: true,        // Enable crash log capture (enabled by default)
  [UpshotInitOptions.ExternalStorage]: false       // Enable external storage usage
}

Authentication Status Handling

Add Listener

Add a listener to handle authentication status updates:

// Add listener for authentication status
Upshot.addListener("UpshotAuthStatus", handleAuthStatus);

const handleAuthStatus = (response) => {
  // response is JSON Object
  console.log("Authentication Response:", response);

  if (response.status) {
    // Success: {"error":"","status":true}
    console.log("Authentication successful");
  } else {
    // Error: {"error":"will get error message","status":false}
    console.error("Authentication failed:", response.error);
  }
};

Remove Listener

Remove the authentication status listener when no longer needed:

// Remove listener
Upshot.removeListener("UpshotAuthStatus");

Session Management

Session Creation

A new session is registered every time the SDK is initialized. When the app goes to the background, the session needs to be terminated.

Session Termination

// Terminate the current session
Upshot.terminate();

Important Notes:

• Every successful authentication creates a new session
• Sessions are terminated only when terminate() is called
• Every time initializeUpshot is called, the old session gets terminated and a new session starts
• Avoid multiple duplicate sessions by not initializing the SDK when navigating between screens unless it's a specific business need

App Lifecycle Integration

Foreground Initialization

Initialize the SDK when the app comes to foreground:

import { AppState } from "react-native";

// Handle app state changes
const handleAppStateChange = (nextAppState) => {
  if (nextAppState === "active") {
    // App has come to the foreground
    initializeUpshot();
  } else if (nextAppState === "background") {
    // App has gone to the background
    Upshot.terminate();
  }
};

// Add app state listener
AppState.addEventListener("change", handleAppStateChange);

Component Integration

For React components, you can integrate initialization in useEffect:

import { useEffect } from "react";

const App = () => {
  useEffect(() => {
    // Initialize on component mount
    initializeUpshot();

    // Cleanup on unmount
    return () => {
      Upshot.removeListener("UpshotAuthStatus");
      Upshot.terminate();
    };
  }, []);

  // ... rest of your component
};

Verification

Run Your Application

On Upshot.ai SDK integration success, you can see an active user on the dashboard LiveEvents Section.

Testing Integration

// Test if SDK is properly initialized
const testSDKStatus = () => {
  Upshot.addListener("UpshotAuthStatus", (response) => {
    if (response.status) {
      console.log("✅ SDK is working correctly");
      // You should see this user in the Upshot.ai dashboard
    } else {
      console.error("❌ SDK initialization failed:", response.error);
    }
  });
};

Environment Configuration

Development vs. Production

Use different configurations for development and production:

// Using environment variables or constants
const getInitOptions = () => {
  if (__DEV__) {
    return {
      [UpshotInitOptions.AppId]: "DEV_APP_ID",
      [UpshotInitOptions.OwnerId]: "DEV_OWNER_ID",
      [UpshotInitOptions.EnableLocation]: false, // Disable in development
      [UpshotInitOptions.EnableCrashLog]: true,
      [UpshotInitOptions.ExternalStorage]: false,
    };
  } else {
    return {
      [UpshotInitOptions.AppId]: "PROD_APP_ID",
      [UpshotInitOptions.OwnerId]: "PROD_OWNER_ID",
      [UpshotInitOptions.EnableLocation]: true,
      [UpshotInitOptions.EnableCrashLog]: true,
      [UpshotInitOptions.ExternalStorage]: false,
    };
  }
};

// Initialize with environment-specific config
Upshot.initializeUpshotUsingOptions(JSON.stringify(getInitOptions()));

Best Practices

1. Initialize early in app lifecycle (App.js or index.js)
2. Always add authentication status listener before initialization
3. Handle app state changes for proper session management
4. Terminate sessions when app goes to background
5. Use environment-specific configurations
6. Avoid multiple initializations during app navigation
7. Remove listeners when components unmount

Troubleshooting

Common initialization issues and solutions:

Invalid Credentials

• Verify App ID and Owner ID from Upshot.ai dashboard
• Check environment configuration
• Confirm account status on dashboard

Authentication Failures

• Check network connectivity
• Verify API endpoint accessibility
• Review authentication response error messages
• Ensure proper listener setup before initialization

Session Issues

• Avoid multiple simultaneous sessions
• Always terminate sessions on app background
• Check session timeout configurations
• Monitor active sessions on dashboard