@loyalytics/swan-react-native-sdk 2.0.1

package/LICENSE

@@ -0,0 +1,55 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2025 Loyalytics. All Rights Reserved.
+
+NOTICE: This software and its source code are proprietary and confidential
+information of Loyalytics ("Proprietary Information").
+
+This software is provided to you under a commercial license agreement with
+Loyalytics. You may not use this software except in compliance with the terms
+of such commercial license agreement.
+
+RESTRICTIONS:
+
+1. You may NOT redistribute, sublicense, sell, or otherwise transfer this
+   software or any portion thereof to any third party.
+
+2. You may NOT modify, adapt, translate, reverse engineer, decompile,
+   disassemble, or create derivative works based on this software.
+
+3. You may NOT remove or alter any copyright, trademark, or other proprietary
+   notice from this software.
+
+4. You may NOT use this software for any purpose other than as expressly
+   authorized in your commercial license agreement with Loyalytics.
+
+5. The software is licensed, not sold. Loyalytics retains all right, title,
+   and interest in and to the software, including all intellectual property
+   rights therein.
+
+AUTHORIZED USE:
+
+This software may only be used by authorized customers of Loyalytics who have
+entered into a valid commercial license agreement. Use of this software
+constitutes acceptance of the terms and conditions set forth in such
+agreement.
+
+To obtain a commercial license or for more information, please contact:
+Email: support@loyalytics.ai
+Website: https://www.loyalytics.ai/
+
+DISCLAIMER:
+
+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. IN NO EVENT SHALL
+LOYALYTICS 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 THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+GOVERNING LAW:
+
+This license shall be governed by and construed in accordance with the laws
+of India, without regard to its conflict of law provisions.
+
+For licensing inquiries, contact: support@loyalytics.ai

package/README.md

@@ -0,0 +1,67 @@
+# Swan React Native SDK
+
+> **⚠️ PROPRIETARY SOFTWARE:** This SDK is proprietary software owned by Loyalytics.
+> It requires a valid commercial license for use. See [LICENSE](./LICENSE) for terms.
+
+## Installation
+
+**Note:** This package is available via npm for authorized customers only. Installation requires a valid commercial license agreement with Loyalytics.
+
+```sh
+npm install @loyalytics/swan-react-native-sdk
+```
+
+Or using yarn:
+
+```sh
+yarn add @loyalytics/swan-react-native-sdk
+```
+
+## Usage
+
+```js
+import SwanSDK from '@loyalytics/swan-react-native-sdk';
+
+// Initialize SDK
+const sdk = SwanSDK.getInstance('YOUR_APP_ID', {
+  isProduction: false,
+  pushNotifications: {
+    enabled: true,
+    autoRequestPermission: true,
+  },
+  isProduction: true,
+});
+
+// Track events
+sdk.productViewed({ productId: '123' });
+
+// Listen for SDK events
+sdk.on('initialized', () => {
+  console.log('SDK initialized!');
+});
+```
+
+## iOS Notification Extension
+
+To support Rich Media (Images) and Delivery Tracking (even when the app is killed), you must set up a **Notification Service Extension**.
+
+We provide an automated tool and a guide to help you set this up.
+
+```
+node ./node_modules/@loyalytics/swan-react-native-sdk/scripts/setup-ios-extension.js
+```
+
+## License
+
+This software is proprietary and confidential. Unauthorized copying, modification,
+distribution, or use of this software is strictly prohibited.
+
+Copyright © 2025 Loyalytics. All Rights Reserved.
+
+For licensing inquiries, contact: support@loyalytics.ai
+
+See the [LICENSE](./LICENSE) file for full terms.
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/docs/IOS_NOTIFICATION_EXTENSION_SETUP.md

