@sophonz/react-native

React Native bindings for the Sophonz Android and Apple SDKs: startup, global JS error handling, logs, breadcrumbs, sessions, user identity and manual network recording. The full guide is at sophonz.ai/docs/react-native.

Install

npm install @sophonz/[email protected]
# or
yarn add @sophonz/[email protected]

This release binds to these native SDKs. Neither is on a public registry, so the app build needs credentials for both.

| Platform | Artifact | Version | Source | |---|---|---|---| | Android | io.sophonz:sophonz-android-sdk, sophonz-internal-api, sophonz-gradle-plugin | 1.0.0 | GitHub Packages, sophonz-labs/sophonz-android-sdk | | iOS | SophonzIO | 1.0.0 | git tag v1.0.0 of sophonz-labs/sophonz-apple-sdk (CocoaPods or SPM) |

Then either let the Expo config plugin do the native setup, run the setup wizard for a bare React Native app, or do it by hand as described in the guide.

Credentials

The Android SDK and its Gradle plugin are read from GitHub Packages, which requires a token even to read and answers 404 without one. Use a classic token with read:packages from an account that can see sophonz-labs:

# ~/.gradle/gradle.properties
gpr.user=<github user>
gpr.key=<token with read:packages>

On CI, GITHUB_ACTOR and GITHUB_TOKEN are used instead.

SophonzIO is fetched with git from https://github.com/sophonz-labs/sophonz-apple-sdk.git, by CocoaPods or by SPM, so the machine running pod install needs git access to that repository (a credential helper or ~/.netrc).

Expo

{
  "expo": {
    "plugins": [
      [
        "@sophonz/react-native",
        {
          "androidAppKey": "sk_android_...",
          "iOSAppKey": "sk_ios_...",
          "project": "my-project"
        }
      ]
    ]
  }
}

npx expo prebuild

@sophonz/react-native/lib/app.plugin.js is the same plugin under its older path. The props are documented in src/plugin/types.ts and src/plugin/README.md. The plugin adds the GitHub Packages repository, the Gradle plugin and the SophonzIO pod for you; the credentials above are still needed. Expo Go cannot load native modules, use a development build.

Bare React Native

node node_modules/@sophonz/react-native/lib/scripts/setup/installAndroid.js
node node_modules/@sophonz/react-native/lib/scripts/setup/installIos.js
cd ios && pod install

Each asks for the collector URL and that platform's app key. See scripts/setup/README.md.

By hand

Android, in android/build.gradle, add the repository to both buildscript.repositories and allprojects.repositories, and the Gradle plugin to the classpath:

maven {
  url "https://maven.pkg.github.com/sophonz-labs/sophonz-android-sdk"
  credentials {
    username = findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
    password = findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
  }
}

classpath("io.sophonz:sophonz-gradle-plugin:1.0.0")

Then apply plugin: "io.sophonz.gradle" in android/app/build.gradle and create android/app/src/main/sophonz-config.json with sdk_config.ingest.service_key.

iOS, in ios/Podfile inside the app target. SophonzIO is not on the CocoaPods trunk, so name its source:

pod 'SophonzIO', :git => 'https://github.com/sophonz-labs/sophonz-apple-sdk.git', :tag => 'v1.0.0'

Initialize

initialize wires up the JavaScript side. Call it once, as early as possible. If the native SDK was already started (which the Expo plugin and the wizard both do), the sdkConfig passed here is ignored.

import {initialize} from "@sophonz/react-native";

await initialize({
  sdkConfig: {
    ios: {
      collectorUrl: "https://in.sophonz.ai",
      appKey: "sk_...",
      appName: "my-ios-app",
    },
    trackUnhandledRejections: true,
  },
});

Or with the hook:

import {useSophonz} from "@sophonz/react-native";

const {isPending, isStarted} = useSophonz({
  ios: {collectorUrl: "https://in.sophonz.ai", appKey: "sk_..."},
});

Android takes no runtime configuration: the collector URL and service key are compiled in from android/app/src/main/sophonz-config.json by the Gradle plugin.

On iOS the identity is resolved natively, first match wins: collectorUrl + appKey from JavaScript, Sophonz-Info.plist in the app bundle, then exporters only (with @sophonz/react-native-otlp). With none of them the start fails and initialize resolves false.

Sourcing the Apple SDK from SPM

CocoaPods is the default. To use Swift Package Manager (React Native 0.75+, dynamic frameworks):

SOPHONZ_USE_SPM=1 USE_FRAMEWORKS=dynamic pod install

With Expo, set iOSUseSPM: true and add expo-build-properties with ios.useFrameworks: "dynamic".

Platform differences

| API | Android | iOS | |---|---|---| | setUsername, setUserEmail and their clear* | supported | resolves false, the Apple SDK has no such field | | getCurrentSessionId | user session id | user session id | | setReactNativeVersion, setJavaScriptPatch | resource attributes | process-lifespan properties | | unhandled JS exception | typed React Native crash log | ERROR log carrying exception.* |

getCurrentSessionId returns 32 lowercase hex characters on both platforms, the same value that goes on the wire as session.id.