mergn-react-native 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+MERGN React Native SDK — License Agreement
+
+Copyright (c) 2026 MERGN. All rights reserved.
+
+1. Grant of License
+   MERGN grants you a non-exclusive, non-transferable, revocable license to
+   install and use this package (the "Software"), including the MERGN mobile
+   SDK binaries distributed with or referenced by it, solely to integrate
+   MERGN services into your own applications.
+
+2. Restrictions
+   You may not:
+   (a) reverse engineer, decompile, or disassemble the SDK binaries, except to
+       the extent such restriction is prohibited by applicable law;
+   (b) redistribute, sublicense, sell, or rent the Software as a standalone
+       product, or as part of any product that competes with MERGN;
+   (c) remove or alter any copyright, trademark, or proprietary notice.
+
+   Redistributing the Software as an embedded component of your own
+   application is permitted and expected.
+
+3. Ownership
+   MERGN retains all right, title, and interest in the Software. This license
+   conveys no ownership.
+
+4. Third-Party Components
+   The Software depends on third-party open-source components, each governed
+   by its own license. Those licenses are unaffected by this agreement.
+
+5. No Warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. Limitation of Liability
+   IN NO EVENT SHALL MERGN BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+7. Termination
+   This license terminates automatically if you breach any term. On
+   termination you must cease use and remove the Software from your products.
+
+For commercial terms, support, or questions: https://mergn.com

package/README.md

