Installation

npm i @instalog.dev/expo

Expo Config Plugin

This package auto-installs necessary native dependencies for Expo projects.

Android Configuration

For Android, make sure to add the Instalog Feedback Activity to your AndroidManifest.xml:

<activity
  android:name="dev.instalog.mobile.feedback.InstalogFeedbackActivity"
  android:label="Instalog"
  android:theme="@style/Theme.Instalog" />

This should be placed inside the <application> tags of your manifest file.

Usage

Initialization

Initialize Instalog at the beginning of your app, typically in your main App file:

import { Instalog } from '@instalog.dev/expo';

// Initialize with default options
await Instalog.initialize('YOUR_API_KEY');

// Or with custom options
await Instalog.initialize('YOUR_API_KEY', {
  isLogEnabled: true,
  isCrashEnabled: true,
  isFeedbackEnabled: true,
  isLoggerEnabled: false, // Debug logging
  autoCaptureCrashes: true, // Automatically capture unhandled JS errors
  errorGrouping: {
    enabled: true,
    flushIntervalMs: 30000, // 30 seconds
    errorThreshold: 5,
    timeWindowMs: 60000, // 1 minute
    flushOnBackground: true,
    requireNetwork: true,
    maxErrorsPerGroup: 10,
    dynamicFlushInterval: true,
  }
});

// Identify your user after initialization
await Instalog.identifyUser("user123");

User Identification

Identify your users to associate logged events and crashes with specific users:

await Instalog.identifyUser('user_id_or_email');

Event Logging

Log specific events with optional properties:

await Instalog.logEvent('button_clicked', {
  button_name: 'submit',
  screen: 'login',
});

User Feedback

Show a feedback modal to collect user feedback:

await Instalog.showFeedbackModal();

Crash Reporting

Crash reporting is automatically enabled after initialization. The SDK can automatically capture unhandled JavaScript errors when autoCaptureCrashes is enabled (default).

You can also manually report crashes:

try {
  // Your code that might throw an exception
} catch (error) {
  await Instalog.sendCrash('Error name', error.stack || error.toString());
}

For more structured error reporting, you can use the formatErrorReport helper:

try {
  // Your code that might throw an exception
} catch (error) {
  const formattedError = Instalog.formatErrorReport(error, errorInfo);
  await Instalog.sendCrash('Caught Error', formattedError);
}

Global Error Handling

The SDK automatically sets up global error handling when initialized with autoCaptureCrashes: true (default). This captures unhandled JavaScript errors and reports them to Instalog.

You can test this functionality with:

// This will trigger the global error handler
setTimeout(() => {
  throw new Error("Test Global Error");
}, 0);

Test/Debug Methods

// Simulate a crash for testing
await Instalog.simulateCrash();

Advanced Configuration

Error Grouping

Instalog can group similar errors together to reduce noise in your error reports:

// Configure error grouping during initialization
await Instalog.initialize('YOUR_API_KEY', {
  errorGrouping: {
    enabled: true,                // Enable error grouping
    flushIntervalMs: 30000,       // Check for group flushes every 30 seconds
    errorThreshold: 5,            // Send after 5 occurrences of similar errors
    timeWindowMs: 60000,          // Send after 1 minute regardless of count
    flushOnBackground: true,      // Flush when app goes to background
    requireNetwork: true,         // Only send reports when network is available
    maxErrorsPerGroup: 10,        // Store at most 10 errors per group
    dynamicFlushInterval: true,   // Adjust flush intervals based on error frequency
  },
});

Common Issues

  1. SDK Not Initialized

    • Make sure to await the initialize call
    • Verify your API key is correct
  2. Missing Error Reports

    • Check that isCrashEnabled is set to true
    • Verify network connectivity
  3. Expo Config Plugin Issues

    • Ensure you’ve properly configured the plugin in your app.json
    • Run expo prebuild --clean to ensure the plugin is applied

For additional support, please contact [email protected].

API Reference

Instalog

MethodDescription
initialize(key, options)Initializes the SDK with your API key and optional configuration
identifyUser(userId)Identifies the current user
logEvent(event, params)Logs an event with optional parameters
sendCrash(error, stack)Manually sends a crash report
showFeedbackModal()Shows the feedback collection modal
simulateCrash()Simulates a crash for testing
formatErrorReport(error, errorInfo)Formats an error into a structured report for sending

Options

OptionTypeDefaultDescription
isLogEnabledbooleanfalseEnable event logging
isLoggerEnabledbooleanfalseEnable debug logging
isCrashEnabledbooleanfalseEnable crash reporting
isFeedbackEnabledbooleanfalseEnable feedback collection
autoCaptureCrashesbooleantrueAutomatically capture unhandled JS errors
errorGroupingobjectSee belowConfigure how errors are grouped and reported

Error Grouping Options

OptionTypeDefaultDescription
enabledbooleantrueEnable error grouping
flushIntervalMsnumber30000Interval to flush error groups (ms)
errorThresholdnumber5Number of errors to trigger flush
timeWindowMsnumber60000Time window for grouping errors (ms)
flushOnBackgroundbooleantrueFlush errors when app goes to background
requireNetworkbooleantrueOnly flush when network is available
maxErrorsPerGroupnumber10Max errors to store per group
dynamicFlushIntervalbooleantrueAdjust flush interval based on error volume