Chatla SDK for React Native

Drop-in SDK for sending Chatla events and opening WhatsApp / Messenger deep links from a React Native app. API parity with the Unity SDK.

Install

The SDK ships as TypeScript source — Metro transpiles it via Babel, no build step needed.

From your React Native project:

npm install @chatlaio/sdk-react-native js-sha256
# or
yarn add @chatlaio/sdk-react-native js-sha256

Installing from source (while iterating on the SDK itself)

If you're developing the SDK locally, install it from a folder or git URL instead of the registry:

# local folder
yarn add file:../chatla-sdk-rn js-sha256
# git URL
yarn add github:Simply-Expert/chatla-sdk-rn js-sha256

Peer dependencies

• react-native >= 0.60
• js-sha256 (listed as a regular dependency; explicitly install it if your package manager doesn't auto-hoist)

No native modules are required. The SDK uses react-native's built-in Linking, Platform, and NativeModules only — works with Expo (managed and bare) and bare RN.

Setup

1. Initialize once at app startup

// App.tsx
import { useEffect } from 'react';
import { Chatla } from '@chatlaio/sdk-react-native';

export default function App() {
  useEffect(() => {
    Chatla.initialize({
      apiKey: 'YOUR_API_KEY',
      secretKey: 'YOUR_SECRET_KEY',
      // Optional — set once the user is signed in, or omit for guest sessions
      userId: undefined,
      // Optional — used if the backend doesn't return a phone / page id
      fallbackPhone: '15551234567',
      fallbackPageId: 'your-fb-page-id',
      // Optional metadata for event payloads
      appVersion: '1.2.3',
      deviceModel: 'iPhone15,3',
    });
  }, []);

  // ...
}

If you want to read appVersion / deviceModel automatically, install react-native-device-info and pass them yourself:

import DeviceInfo from 'react-native-device-info';

Chatla.initialize({
  apiKey: '...',
  secretKey: '...',
  appVersion: DeviceInfo.getVersion(),
  deviceModel: DeviceInfo.getModel(),
});

2. Identify the user (after sign-in / onboarding)

// Tell Chatla which user this session belongs to
Chatla.setUserId('user-123');

// Send the onboarding event with their phone — this is what makes the user "identified"
Chatla.identify('+15551234567', 'pro-tier', { signup_source: 'app_store' });

identify() and userOnboard() are aliases — pick whichever reads better.

3. Open WhatsApp / Messenger

import { Button } from 'react-native';

<Button title="Chat on WhatsApp" onPress={() => Chatla.openWhatsapp()} />
<Button title="Chat on Messenger" onPress={() => Chatla.openMessenger()} />

The SDK fetches the configured phone / page id from /me, flushes any pending traits, and opens the system deep link. If the user is already identified, the prefilled onboarding message is skipped.

4. Send events

import { Chatla, ChatlaEventType } from '@chatlaio/sdk-react-native';

Chatla.gameStart();
Chatla.levelUp(5, { difficulty: 'hard' });
Chatla.iapTransaction({
  productId: 'gold_pack_100',
  isFirstPurchase: true,
  purchaseCount: 1,
});

// Or directly with the enum
Chatla.sendEvent(ChatlaEventType.AchievementUnlocked, {
  achievement_id: 'first_win',
});

Events are only delivered once the user is identified (the SDK queues nothing — it drops events sent before identification, with the exception of UserOnboard).

5. Set traits

Chatla.setTrait('subscription_tier', 'pro');
Chatla.setTraits({ preferred_language: 'en', has_referral: true });

Traits are queued locally and flushed when the user becomes identified, or right before opening WhatsApp/Messenger.

6. GDPR — tracking consent & deletion

// Pause / resume tracking based on user consent
Chatla.setTrackingEnabled(false);

// On account deletion: drop user state and stop sending data
Chatla.onUserRequestedDeletion();

API surface

| Method | Purpose | | ------------------------------------------------ | ---------------------------------------------------- | | Chatla.initialize(opts) | One-time init | | Chatla.setUserId(id) | Associate or change the user id (re-fetches /me) | | Chatla.identify(phone, tag?, customData?) | Onboard — required before non-onboarding events flow | | Chatla.sendEvent(type, customData?) | Raw event | | Chatla.gameStart() / levelUp() / iapTransaction() / ... | Typed convenience wrappers | | Chatla.openWhatsapp() | Deep-link to WhatsApp | | Chatla.openMessenger() | Deep-link to Facebook Messenger | | Chatla.setTrait(key, value) / setTraits(map) | Queue/flush user traits | | Chatla.setTrackingEnabled(bool) | GDPR consent toggle | | Chatla.onUserRequestedDeletion() | GDPR account deletion | | Chatla.state / Chatla.isIdentified | Current state |

For advanced cases (multiple clients, dependency injection), import the underlying class:

import { ChatlaClient } from '@chatlaio/sdk-react-native';
const client = new ChatlaClient({ apiKey, secretKey });

Notes

• Singleton. Only one initialize() call takes effect; subsequent calls are ignored (matches the Unity SDK).
• Async transport. sendEvent / setTraits are fire-and-forget — network failures are logged via console.warn, never thrown.
• Identified gating. Non-onboarding events are dropped until /me confirms identification — same behavior as the Unity SDK.
• No native modules. Compatible with Expo Go.

License

MIT