Initialization

The SDK must be initialized once, as early as possible in your app's lifecycle, before any other SDK method is called. The recommended location is your root component's mount effect, so initialization runs before the first screen renders.

4.1 Minimal Example

In its simplest form, init takes only two values: your API key and an appIdentifier. All other configuration fields have sensible defaults that work for the vast majority of integrations.

import { useEffect } from 'react'
import { B2Metric } from '@b2metric/react-native-sdk'

export default function App() {
  useEffect(() => {
    B2Metric.init({
      apiKey: 'YOUR_API_KEY',
      appIdentifier: 'your_app_identifier',
    })
  }, [])

  return <RootNavigator />
}

4.2 With Full Configuration

When you need more control — for example, to lower the batch size during development or to enable debug logs — pass any of the optional fields documented in the table below. Values outside the documented ranges are clamped automatically, so the SDK will never fail to initialize because of an out-of-range value.

await B2Metric.init({
  apiKey: 'YOUR_API_KEY',
  appIdentifier: 'your_app_identifier',
  batchSize: 20,
  flushIntervalSeconds: 30,
  maxRetries: 3,
  sessionTimeoutMinutes: 30,
  maxQueueSize: 1000,
  logLevel: 'debug',
})

4.3 Configuration Options

The full set of configuration options accepted by init:

Option	Type	Required	Default	Description
apiKey	string	Yes	—	Your B2Metric project API key. Treat it as a public client identifier — it is safe to embed in a shipped binary.
appIdentifier	string	Yes	—	Lowercase snake_case identifier of your app as registered in B2Metric. See section 4.4 for the exact format rules.
baseUrl	string	No	tracker.b2metric.com	Override the API endpoint. Only change this if directed by the B2Metric team (for example, for an on-premise deployment).
batchSize	number	No	20	How many events the SDK accumulates before sending. Allowed range: 1–100. Larger values reduce request count; smaller values reduce delivery latency.
flushIntervalSeconds	number	No	30	Maximum time a batch may wait before being sent, even if it is not full. Allowed range: 1–3600 seconds.
maxRetries	number	No	3	How many times a failed batch is retried before being dropped. Allowed range: 1–10. Retries use exponential backoff.
sessionTimeoutMinutes	number	No	30	How long the app must be inactive (backgrounded) before the next foreground event opens a new session. Allowed range: 1–10080 minutes (one week).
maxQueueSize	number	No	1000	Maximum number of unsent events held on disk. When the queue is full, the oldest events are evicted. Allowed range: 100–10000.
logLevel	string	No	off	Console log verbosity. One of off, error, warning, info, debug. Use debug during integration and off in production.

4.4 appIdentifier Format

The appIdentifier field has stricter rules than the other configuration values. It must be lowercase snake_case so that it can be used safely as a key in dashboards, queries, and exported data. The exact rules are:

• Only the characters a–z, 0–9 and _ are allowed.
• Must start with a letter (a digit or underscore is rejected).
• Cannot contain spaces, hyphens, uppercase letters, or any non-ASCII characters (including Turkish characters such as ç ğ ı ö ş ü).
• Cannot start or end with _, and cannot contain two consecutive __.

Valid	Invalid	Why it is invalid
my_app	MyApp	Contains uppercase letters.
my_app_v2	my-app	Hyphens are not allowed; use underscore.
checkout_web	my app	Spaces are not allowed.
app123	şirket	Contains non-ASCII characters.
a_b_c	123app	Cannot start with a digit.
—	_myapp	Cannot start with underscore.
—	my__app	Two consecutive underscores are not allowed.

Note

Once events have been collected under a particular appIdentifier, changing it later will cause those existing events to appear under the old identifier in the dashboard. Choose a stable value before going to production.