@@ -0,0 +1,335 @@
+# iOS Notification Service Extension Setup
+
+## Overview
+
+The Swan SDK's Notification Service Extension enables:
+- ✅ **Delivery tracking** when app is killed or in background
+- ✅ **Rich media support** (images in notifications)
+- ✅ **Reliable ACKs** even when app is not running
+
+This extension is **required for iOS** to track push notification delivery in all app states.
+
+---
+
+## Why is this needed?
+
+### The iOS Limitation
+
+On iOS, when your app is in background or killed state and receives a push notification with a visible alert, React Native's `setBackgroundMessageHandler` **is NOT called**. This is fundamental iOS behavior, not a bug.
+
+**What this means:**
+- ❌ No delivery tracking when app is killed
+- ❌ No custom notification display logic in background
+- ❌ No image processing without extension
+
+### The Solution: Notification Service Extension
+
+A Notification Service Extension is a separate iOS app extension that:
+- ✅ Runs in a **separate process** from your main app
+- ✅ Intercepts **all incoming notifications** before they're displayed
+- ✅ Has **30 seconds** to process the notification
+- ✅ Can send delivery ACKs, download images, and modify content
+
+**Industry standard:** Firebase, OneSignal, CleverTap, Airship all use this approach.
+
+---
+
+## Installation
+
+### Step 1: Install Dependencies
+
+```bash
+npm install react-native-shared-group-preferences
+cd ios && pod install && cd ..
+```
+
+**Why needed:** Share credentials between app and extension.
+
+---
+
+### Step 2: Configure in Xcode
+
+#### 2.1 Add Extension Target
+
+1. Open `ios/*.xcworkspace` in Xcode
+2. Go to **File → New → Target**
+3. Choose **"Notification Service Extension"**
+4. **Product Name:** `SwanNotificationServiceExtension`
+5. **Language:** Swift
+6. Click **Finish**
+7. When prompted "Activate scheme?", click **Cancel**
+
+#### 2.2 Configure App Groups
+
+**App Groups** allow the main app and extension to share credentials.
+
+##### Main App Target
+
+1. Select your **main app target** (e.g., `YourApp`)
+2. Go to **"Signing & Capabilities"** tab
+3. Click **"+ Capability"**
+4. Search for and add **"App Groups"**
+5. Click **"+"** under App Groups
+6. Enter: `group.swan.sdk.notifications`
+7. Click **OK**
+
+##### Extension Target
+
+1. Select **SwanNotificationServiceExtension** target
+2. Go to **"Signing & Capabilities"** tab
+3. Click **"+ Capability"**
+4. Search for and add **"App Groups"**
+5. Click **"+"** under App Groups
+6. Enter: `group.swan.sdk.notifications` (**MUST match main app!**)
+7. Click **OK**
+
+**⚠️ IMPORTANT:** Both targets must have the **exact same** App Group ID.
+
+#### 2.3 Verify Bundle Identifier
+
+1. Select **SwanNotificationServiceExtension** target
+2. Go to **"General"** tab
+3. Check **Bundle Identifier**: Should be `com.yourcompany.app.SwanNotificationServiceExtension`
+4. Make sure it's a **child** of your main app's bundle ID
+
+---
+
+### Step 3: Run Setup Script
+
+Now that the extension target is created, run the setup script to copy the Swan implementation files. This will overwrite the default files created by Xcode.
+
+```bash
+node node_modules/swan-react-native-sdk/scripts/setup-ios-extension.js
+```
+
+**What it does:**
+- Copies extension files to `ios/SwanNotificationServiceExtension/`
+- Validates dependencies
+- Ensures the correct implementation is in place
+
+---
+
+### Step 4: Testing
+
+### Build and Archive
+
+```bash
+# Clean build
+cd ios
+rm -rf build
+xcodebuild clean -workspace YourApp.xcworkspace -scheme YourApp
+
+# Build
+xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release
+
+# Archive (for TestFlight or Ad Hoc)
+xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release archive
+```
+
+### Test on Real Device
+
+**IMPORTANT:** Push notifications don't work on iOS Simulator!
+
+1. Archive your app (Product → Archive in Xcode)
+2. Export to device or upload to TestFlight
+3. Install on a real iOS device
+4. Send a test notification
+5. Check Xcode **Device Console** for logs
+
+### Expected Logs
+
+When extension receives a notification:
+
+```
+[SwanSDK Extension] Notification Service Extension triggered
+[SwanSDK Extension] Request identifier: 1234567890
+[SwanSDK Extension] UserInfo: {...}
+[SwanSDK Extension] Found messageId in gcm.message_id: 0:1234567890
+[SwanSDK Extension] Sending delivery ACK for messageId: 0:1234567890
+[SwanSDK Extension] Credentials loaded - appId: YOUR_APP_ID
+[SwanSDK Extension] ACK payload: {...}
+[SwanSDK Extension] ACK response status: 200
+[SwanSDK Extension] ✅ Delivery ACK sent successfully
+```
+
+If image is present:
+```
+[SwanSDK Extension] Downloading notification image: https://example.com/image.png
+[SwanSDK Extension] ✅ Image downloaded successfully
+```
+
+### View Logs on Real Device
+
+**Option 1: Xcode Device Console**
+1. Connect device via USB
+2. Xcode → Window → Devices and Simulators
+3. Select your device
+4. Click **"Open Console"**
+5. Filter by "SwanSDK Extension"
+
+**Option 2: Console.app (macOS)**
+1. Open Console app on Mac
+2. Select your connected device
+3. Search for "SwanSDK Extension"
+
+---
+
+## Troubleshooting
+
+### Extension logs don't appear
+
+**Symptom:** No `[SwanSDK Extension]` logs when notification arrives
+
+**Possible causes:**
+
+1. **Missing mutable-content: 1**
+   - Check FCM payload includes `mutable-content: 1` in APNS
+   - Without it, iOS won't trigger the extension
+
+2. **App Groups not configured**
+   - Verify both targets have "App Groups" capability
+   - Verify App Group ID is `group.swan.sdk.notifications` in BOTH targets
+   - IDs must match exactly (no typos!)
+
+3. **Extension not included in build**
+   - In Xcode, go to Product → Scheme → Edit Scheme
+   - Check that SwanNotificationServiceExtension is included
+
+4. **Testing on simulator**
+   - Push notifications don't work on iOS Simulator
+   - Test on a real device
+
+### Extension runs but no ACK sent
+
+**Symptom:** See extension logs but backend doesn't receive ACK
+
+**Possible causes:**
+
+1. **Credentials not saved to App Group**
+   - Ensure SDK is initialized: `SwanSDK.init({ appId: '...' })`
+   - Credentials are saved automatically on init
+   - Check logs for: `[SharedCredentials] ✅ Credentials saved to iOS App Group`
+
+2. **App Group ID mismatch**
+   - Extension uses `group.swan.sdk.notifications` by default
+   - If you changed it, update `NotificationService.swift` line 143
+
+3. **Network issue**
+   - Extension has only 30 seconds to complete
+   - Check device has internet connection
+
+### Images not appearing
+
+**Symptom:** Notification arrives but image doesn't display
+
+**Possible causes:**
+
+1. **Image URL invalid**
+   - Check image URL is accessible (try in browser)
+   - Must be HTTPS (HTTP won't work)
+
+2. **Image format unsupported**
+   - Supported: JPEG, PNG, GIF
+   - Max size: 10MB (iOS limit)
+
+3. **mutable-content missing**
+   - Extension won't run without `mutable-content: 1`
+
+### Build errors
+
+**Error:** `No such module 'UserNotifications'`
+- Solution: Make sure deployment target is iOS 10.0+
+
+**Error:** `Use of undeclared type 'UNNotificationServiceExtension'`
+- Solution: Verify extension target is set to iOS 10.0+ deployment target
+
+**Error:** `Could not find or use auto-linked library 'swiftFoundation'`
+- Solution: Add `use_frameworks!` to Podfile
+
+**Error:** `CocoaPods Error: Unable to find compatibility version string for object version '70'`
+- Solution: In Xcode, select your Project (blue icon) → Build Settings (or Info) → Project Format. Change it to **Xcode 16.0-compatible** or later.
+
+---
+
+## Customization
+
+### Custom App Group ID
+
+If you want to use a different App Group ID:
+
+1. **In Xcode:** Update App Groups in both targets to use your custom ID (e.g., `group.com.yourcompany.app`)
+
+2. **In SDK:** Configure before calling `SwanSDK.init()`:
+
+```typescript
+import { SharedCredentialsManager } from 'swan-react-native-sdk';
+
+// Set custom App Group ID BEFORE SDK init
+SharedCredentialsManager.setAppGroupId('group.com.yourcompany.app');
+
+// Then initialize SDK
+await SwanSDK.init({ appId: 'YOUR_APP_ID' });
+```
+
+3. **In Extension:** Update `NotificationService.swift`:
+
+```swift
+let appGroupId = "group.com.yourcompany.app"
+```
+
+
+
+## FAQs
+
+### Q: Do I need to modify the extension code?
+
+**A:** No. The extension works out of the box. Only modify if you need custom App Group ID.
+
+### Q: Will this increase my app size?
+
+**A:** Minimally. The extension adds ~50KB to your IPA.
+
+### Q: Does this affect app performance?
+
+**A:** No. The extension runs in a separate process and only when notifications arrive.
+
+### Q: Can I test without archiving?
+
+**A:** Yes, but you must run on a real device. Push doesn't work on simulator.
+
+### Q: What if I already have a Notification Service Extension?
+
+**A:** You'll need to merge Swan's code into your existing extension. The key parts are:
+1. Reading credentials from App Group
+2. Sending delivery ACK
+3. Downloading images
+
+### Q: Do I need this for Android?
+
+**A:** No. Android data-only push notifications work without an extension. This is iOS-only.
+
+---
+
+## Support
+
+If you encounter issues:
+
+1. Check logs in Xcode Device Console
+2. Verify all steps in this guide
+3. Test with the provided FCM payload example
+4. Check that App Group IDs match in both targets
+
+For detailed debugging, enable verbose logging:
+- Main app: `SwanSDK.setLoggingEnabled(true)`
+- Extension: Logs are always enabled, check Device Console
+
+---
+
+## Summary
+
+✅ **Install:** `npm install react-native-shared-group-preferences`
+✅ **Xcode:** Add extension target + configure App Groups
+✅ **Run:** `node node_modules/swan-react-native-sdk/scripts/setup-ios-extension.js`
+✅ **Test:** Archive and test on real device
+
+That's it! Your iOS notifications now have reliable delivery tracking and rich media support. 🎉

package/ios/README.md

@@ -0,0 +1,64 @@
+# Swan SDK - iOS Notification Service Extension
+
+This directory contains the Notification Service Extension for iOS, which enables:
+- ✅ Delivery tracking when app is killed or backgrounded
+- ✅ Rich media support (images in notifications)
+- ✅ Reliable ACKs in all app states
+
+## Quick Setup
+
+### Step 1: Run Setup Script
+
+From your React Native project root:
+
+```bash
+node node_modules/swan-react-native-sdk/scripts/setup-ios-extension.js
+```
+
+This will:
+- Copy extension files to your `ios/` directory
+- Validate dependencies
+- Show setup instructions
+
+### Step 2: Configure in Xcode
+
+Follow the instructions shown by the setup script to:
+1. Add extension target to Xcode
+2. Configure App Groups
+3. Replace auto-generated files
+
+### Step 3: Update FCM Payload
+
+Ensure your backend includes `mutable-content: 1` in APNS:
+
+```json
+{
+  "apns": {
+    "payload": {
+      "aps": {
+        "alert": { "title": "...", "body": "..." },
+        "mutable-content": 1
+      }
+    }
+  }
+}
+```
+
+## Full Documentation
+
+See complete setup guide: [docs/IOS_NOTIFICATION_EXTENSION_SETUP.md](../docs/IOS_NOTIFICATION_EXTENSION_SETUP.md)
+
+## Files
+
+- **SwanNotificationServiceExtension/** - Extension source code
+  - `NotificationService.swift` - Main extension logic
+  - `Info.plist` - Extension configuration
+  - `SwanNotificationServiceExtension.entitlements` - App Group permissions
+
+## Support
+
+For issues or questions:
+1. Check the full documentation
+2. Verify App Groups are configured correctly
+3. Test on a real device (not simulator)
+4. Check Xcode Device Console for logs

package/ios/SwanNotificationServiceExtension/Info.plist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>SwanNotificationServiceExtension</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.usernotifications.service</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).NotificationService</string>
+	</dict>
+</dict>
+</plist>