@riveora/sdk-core

The platform-independent engine of the Riveora analytics SDK: event queue, sessions, anonymous and identified users, consent, batching and retries.

Building a React Native or Expo app? Install @riveora/react-native instead. It includes this package and adds automatic screen, tap, onboarding and paywall tracking.

Use this package directly only to send Riveora events from another JavaScript environment.

What it does

• Queue: events are stored through the Storage you provide and survive restarts. The queue holds up to 500 events; when full, the oldest are dropped first. New events are saved together about once a second, and straight away on flush().
• Batching: events are sent every 10 seconds or every 20 events, whichever comes first.
• Retries: on network errors and server errors the batch stays queued and is retried with a growing, randomly spread backoff (2 s up to 2 minutes). The server's Retry-After is respected, up to 10 minutes.
• Sessions: every launch starts a new session, and so does coming back after more than 2 minutes in the background (backgroundTimeoutMs).
• Consent: nothing is queued or sent unless consent is "granted", including events already queued. While consent is "unknown", saved events wait unsent; "denied" deletes them.
• People: identify() with a different user id than before, and reset(), start a new anonymous id and a new session, so two accounts on one device never mix. identify() with the previous user within 30 seconds of reset(), before anything else is recorded, undoes it.
• Never throws into your app: a missing or wrong projectKey logs an error and the client does nothing; identify() ignores ids it can't use, with a warning.
• Safe properties: only plain values are sent, at most 50 per event. Keys like password, token, email, phone, mobile, address, iban, pin, otp, api_key, cookie, verification_code, first_name or username, and values that look like an email address, a formatted phone number, an IBAN or card number, or a token or service key (sk-…, AWS, GitHub, Google, Slack…), are dropped. The Riveora server applies the same filter again. An event over 40 KB (after beforeSend) is dropped.
• Ids saved together: the anonymous and the user id are saved in one value, so a switch of person is never half saved. Ids saved by versions before 0.5.0 are taken over, also again if such a version ran since (an app update rolled back).
• Delivery: development builds (devWarnings) warn when the endpoint isn't https:// (local test servers are fine). Redirects from the endpoint are followed, as fetch does.

Example

import { RiveoraClient, MemoryStorage } from '@riveora/sdk-core';

const riveora = new RiveoraClient({
  projectKey: 'pk_your_project_key',
  sdkVersion: 'my-integration/1.0.0',
  storage: new MemoryStorage(), // or your own persistent Storage
  consent: 'granted',
});

await riveora.init();
await riveora.ensureSession();

riveora.track({ name: 'recipe_saved', properties: { recipe_id: 'r_42' } });
await riveora.identify('user_123'); // your internal id; emails and phone numbers are refused
await riveora.flush();

Storage is any object with async getItem, setItem and removeItem, such as AsyncStorage or a small wrapper around localStorage.

Random ids use crypto.getRandomValues when the environment has it (browsers, Node, React Native with react-native-get-random-values), otherwise Math.random.

Versions

@riveora/react-native, @riveora/sdk-core and @riveora/shared-contracts are released together and always share one version number (react-native 0.5.0 goes with sdk-core 0.5.0 and shared-contracts 0.5.0). What changed in each release is in the changelog of @riveora/react-native, which covers all three.

License

MIT