HeronSignal React Native

React Native SDK for sending mobile app screens, business events, logs, and errors to HeronSignal.

Use it when you want HeronSignal to understand what happens inside your mobile app, not only your website.

Install

npm install @heronsignal/react-native

or:

yarn add @heronsignal/react-native

Android setup

The React Native package uses the HeronSignal Android SDK under the hood. Add JitPack to your Android repositories.

In android/settings.gradle or android/settings.gradle.kts:

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven("https://jitpack.io")
  }
}

Then rebuild the app:

npx react-native run-android

Expo note

This package uses a native module. It is intended for React Native bare apps or Expo development builds.

It will not work inside Expo Go until a config plugin is added.

Initialize once

Initialize HeronSignal when your app starts.

import { useEffect } from "react";
import { HeronSignal } from "@heronsignal/react-native";

export function App() {
  useEffect(() => {
    HeronSignal.init({
      publicKey: "pk_your_workspace_key",
      appVersion: "1.0.0",
      environment: "production",
    });
  }, []);

  return null;
}

Track screens

Screens are the mobile equivalent of pages.

import React, { useEffect } from "react";
import { HeronSignal } from "@heronsignal/react-native";

export function PricingScreen() {
  useEffect(() => {
    HeronSignal.screen("Pricing");
  }, []);

  return null;
}

With React Navigation:

import React, { useEffect } from "react";
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import { HeronSignal } from "@heronsignal/react-native";

export function App() {
  const navigationRef = useNavigationContainerRef();
  const routeNameRef = React.useRef<string | undefined>();

  useEffect(() => {
    HeronSignal.init({
      publicKey: "pk_your_workspace_key",
      appVersion: "1.0.0",
      environment: "production",
    });
  }, []);

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        routeNameRef.current = navigationRef.getCurrentRoute()?.name;
        if (routeNameRef.current) {
          HeronSignal.screen(routeNameRef.current);
        }
      }}
      onStateChange={() => {
        const currentRouteName = navigationRef.getCurrentRoute()?.name;
        if (currentRouteName && routeNameRef.current !== currentRouteName) {
          HeronSignal.screen(currentRouteName);
          routeNameRef.current = currentRouteName;
        }
      }}
    >
      {/* Your navigators */}
    </NavigationContainer>
  );
}

Track business events

Use business events for meaningful user actions such as demo requests, signups, checkout steps, onboarding progress, or important CTA clicks.

import { Button } from "react-native";
import { HeronSignal } from "@heronsignal/react-native";

export function DemoButton() {
  return (
    <Button
      title="Request demo"
      onPress={() => {
        HeronSignal.event("demo_requested", {
          screen: "Pricing",
          cta: "request_demo",
          source: "hero",
        });
      }}
    />
  );
}

These events can later power funnels such as:

signup_started -> signup_completed
demo_requested -> demo_booked
checkout_started -> checkout_completed

Send app logs

Use logs for important app behavior you want to explain later in HeronSignal.

import { HeronSignal } from "@heronsignal/react-native";

HeronSignal.log("warn", "Checkout retry happened", {
  screen: "Checkout",
  area: "payment",
});

Recommended levels:

• info
• warn
• error

Capture errors

import { HeronSignal } from "@heronsignal/react-native";

try {
  await submitLeadForm();
} catch (error) {
  HeronSignal.captureError(error, {
    screen: "Pricing",
    flow: "lead_form",
  });

  throw error;
}

Privacy guidance

Do not send sensitive user data in event payloads.

Avoid:

• passwords
• access tokens
• payment card data
• full names
• emails
• phone numbers
• full message contents

Prefer safe labels:

HeronSignal.event("checkout_started", {
  plan: "growth",
  source: "pricing",
});

API

import { HeronSignal } from "@heronsignal/react-native";

await HeronSignal.init(options);
await HeronSignal.screen(name, data);
await HeronSignal.event(name, payload);
await HeronSignal.log(level, message, data);
await HeronSignal.captureError(error, data);

init(options)

type HeronSignalInitOptions = {
  publicKey: string;
  apiUrl?: string;
  appVersion?: string;
  environment?: string;
};

Payloads

Payloads should be small, non-sensitive JSON objects.

type HeronSignalPayload = Record<string, unknown>;

Dashboard behavior

Mobile SDK data appears in HeronSignal as mobile app telemetry:

• screen(...) becomes screen/page activity.
• event(...) becomes business events and can be used in funnels.
• log(...) appears in Logger.
• captureError(...) appears as app errors.

Current status

This is an alpha SDK. Android support is available first. iOS support is planned.