Luciq for React Native

Luciq is the Agentic Observability Platform built for Mobile.

Our intelligent AI agents help you capture rich, contextual data for every issue, including full session replays, console logs, and detailed network requests, to proactively detect, prioritize, and resolve problems automatically. From traditional bug reporting to proactive resolution, Luciq equips you with the building blocks to your app’s success.

Ship faster, deliver frustration-free user sessions, and focus on building what matters.

For more info, visit Luciq.ai.

Installation

1. In Terminal, navigate to your React Native directory and install the @luciq/react-native package:

   npm install @luciq/react-native

   Or if you prefer to use Yarn instead of npm:

   yarn add @luciq/react-native

2. if you are using expo you need to add @luciq/react-native plugin to app.json:

      "plugins" : [
         [
           "@luciq/react-native",
           {
              // optional that add Mic,Photo permission on iOS and FOREGROUND_SERVICE_MEDIA_PROJECTION on android
             "addScreenRecordingBugReportingPermission": true
           }
         ]
   ]

3. CocoaPods on iOS needs this extra step:

   cd ios && pod install && cd ..

Initializing Luciq

To start using Luciq, import it as follows, then initialize it in the constructor or componentWillMount. This line will let the SDK work with the default behavior. The SDK will be invoked when the device is shaken. You can customize this behavior through the APIs.

import Luciq from '@luciq/react-native';

Luciq.init({
  token: 'APP_TOKEN',
  invocationEvents: [Luciq.invocationEvent.shake],
});

You can find your app token by selecting the SDK tab from your Luciq dashboard.

Microphone and Photo Library Usage Description (iOS Only)

Luciq needs access to the microphone and photo library to be able to let users add audio and video attachments. Starting from iOS 10, apps that don’t provide a usage description for those 2 permissions would be rejected when submitted to the App Store.

For your app not to be rejected, you’ll need to add the following 2 keys to your app’s info.plist file with text explaining to the user why those permissions are needed:

• NSMicrophoneUsageDescription
• NSPhotoLibraryUsageDescription

If your app doesn’t already access the microphone or photo library, we recommend using a usage description like:

• "<app name> needs access to the microphone to be able to attach voice notes."
• "<app name> needs access to your photo library for you to be able to attach images."

The permission alert for accessing the microphone/photo library will NOT appear unless users attempt to attach a voice note/photo while using Luciq.

Uploading Source Map Files for Crash Reports

For your app crashes to show up with a fully symbolicated stack trace, we will automatically generate the source map files and upload them to your dashboard on release build. To do so, we rely on your app token being explicitly added to Luciq.init({token: 'YOUR_APP_TOKEN'}) in JavaScript.

If your app token is defined as a constant, you can set an environment variable LUCIQ_APP_TOKEN to be used instead. We also automatically read your versionName and versionCode to upload your sourcemap file. alternatively, can also set the environment variables LUCIQ_APP_VERSION_NAME and LUCIQ_APP_VERSION_CODE to be used instead.

To disable the automatic upload, you can set the environment variable LUCIQ_SOURCEMAPS_UPLOAD_DISABLE to TRUE.

Network Logging

Luciq network logging is enabled by default. It intercepts any requests performed with fetch or XMLHttpRequest and attaches them to the report that will be sent to the dashboard. To disable network logs:

import { NetworkLogger } from '@luciq/react-native';

NetworkLogger.setEnabled(false);

Repro Steps

Luciq Repro Steps are enabled by default. It captures a screenshot of each screen the user navigates to. These screens are attached to the BugReport when sent.

We support the two most popular React Native navigation libraries:

• react-navigation

  • v5 set the onStateChange to Luciq.onStateChange in your NavigationContainer as follows:

    <NavigationContainer onStateChange={Luciq.onStateChange} />

  • <=v4 set the onNavigationStateChange to Luciq.onNavigationStateChange in your App wrapper as follows:

    export default () => <App onNavigationStateChange={Luciq.onNavigationStateChange} />;

• react-native-navigation

  Register luciq.aiponentDidAppearListener listener using:

  Navigation.events().registerComponentDidAppearListener(luciq.aiponentDidAppearListener);

Alternatively, you can report your screen changes manually using the following API

Luciq.reportScreenChange('screenName');

You can disable Repro Steps using the following API:

Luciq.setReproStepsConfig({ all: ReproStepsMode.disabled });

Custom Spans

Custom spans allow you to manually instrument arbitrary code paths for performance tracking. This feature enables tracking of operations not covered by automatic instrumentation.

Starting and Ending a Span

import { APM } from '@luciq/react-native';

// Start a custom span
const span = await APM.startCustomSpan('Load User Profile');

if (span) {
  try {
    // Perform your operation
    await loadUserProfile();
  } finally {
    // Always end the span, even if operation fails
    await span.end();
  }
}

Recording a Completed Span

const start = new Date();
// ... operation already completed ...
const end = new Date();

await APM.addCompletedCustomSpan('Cache Lookup', start, end);

Important Notes

• Span Limit: Maximum of 100 concurrent spans at any time
• Name Length: Span names are truncated to 150 characters
• Validation: Empty names or invalid timestamps will be rejected
• Idempotent: Calling span.end() multiple times is safe
• Feature Flags: Spans are only created when SDK is initialized, APM is enabled, and custom spans feature is enabled

API Reference

APM.startCustomSpan(name: string): Promise<CustomSpan | null>

Starts a custom span for performance tracking.

Parameters:

• name (string): The name of the span. Cannot be empty. Max 150 characters.

Returns:

• Promise<CustomSpan | null>: The span object to end later, or null if the span could not be created.

Example:

const span = await APM.startCustomSpan('Database Query');
if (span) {
  // ... perform operation ...
  await span.end();
}

CustomSpan.end(): Promise<void>

Ends the custom span and reports it to the SDK. This method is idempotent.

APM.addCompletedCustomSpan(name: string, startDate: Date, endDate: Date): Promise<void>

Records a completed custom span with pre-recorded timestamps.

Parameters:

• name (string): The name of the span. Cannot be empty. Max 150 characters.
• startDate (Date): The start time of the operation.
• endDate (Date): The end time of the operation (must be after startDate).

Example:

const start = new Date(Date.now() - 1500);
const end = new Date();
await APM.addCompletedCustomSpan('Background Task', start, end);

Documentation

For more details about the supported APIs and how to use them, check our Documentation.