@janiscommerce/app-analytics

@janiscommerce/app-analytics

Firebase Analytics tracking for Janis React Native apps.

Requirements

• @react-native-firebase/app and @react-native-firebase/analytics installed and configured
• @janiscommerce/app-crashlytics installed (used for internal error reporting in production)

See Firebase setup for Android/iOS configuration.

Installation

npm install @janiscommerce/app-analytics

Usage

1. Create an instance

import Analytics from '@janiscommerce/app-analytics'

const analytics = new Analytics({ appVersion: '1.0.0' })

Param	Type	Required	Description
appVersion	string	Yes	App version string
isDebugMode	boolean	No	When true, events are sent even in dev environment

2. Register user identity at login

Call setSession() once after the user logs in. It fetches the user from the OAuth token and registers identity in Firebase via setUserId and setUserProperties.

await analytics.setSession()

3. Send events

// Log an action
await analytics.sendAction('button_press', 'Home')
await analytics.sendAction('button_press', 'Home', { itemId: '123' })

// Log a custom event
await analytics.sendCustomEvent('order_created', { orderId: '123' })

// Log a screen view
await analytics.sendScreenTracking('Home', 'HomeScreen')

4. Update user properties after login

Use setUserProperties to register or update dynamic user attributes after login (e.g. when a warehouse operator selects a depot).

await analytics.setUserProperties({ warehouseId: 'WH-001' })
await analytics.setUserProperties({ language: 'es-AR' })

5. Clear user identity at logout

Call clearSession() when the user logs out. It clears user identity from Firebase and nullifies all registered user properties, including any extras set via setUserProperties.

await analytics.clearSession()

---

API

new Analytics({ appVersion, isDebugMode })

Creates a new Analytics instance. Throws if appVersion is not provided or is not a string.

setSession()

Fetches user info from the OAuth token and registers identity in Firebase:

• Calls analytics().setUserId(sub) with the token's sub field
• Calls analytics().setUserProperties({ userEmail, client, language, userProfile }) with the token's fields

Required token fields: sub, email, tcode. Optional: locale, profileName.

Must be called once at login before sending events.

clearSession()

Clears user identity from Firebase and resets session state:

• Calls analytics().setUserId(null)
• Nullifies all user properties registered during the session (both from setSession() and setUserProperties())
• Resets session state while preserving appVersion and isDebugMode

Must be called at logout.

setUserProperties(properties)

Updates one or more Firebase user properties. Accepts a non-empty object of key/value pairs.

await analytics.setUserProperties({ warehouseId: 'WH-001', zone: 'north' })

Properties registered via this method are automatically cleared on clearSession().

sendAction(actionName, screenName[, params])

Logs a Firebase action event.

Param	Type	Required	Description
actionName	string	Yes	Name of the action (formatted to lowercase with underscores)
screenName	string	No	Screen where the action was triggered
params	object	No	Extra params to include in the event

Returns true on success, false on error, null if session not ready or dev environment.

sendCustomEvent(eventName[, params])

Logs a custom Firebase event.

Param	Type	Required	Description
eventName	string	Yes	Name of the event
params	object	No	Sent as individual Firebase event params

Returns true on success, false on error, null if session not ready or dev environment.

sendScreenTracking(screenName[, screenClass])

Logs a Firebase screen view event.

Param	Type	Required	Description
screenName	string	Yes	Name of the screen the user is viewing
screenClass	string	No	Class associated with the screen

Returns true on success, false on error, null if session not ready or dev environment.

---

Base event params

Every event automatically includes:

Param	Source
appVersion	Constructor param
deviceId	@janiscommerce/app-device-info
device	@janiscommerce/app-device-info
osVersion	@janiscommerce/app-device-info
connection	@janiscommerce/app-device-info (fetched fresh per event)

User identity fields (userEmail, client, language, userProfile) are registered as Firebase user properties via setSession() — they do not travel as event params.

---

Firebase setup

Android

Add the Google Services plugin to android/build.gradle:

dependencies {
  classpath 'com.google.gms:google-services:4.3.15'
}

Add to android/app/build.gradle:

plugins {
  id("com.google.gms.google-services")
}

dependencies {
  implementation platform('com.google.firebase:firebase-bom:32.2.2')
  implementation 'com.google.firebase:firebase-analytics'
}

Clean the project:

cd android && ./gradlew clean && cd ..

---

Documentation

• Migration to v4 — breaking changes and migration guide from v3 to v4
• Enable Firebase DebugView — how to enable real-time event debugging in Firebase console
• Recommended Events — Google Analytics recommended events reference