React Native Integration

Vexo is the first React Native out of the box tool for analytics. We provide a solution for precise and actionable data with a seamless integration and zero-configuration, zero-coding support.

Our documentation is a great place to find most answers and make sure that your experience using Vexo is a magical one.

Quickstart

Prerequisites

• Using React Navigation or Expo Router

Expo

• ✅ You can use this library with Development Builds. No config plugin is required.
• ❌ This library can't be used in the "Expo Go" app because it requires custom native code.

Getting started

1. Create an account here
2. You'll be prompted into creating a new app, give it a cool name (you will be able to change that later) and once you submit it, you'll be given an API key.
3. Run yarn add vexo-analytics or npm install vexo-analytics in your project. If you are using bare React Native, run pod install in the iOS folder.
4. Add the following code to your app entry file (usually index.js, App.js or _layout.tsx if you're using Expo Router):

import { vexo } from 'vexo-analytics';

// You may want to wrap this with `if (!__DEV__) { ... }` to only run Vexo in production.
vexo('YOUR_API_KEY');

export default function RootLayout() {
  return (
    // Your layout JSX here
  );
}

⚠️ Important: Initialize Vexo at the module level, not inside useEffect or component functions, to ensure proper tracking from app start.

5. Re-build and run your app (the vexo-analytics package includes native code).
6. Go to your app's page on Vexo and you should see your first event!

Wait, that's it? Yes! That's it. With that ease of integration experience you get an incredible set of features, go check them out!

Development & staging

You usually don't want your own development sessions mixed into your production analytics. Vexo only starts when you call vexo(...) — nothing is collected or sent before that — so the recommended way to disable it is to simply make the call conditional:

import { vexo } from 'vexo-analytics';

if (!__DEV__) {
  vexo('YOUR_API_KEY');
}

A few things you can rely on when Vexo has not been initialized:

• Not calling vexo() is a fully supported way to disable Vexo. There is no background work, and no data leaves the device.
• customEvent() calls are safely ignored: the event is dropped and a warning is logged to the console. Your app's behavior is not affected, so you don't need to guard every call site.
• identifyDevice(), enableTracking() and disableTracking() are safe no-ops as well.

If you'd rather keep development or staging data instead of dropping it, create a separate app in your dashboard (for example "MyApp — Staging") and pick the API key by environment:

vexo(__DEV__ ? 'STAGING_API_KEY' : 'PRODUCTION_API_KEY');

How it works

One line of code? How is this possible?

It's very simple! Vexo is a very lightweight advanced piece of technology that listens to React Native events, such as AppState changes, packs the data into a buffer and sends it to our servers. Given that it works in background with your app, there are no code dependencies and it's effortless to integrate!

Events are batched before they leave the device: the SDK sends a group as soon as it has 20 events, or 5 seconds after the first event was queued — whichever comes first. This keeps network and battery usage low without you having to think about it.

Events

Supported events are:

• Opened/closed/browsing app
• Changed screen
• Tapped on screen
• Started/finished typing
• Turned phone to landscape/portrait
• Your app sent a request for data
• An error occurred
• Custom events

Every one of these — taps, screen changes, requests, errors and your custom events — counts toward your account's monthly event total. See Subscription for the 500,000 events per month free allowance and the pay-as-you-go rates beyond it.

Device Identity

As well as being seamless, privacy is a key focus. We don't store any PII from your devices or users, so we provide a way in which you can identify a user in order to be able to navigate through your dashboards in a personalized way. To achieve this, do the following:

import { View } from 'react-native'
import { identifyDevice } from 'vexo-analytics'

const LoginComponent = () => {
    const onLogin = async () => {
        // your code
        await identifyDevice('IDENTIFIER');
    }
    return (<View>{...}</View>);
};

It's important to note that the identifier is a string and can be anything you want. We recommend that you identify your device with a token/hash that you can then map it into your users' data to be able to know which user is it. As an example, in SQL a unique ID as a foreign key to your users' table should suffice.

In case you want to make the device anonymous, identifyDevice supports null like in the following example:

import { View } from 'react-native'
import { identifyDevice } from 'vexo-analytics'

const LogoutComponent = () => {
    const onLogout = async () => {
        // your code
        await identifyDevice(null);
    }
    return (<View>{...}</View>);
};

Tracking Opt-in

You can programmatically enable or disable tracking in your app based on your business logic and requirements. This gives you full control over when analytics data is sent.

import { enableTracking, disableTracking } from 'vexo-analytics'

// disable tracking
await disableTracking();
// re-enable tracking, under X condition
await enableTracking();

Error reporting

Errors that reach the top of your app are captured automatically. To report a caught exception yourself — without crashing the app — call trackError:

import { trackError } from 'vexo-analytics'

try {
  await riskyOperation();
} catch (err) {
  trackError(err);
}

By default the error is recorded as handled, so it does not count against your crash-free rate. Pass { handled: false } to record it as an unhandled error instead:

trackError(err, { handled: false });

Custom events

This is where the power of out of the box analytics meets the custom needs of your business. You'll be able to send custom events specific to you application's needs, and that data will be enriched with the context data that we provide:

import { View } from 'react-native'
import { customEvent } from 'vexo-analytics'

const SaaSPurchaseComponent = () => {
    const onSuccessfulPurchase = (subscriptionType, amount, description) => {
        customEvent(`sale-${subscriptionType}`, { amount, description })
    }
    return (<View>{...}</View>)
}

We will understand the context about the event that has just happened and infer multiple axis of data, such as:

• Screen it happened on
• Device OS
• App version
• ... and more!

For further understanding on custom events check out the docs

Troubleshooting

Scroll feels laggy after returning from the background

Some apps saw a brief scroll stutter the first time a list is scrolled after the app comes back from the background to the foreground. This is fixed in vexo-analytics 1.8.0 and later, so upgrading the SDK resolves it for most apps.

If you still see it and don't need session replay, you can turn replay off for the app from your dashboard tracking settings. A code-level switch — vexo('YOUR_API_KEY', { sessionReplay: false }) — is targeted for the next release (v1.9.1) and is not available yet. See docs issue #49 for background and vexo-analytics PR #95 for the upcoming option.