@@ -0,0 +1,131 @@
+# mergn-react-native
+
+MERGN SDK for React Native. One JS API, native SDKs on both platforms.
+
+## Install
+
+```sh
+npm install mergn-react-native
+```
+
+Add the plugin to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["mergn-react-native"]
+  }
+}
+```
+
+Then rebuild the native projects:
+
+```sh
+npx expo prebuild
+npx expo run:android
+npx expo run:ios      # macOS only
+```
+
+That's it. The Android `.aar` and the iOS `.xcframework` ship inside this
+package, and autolinking registers the native module — you do not edit
+`MainApplication`, `settings.gradle`, or the `Podfile`.
+
+> **Expo Go will not work.** This package contains native code, so it needs a
+> development build (`expo run:*`) or an EAS build.
+
+## Usage
+
+```js
+import Mergn from "mergn-react-native";
+
+// Once, as early as possible — pending events are dropped until this resolves.
+await Mergn.registerApi("YOUR_MERGN_API_KEY");
+
+await Mergn.performEvent("Collection Viewed", { title: "Beauty" });
+await Mergn.setAttribute("Email", "user@example.com");
+await Mergn.login("user@example.com");
+await Mergn.setFirebaseToken(fcmToken);
+```
+
+Every method returns a Promise resolving to a status string from the native SDK.
+Identical method names, arguments and results on Android and iOS.
+
+| Method | Purpose |
+| --- | --- |
+| `registerApi(apiKey)` | Register your API key. Call first. |
+| `performEvent(name, props?)` | Record an event. |
+| `setAttribute(name, value)` | Set a user attribute. |
+| `login(id)` | Identify the user. |
+| `setFirebaseToken(token)` | Give MERGN the push token. |
+| `setAppContext(token)` | Currently the same path as `setFirebaseToken`. |
+
+### `setAttribute` de-duplicates
+
+Sending the same value twice for one attribute is a deliberate no-op in the SDK
+("value is same as previous"). Use a changed value when testing.
+
+## Push notifications
+
+You need Firebase configured in your own app — this package does not bundle it.
+
+```sh
+npx expo install @react-native-firebase/app @react-native-firebase/messaging
+```
+
+- **Android:** put `google-services.json` in your project and configure the
+  Firebase plugin. This package's config plugin already declares MERGN's
+  messaging service and the notification permissions.
+- **iOS:** add `GoogleService-Info.plist`, upload an APNs key to Firebase, and
+  add the push capability. Register the app's bundle ID in Firebase.
+
+Pass the token you get from `messaging().getToken()` to
+`Mergn.setFirebaseToken(token)`.
+
+### Rich push images on iOS (optional)
+
+iOS only renders a notification image if the app contains a **Notification
+Service Extension** — a separate binary that must be a target of your app, so
+no library can provide it. Without one, a push carrying `mutable-content: 1`
+and an `image` URL still arrives, just as text.
+
+To add it: **Xcode → File → New → Target → Notification Service Extension**,
+then copy the implementation from
+`node_modules/mergn-react-native/ios/NotificationService/NotificationService.swift`.
+Set the extension's deployment target to match your app (it must not be higher).
+
+Android needs nothing here — MERGN's SDK handles images itself.
+
+## Platform guides
+
+| | |
+| --- | --- |
+| [docs/ANDROID.md](docs/ANDROID.md) | Android setup, push, popups, troubleshooting |
+| [docs/IOS.md](docs/IOS.md) | iOS setup, push, rich images, troubleshooting |
+| [docs/MIGRATION.md](docs/MIGRATION.md) | **Upgrading from a manual integration — read this first if you copied MergnModule.java into your app** |
+
+## Requirements
+
+| | |
+| --- | --- |
+| iOS | 14.0+ |
+| Android | minSdk 24+ |
+| React Native | 0.72+ |
+| Expo | SDK 50+ |
+
+## Troubleshooting
+
+**`MergnModule.<method> is unavailable`** — the native module did not load.
+Rebuild (`npx expo prebuild && npx expo run:ios`). Expo Go cannot load it.
+
+**`pod install` fails with "Unable to find compatibility version string for
+object version 70"** — newer Xcode writes a project format older CocoaPods
+cannot read. This package's config plugin pins it; make sure the plugin is in
+your `app.json` and re-run `npx expo prebuild`. Or update CocoaPods.
+
+**iOS build fails with "Cycle inside <YourApp>"** — caused by
+`@react-native-firebase`'s script phase once an app extension is embedded. The
+config plugin fixes this too; ensure it is listed in `app.json`.
+
+**Events reach the SDK but nothing appears in the dashboard** — check
+`registerApi` resolved before you sent them, and confirm your API key and
+bundle ID / package name are provisioned in your MERGN account.

package/android/build.gradle

@@ -0,0 +1,66 @@
+// Android library module for mergn-react-native.
+// React Native autolinking discovers this via react-native.config.js, so the
+// client never edits settings.gradle or app/build.gradle.
+buildscript {
+  repositories { google(); mavenCentral() }
+  dependencies { classpath 'com.android.tools.build:gradle:8.1.1' }
+}
+
+apply plugin: 'com.android.library'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace 'com.mergn.reactnative'
+  compileSdk safeExtGet('compileSdkVersion', 34)
+
+  defaultConfig {
+    minSdk safeExtGet('minSdkVersion', 24)
+    targetSdk safeExtGet('targetSdkVersion', 34)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  lintOptions { abortOnError false }
+}
+
+repositories {
+  google()
+  mavenCentral()
+  // The Mergn Android SDK is published here.
+  maven { url 'https://jitpack.io' }
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-android'
+
+  // Resolved from JitPack rather than a bundled .aar, so the binary does not
+  // ship inside this npm package.
+  implementation "com.github.SHamzaHMergn:Mergn_sdk_android:${safeExtGet('mergnSdkVersion', '5.2.4')}"
+
+  // The SDK's POM was generated by `install:install-file` and declares NO
+  // dependencies, so Gradle cannot resolve them transitively - they must be
+  // listed here or the app fails at runtime with NoClassDefFoundError.
+  // This list was derived by disassembling the .aar (javap over classes.jar):
+  //   androidx.room + sqlite  - local event/attribute persistence
+  //   androidx.work           - periodic upload worker
+  //   androidx.core           - notification building
+  //   kotlin stdlib/coroutines- the SDK is written in Kotlin
+  //   gson                    - payload serialisation (85 references)
+  //   firebase-messaging      - FireBaseMessagingService, declared in our manifest
+  implementation "androidx.room:room-runtime:${safeExtGet('roomVersion', '2.6.1')}"
+  implementation "androidx.work:work-runtime-ktx:${safeExtGet('workVersion', '2.9.0')}"
+  implementation 'androidx.core:core-ktx:1.13.1'
+  implementation 'androidx.appcompat:appcompat:1.6.1'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1'
+  implementation 'com.google.code.gson:gson:2.10.1'
+
+  // compileOnly: the host app supplies its own Firebase version via
+  // google-services, and pinning one here would risk a conflict.
+  compileOnly 'com.google.firebase:firebase-messaging:23.4.1'
+}

package/android/src/main/java/com/mergn/reactnative/MergnModule.java

@@ -0,0 +1,152 @@
+package com.mergn.reactnative;
+
+import android.app.Activity;
+import android.app.Application;
+import android.content.Context;
+import android.util.Log;
+
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.mergn.insights.classes.AttributeManager;
+import com.mergn.insights.classes.EventManager;
+import com.mergn.insights.classes.MergnContext;
+import com.mergn.insights.classes.MergnSDK;
+
+import org.json.JSONObject;
+
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+
+public class MergnModule extends ReactContextBaseJavaModule {
+    private static final String TAG = "MergnModule";
+    private static final String ACTION_REGISTER_API = "register_api";
+    private static final String ACTION_PERFORM_EVENT = "perform_event";
+    private static final String ACTION_SET_ATTRIBUTE = "add_attribute";
+    private static final String ACTION_LOGIN = "login_mergn";
+    private static final String ACTION_FIREBASE_TOKEN_MERGN = "firebase_token_mergn";
+    private static final String MERGN_APP_CONTEXT = "mergn_app_context";
+
+    // MergnSDK.initialize registers activity lifecycle callbacks, so calling it on
+    // every register_api would stack duplicate listeners.
+    private static boolean sdkInitialized = false;
+
+    private final EventManager eventManager = new EventManager();
+    private final AttributeManager attributeManager = new AttributeManager();
+
+    public MergnModule(ReactApplicationContext reactContext) {
+        super(reactContext);
+    }
+
+    @Override
+    public String getName() {
+        return "MergnModule";
+    }
+
+    @ReactMethod
+    public void performAction(String action, String jsonData, Promise promise) {
+        try {
+            JSONObject options = new JSONObject(jsonData);
+
+            ReactApplicationContext appCtx = getReactApplicationContext();
+            Activity activity = getCurrentActivity();
+            Log.d(TAG, "Received Action: " + action
+                    + " | activity=" + (activity == null ? "NULL" : "present"));
+            // The SDK renders in-app popups, which need an Activity. Fall back to the
+            // application context so backgrounded calls still record instead of failing.
+            Context uiCtx = activity != null ? activity : appCtx;
+
+            switch (action) {
+                case ACTION_REGISTER_API: {
+                    String apiKey = options.getString("apiKey");
+                    if (!sdkInitialized) {
+                        MergnSDK.initialize((Application) appCtx.getApplicationContext());
+                        sdkInitialized = true;
+                    }
+                    if (activity != null) {
+                        MergnContext.context = activity;
+                    }
+                    eventManager.registerApiKey(apiKey, appCtx);
+                    Log.d(TAG, "Registered API key");
+                    promise.resolve("API Key Registered");
+                    break;
+                }
+
+                case ACTION_PERFORM_EVENT: {
+                    String eventName = options.getString("eventName");
+                    Map<String, String> eventPropertiesMap = new HashMap<>();
+                    JSONObject rawProperties = options.optJSONObject("eventPropertiesMap");
+                    if (rawProperties != null) {
+                        Iterator<String> keys = rawProperties.keys();
+                        while (keys.hasNext()) {
+                            String key = keys.next();
+                            eventPropertiesMap.put(key, String.valueOf(rawProperties.get(key)));
+                        }
+                    }
+                    // Argument order is load-bearing. The SDK declares:
+                    //   sendEvent(eventName, properties, activityContext, clientAppContext)
+                    // so the ACTIVITY must be 3rd and the app context 4th.
+                    //
+                    // EventManager builds the in-app popup with
+                    //   var dialogContext = activityContext
+                    // and only swaps to the app context when Settings.canDrawOverlays()
+                    // is true — which never happens in production, since the SDK does not
+                    // request SYSTEM_ALERT_WINDOW and users must enable it by hand.
+                    // So activityContext IS the popup's context. Passing an Application
+                    // context there makes AlertDialog.show() throw BadTokenException,
+                    // which CampaignView.show() swallows in an empty catch — the popup
+                    // silently never appears while the SDK still logs " In App Showed"
+                    // and sets IS_IN_APP_SHOWN = true.
+                    eventManager.sendEvent(eventName, eventPropertiesMap, uiCtx, appCtx);
+                    Log.d(TAG, "Event Sent: " + eventName);
+                    promise.resolve("Event Performed");
+                    break;
+                }
+
+                case ACTION_SET_ATTRIBUTE: {
+                    String attributeName = options.getString("attributeName");
+                    String attributeValue = options.getString("attributeValue");
+                    attributeManager.sendAttribute(appCtx, attributeName, attributeValue);
+                    Log.d(TAG, "Attribute Set: " + attributeName);
+                    promise.resolve("Attribute Set");
+                    break;
+                }
+
+                case ACTION_LOGIN: {
+                    String uniqueIdentifier = options.getString("uniqueIdentifier");
+                    eventManager.login(uniqueIdentifier, uiCtx);
+                    Log.d(TAG, "User Logged In");
+                    promise.resolve("User Logged In");
+                    break;
+                }
+
+                case ACTION_FIREBASE_TOKEN_MERGN: {
+                    String fcmTokenMergn = options.getString("fcmTokenMergn");
+                    eventManager.firebaseToken(fcmTokenMergn, uiCtx);
+                    Log.d(TAG, "Firebase Token Set");
+                    promise.resolve("Firebase Token Set");
+                    break;
+                }
+
+                // TODO: currently identical to firebase_token_mergn. Needs a product
+                // decision on what app-context registration should actually do.
+                case MERGN_APP_CONTEXT: {
+                    String contextToken = options.getString("fcmTokenMergn");
+                    eventManager.firebaseToken(contextToken, uiCtx);
+                    Log.d(TAG, "Firebase Token in App Context Set");
+                    promise.resolve("Firebase Token in App Context Set");
+                    break;
+                }
+
+                default:
+                    promise.reject("UNSUPPORTED_ACTION", "Action " + action + " is not supported.");
+                    break;
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "performAction failed for action " + action, e);
+            promise.reject("MERGN_ERROR", e);
+        }
+    }
+}

package/android/src/main/java/com/mergn/reactnative/MergnPackage.java

@@ -0,0 +1,31 @@
+package com.mergn.reactnative;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+public class MergnPackage implements ReactPackage {
+    @NonNull
+    @Override
+    public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactApplicationContext) {
+
+            List<NativeModule> modules = new ArrayList<>();
+
+            modules.add(new MergnModule(reactApplicationContext));
+
+            return modules;
+    }
+
+    @NonNull
+    @Override
+    public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactApplicationContext) {
+        return Collections.emptyList();
+    }
+}

package/app.plugin.js

@@ -0,0 +1,2 @@
+// Expo resolves "mergn-react-native" in app.json plugins to this file.
+module.exports = require("./plugin");

package/docs/ANDROID.md

@@ -0,0 +1,147 @@
+# Android setup
+
+Most of this is automatic. Autolinking registers the native module, and the
+config plugin adds the manifest entries — so a plain analytics integration needs
+nothing on this page beyond installing.
+
+> **Upgrading from a hand-rolled MERGN integration?** Read
+> [MIGRATION.md](./MIGRATION.md) **first** and remove the old pieces. Installing
+> this package on top of a manual integration fails the build, and two of the
+> removal steps fail *silently* if you skip them.
+
+```sh
+npm install mergn-react-native
+```
+
+```json
+{ "expo": { "plugins": ["mergn-react-native"] } }
+```
+
+```sh
+npx expo prebuild --platform android
+npx expo run:android
+```
+
+## What the package does for you
+
+| | |
+| --- | --- |
+| Native module registration | Autolinking (`react-native.config.js`) |
+| MERGN Android SDK | `com.github.SHamzaHMergn:Mergn_sdk_android:5.2.4` from JitPack |
+| JitPack repository | Declared in the package's own `build.gradle` |
+| `INTERNET`, `POST_NOTIFICATIONS`, `VIBRATE` permissions | Config plugin |
+| MERGN `FireBaseMessagingService` | Config plugin |
+
+You do **not** edit `MainApplication`, `settings.gradle`, or `app/build.gradle`.
+
+## Requirements
+
+- `minSdkVersion` 24 or higher
+- Java 17 (the Android Gradle Plugin default for AGP 8+)
+
+Override the SDK version if MERGN ships a new one before this package updates,
+in `android/build.gradle`:
+
+```gradle
+ext { mergnSdkVersion = "5.2.5" }
+```
+
+## Push notifications
+
+The MERGN SDK receives pushes through its own `FirebaseMessagingService`, which
+the config plugin declares. You still need Firebase in your app:
+
+```sh
+npx expo install @react-native-firebase/app @react-native-firebase/messaging
+```
+
+1. Put `google-services.json` in your project root.
+2. Point `app.json` at it and add the Firebase plugin:
+   ```json
+   {
+     "expo": {
+       "android": { "googleServicesFile": "./google-services.json" },
+       "plugins": [
+         "mergn-react-native",
+         "@react-native-firebase/app"
+       ]
+     }
+   }
+   ```
+3. Pass the token to MERGN:
+   ```js
+   import messaging from "@react-native-firebase/messaging";
+   import Mergn from "mergn-react-native";
+
+   const token = await messaging().getToken();
+   await Mergn.setFirebaseToken(token);
+   ```
+
+`google-services.json` is client configuration that ships inside every APK, not
+a server secret — committing it is normal and keeps builds reproducible.
+
+### Android 13+ notification permission
+
+`POST_NOTIFICATIONS` is declared for you, but it is a *runtime* permission on
+API 33+, so you must still request it:
+
+```js
+import { PermissionsAndroid, Platform } from "react-native";
+
+if (Platform.OS === "android" && Platform.Version >= 33) {
+  await PermissionsAndroid.request(
+    PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
+  );
+}
+```
+
+Without this, pushes are delivered but silently not displayed.
+
+### Notification view / click tracking
+
+Automatic. The SDK's own `FirebaseMessagingService` records impressions and taps
+internally — there is no JS API for it, and none is needed.
+
+## In-app popups
+
+Triggered by MERGN campaigns in response to events, so nothing to call directly:
+
+```js
+await Mergn.performEvent("Collection Viewed", { title: "Beauty" });
+```
+
+The SDK renders the popup itself using the current Activity. If a popup does not
+appear, check that a campaign is actually configured for that event name in your
+MERGN dashboard.
+
+## Transitive dependencies
+
+The SDK's published POM declares no dependencies, so this package declares them
+on the SDK's behalf: `androidx.room`, `androidx.work`, `androidx.core`,
+`androidx.appcompat`, `kotlinx-coroutines-android` and `gson`, plus
+`firebase-messaging` as `compileOnly` so it cannot conflict with your app's own
+Firebase version.
+
+If you see `NoClassDefFoundError` from inside `com.mergn.insights` at runtime,
+that list has drifted — please report it.
+
+## Troubleshooting
+
+**`Duplicate class com.mergn.insights.*`** — you still have the old `.aar` in
+`android/app/libs/`. See [MIGRATION.md](./MIGRATION.md) — and note that removing
+the `.aar` alone is not sufficient.
+
+**`Native module MergnModule tried to override ...`** — your old
+`MergnModule.java` / `MergnPackage.java` are still in the app, so two modules
+claim the same name. See [MIGRATION.md](./MIGRATION.md) steps 2 and 3.
+
+**`MergnModule.<method> is unavailable`** — the native module did not load.
+You are probably in Expo Go, which cannot load native code; use
+`npx expo run:android` or an EAS build.
+
+**Events send but nothing reaches the dashboard** — confirm `registerApi`
+resolved *before* the events, and that your API key and package name are
+provisioned in your MERGN account.
+
+**An attribute does not update** — the SDK de-duplicates: setting the same value
+again for one attribute name is intentionally a no-op. Use a changed value.