Instalog Expo

An Expo module wrapper for the Instalog analytics and logging SDK, making it easy to integrate Instalog into your Expo applications.

Installation

npm install @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 the Instalog SDK at the beginning of your app:

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

// Initialize with default settings
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 track their activity across sessions:

await Instalog.identifyUser('user123');

Event Logging

Track user actions and events in your app:

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

Feedback Collection

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);
}

For testing, you can simulate a crash:

await Instalog.simulateCrash();

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);

API Reference

Instalog.initialize(key: string, options?: InstalogOptions): Promise<boolean>

Initializes the SDK with your API key and optional configuration.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | isLogEnabled | boolean | false | Enable event logging | | isLoggerEnabled | boolean | false | Enable debug logging | | isCrashEnabled | boolean | false | Enable crash reporting | | isFeedbackEnabled | boolean | false | Enable feedback collection | | autoCaptureCrashes | boolean | true | Automatically capture unhandled JS errors | | errorGrouping | object | (see below) | Configure how errors are grouped and reported |

Error Grouping Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable error grouping | | flushIntervalMs | number | 30000 | Interval to flush error groups (ms) | | errorThreshold | number | 5 | Number of errors to trigger flush | | timeWindowMs | number | 60000 | Time window for grouping errors (ms) | | flushOnBackground | boolean | true | Flush errors when app goes to background | | requireNetwork | boolean | true | Only flush when network is available | | maxErrorsPerGroup | number | 10 | Max errors to store per group | | dynamicFlushInterval | boolean | true | Adjust flush interval based on error volume |

Instalog.identifyUser(userId: string): Promise<boolean>

Identifies the current user.

Instalog.logEvent(event: string, params?: Record<string, any>): Promise<boolean>

Logs an event with optional parameters.

Instalog.showFeedbackModal(): Promise<boolean>

Shows the feedback collection modal.

Instalog.sendCrash(error: string, stack: string): Promise<boolean>

Manually sends a crash report.

Instalog.formatErrorReport(error: Error, errorInfo?: any): string

Formats an error into a structured report for sending.

Instalog.simulateCrash(): Promise<boolean>

Simulates a crash for testing.

Example Application

import { Instalog } from "@instalog.dev/expo";
import React, { useState, useEffect } from "react";
import { StyleSheet, Text, View, TouchableOpacity, SafeAreaView } from "react-native";

export default function App() {
  const apiKey = "YOUR_API_KEY";

  useEffect(() => {
    const initialize = async () => {
      await Instalog.initialize(apiKey, {
        isLogEnabled: true,
        isCrashEnabled: true,
        isFeedbackEnabled: true,
        isLoggerEnabled: true,
      });
      await Instalog.identifyUser("expo_test_user");
    };
    initialize();
  }, []);

  const handleSendEvent = async () => {
    await Instalog.logEvent("button_clicked", {
      timestamp: new Date().toISOString(),
      screen: "demo_screen",
    });
  };

  const handleShowFeedback = async () => {
    await Instalog.showFeedbackModal();
  };

  const handleSimulateCrash = async () => {
    await Instalog.simulateCrash();
  };

  const handleTestGlobalError = () => {
    setTimeout(() => {
      throw new Error("Test Global Error");
    }, 0);
  };

  const handleManualErrorReport = async () => {
    await Instalog.sendCrash(
      "Manual Test Error",
      "This is a stack trace for a manually reported error\nLine 1\nLine 2\nLine 3"
    );
  };

  return (
    <SafeAreaView style={styles.container}>
      <View style={styles.buttonContainer}>
        <TouchableOpacity
          style={styles.button}
          onPress={handleSendEvent}
        >
          <Text style={styles.buttonText}>Send Event</Text>
        </TouchableOpacity>
        
        <TouchableOpacity
          style={styles.button}
          onPress={handleShowFeedback}
        >
          <Text style={styles.buttonText}>Show Feedback</Text>
        </TouchableOpacity>
        
        <TouchableOpacity
          style={styles.button}
          onPress={handleSimulateCrash}
        >
          <Text style={styles.buttonText}>Simulate Crash</Text>
        </TouchableOpacity>
        
        <TouchableOpacity
          style={styles.button}
          onPress={handleTestGlobalError}
        >
          <Text style={styles.buttonText}>Test Global Error</Text>
        </TouchableOpacity>
        
        <TouchableOpacity
          style={styles.button}
          onPress={handleManualErrorReport}
        >
          <Text style={styles.buttonText}>Manual Error Report</Text>
        </TouchableOpacity>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    backgroundColor: "#fff",
  },
  buttonContainer: {
    alignItems: "center",
  },
  button: {
    backgroundColor: "#8860E6",
    padding: 15,
    borderRadius: 8,
    marginVertical: 10,
    width: 200,
    alignItems: "center",
  },
  buttonText: {
    color: "#fff",
    fontWeight: "bold",
  },
});

License

MIT