@loyalytics/swan-react-native-sdk 2.1.3-beta.0 → 2.1.3-beta.1

package/docs/Swan_Push_Notifications.postman_collection.json

@@ -0,0 +1,330 @@
+{
+	"info": {
+		"_postman_id": "swan-push-notifications-v1",
+		"name": "Swan SDK — Push Notifications",
+		"description": "Complete collection for testing all Swan SDK push notification types across Android and iOS.\n\n## Setup\n1. Set `project_id` to your Firebase project ID\n2. Set `fcm_token` to the device's FCM token\n3. Set `access_token` by running: `gcloud auth print-access-token`\n\n## How it works\n- All requests use the FCM v1 HTTP API\n- Variables are shared across all requests\n- Just update the token and send",
+		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+	},
+	"variable": [
+		{
+			"key": "project_id",
+			"value": "loyalytics-app",
+			"type": "string"
+		},
+		{
+			"key": "fcm_token",
+			"value": "<PASTE_DEVICE_FCM_TOKEN_HERE>",
+			"type": "string"
+		},
+		{
+			"key": "access_token",
+			"value": "<PASTE_GCLOUD_ACCESS_TOKEN_HERE>",
+			"type": "string"
+		},
+		{
+			"key": "fcm_url",
+			"value": "https://fcm.googleapis.com/v1/projects/{{project_id}}/messages:send",
+			"type": "string"
+		}
+	],
+	"item": [
+		{
+			"name": "Android",
+			"item": [
+				{
+					"name": "Standard Push",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"title\": \"Your order has shipped!\",\n      \"body\": \"Track your package #ABC123\",\n      \"channelId\": \"swan_transactional\",\n      \"route\": \"/orders/123\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Standard Push — With Image",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"title\": \"Summer Sale!\",\n      \"body\": \"50% off everything\",\n      \"channelId\": \"swan_promotional\",\n      \"route\": \"/sales/summer\",\n      \"image\": \"https://picsum.photos/id/1/1024/512\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Manual / Standard",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"manual\",\n      \"carouselVariant\": \"standard\",\n      \"title\": \"Weekend Flash Sale\",\n      \"body\": \"Swipe to explore deals!\",\n      \"defaultRoute\": \"/collections/weekend-sale\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/1/720/360\\\",\\\"title\\\":\\\"Summer Collection\\\",\\\"body\\\":\\\"50% off\\\",\\\"route\\\":\\\"/product/summer\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/20/720/360\\\",\\\"title\\\":\\\"New Arrivals\\\",\\\"body\\\":\\\"Just dropped\\\",\\\"route\\\":\\\"/product/new\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/30/720/360\\\",\\\"title\\\":\\\"Best Sellers\\\",\\\"body\\\":\\\"Top picks\\\",\\\"route\\\":\\\"/product/best\\\"}]\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Manual / Filmstrip",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"manual\",\n      \"carouselVariant\": \"filmstrip\",\n      \"title\": \"Trending Now\",\n      \"body\": \"See what's popular\",\n      \"defaultRoute\": \"/trending\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/40/720/360\\\",\\\"title\\\":\\\"Watches\\\",\\\"body\\\":\\\"From $99\\\",\\\"route\\\":\\\"/product/watches\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/50/720/360\\\",\\\"title\\\":\\\"Sneakers\\\",\\\"body\\\":\\\"New colors\\\",\\\"route\\\":\\\"/product/sneakers\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/60/720/360\\\",\\\"title\\\":\\\"Bags\\\",\\\"body\\\":\\\"Premium leather\\\",\\\"route\\\":\\\"/product/bags\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/70/720/360\\\",\\\"title\\\":\\\"Sunglasses\\\",\\\"body\\\":\\\"UV protection\\\",\\\"route\\\":\\\"/product/sunglasses\\\"}]\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Auto Scroll",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"auto\",\n      \"carouselVariant\": \"standard\",\n      \"carouselInterval\": \"4000\",\n      \"title\": \"Flash Deals\",\n      \"body\": \"Auto-scrolling deals!\",\n      \"defaultRoute\": \"/deals\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/10/720/360\\\",\\\"title\\\":\\\"Deal 1\\\",\\\"body\\\":\\\"60% off\\\",\\\"route\\\":\\\"/deal/1\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/11/720/360\\\",\\\"title\\\":\\\"Deal 2\\\",\\\"body\\\":\\\"Buy 1 Get 1\\\",\\\"route\\\":\\\"/deal/2\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/12/720/360\\\",\\\"title\\\":\\\"Deal 3\\\",\\\"body\\\":\\\"Free shipping\\\",\\\"route\\\":\\\"/deal/3\\\"}]\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Silent Push",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"silent\": \"true\",\n      \"action\": \"sync_config\"\n    },\n    \"android\": {\n      \"priority\": \"high\"\n    }\n  }\n}"
+						}
+					}
+				}
+			]
+		},
+		{
+			"name": "iOS",
+			"item": [
+				{
+					"name": "Standard Push",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"title\": \"Your order has shipped!\",\n      \"body\": \"Track your package #ABC123\",\n      \"route\": \"/orders/123\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"alert\",\n        \"apns-priority\": \"10\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"content-available\": 1\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Standard Push — With Image",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"title\": \"Summer Sale!\",\n      \"body\": \"50% off everything\",\n      \"route\": \"/sales/summer\",\n      \"image\": \"https://picsum.photos/id/1/1024/512\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"alert\",\n        \"apns-priority\": \"10\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"content-available\": 1\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Manual / Standard",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"manual\",\n      \"carouselVariant\": \"standard\",\n      \"title\": \"Weekend Flash Sale\",\n      \"body\": \"Swipe to explore deals!\",\n      \"defaultRoute\": \"/collections/weekend-sale\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/1/720/360\\\",\\\"title\\\":\\\"Summer Collection\\\",\\\"body\\\":\\\"50% off\\\",\\\"route\\\":\\\"/product/summer\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/20/720/360\\\",\\\"title\\\":\\\"New Arrivals\\\",\\\"body\\\":\\\"Just dropped\\\",\\\"route\\\":\\\"/product/new\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/30/720/360\\\",\\\"title\\\":\\\"Best Sellers\\\",\\\"body\\\":\\\"Top picks\\\",\\\"route\\\":\\\"/product/best\\\"}]\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"alert\",\n        \"apns-priority\": \"10\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"mutable-content\": 1,\n          \"category\": \"swan_carousel\",\n          \"alert\": {\n            \"title\": \"Weekend Flash Sale\",\n            \"body\": \"Swipe to explore deals!\"\n          }\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Manual / Filmstrip",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"manual\",\n      \"carouselVariant\": \"filmstrip\",\n      \"title\": \"Trending Now\",\n      \"body\": \"See what's popular\",\n      \"defaultRoute\": \"/trending\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/40/720/360\\\",\\\"title\\\":\\\"Watches\\\",\\\"body\\\":\\\"From $99\\\",\\\"route\\\":\\\"/product/watches\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/50/720/360\\\",\\\"title\\\":\\\"Sneakers\\\",\\\"body\\\":\\\"New colors\\\",\\\"route\\\":\\\"/product/sneakers\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/60/720/360\\\",\\\"title\\\":\\\"Bags\\\",\\\"body\\\":\\\"Premium leather\\\",\\\"route\\\":\\\"/product/bags\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/70/720/360\\\",\\\"title\\\":\\\"Sunglasses\\\",\\\"body\\\":\\\"UV protection\\\",\\\"route\\\":\\\"/product/sunglasses\\\"}]\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"alert\",\n        \"apns-priority\": \"10\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"mutable-content\": 1,\n          \"category\": \"swan_carousel\",\n          \"alert\": {\n            \"title\": \"Trending Now\",\n            \"body\": \"See what's popular\"\n          }\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Carousel — Auto Scroll",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"notificationType\": \"carousel\",\n      \"carouselMode\": \"auto\",\n      \"carouselVariant\": \"standard\",\n      \"carouselInterval\": \"4000\",\n      \"title\": \"Flash Deals\",\n      \"body\": \"Auto-scrolling deals!\",\n      \"defaultRoute\": \"/deals\",\n      \"channelId\": \"swan_notifications\",\n      \"carouselItems\": \"[{\\\"imageUrl\\\":\\\"https://picsum.photos/id/10/720/360\\\",\\\"title\\\":\\\"Deal 1\\\",\\\"body\\\":\\\"60% off\\\",\\\"route\\\":\\\"/deal/1\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/11/720/360\\\",\\\"title\\\":\\\"Deal 2\\\",\\\"body\\\":\\\"Buy 1 Get 1\\\",\\\"route\\\":\\\"/deal/2\\\"},{\\\"imageUrl\\\":\\\"https://picsum.photos/id/12/720/360\\\",\\\"title\\\":\\\"Deal 3\\\",\\\"body\\\":\\\"Free shipping\\\",\\\"route\\\":\\\"/deal/3\\\"}]\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"alert\",\n        \"apns-priority\": \"10\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"mutable-content\": 1,\n          \"category\": \"swan_carousel\",\n          \"alert\": {\n            \"title\": \"Flash Deals\",\n            \"body\": \"Auto-scrolling deals!\"\n          }\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				},
+				{
+					"name": "Silent Push",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{access_token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							}
+						],
+						"url": {
+							"raw": "{{fcm_url}}",
+							"host": ["{{fcm_url}}"]
+						},
+						"body": {
+							"mode": "raw",
+							"raw": "{\n  \"message\": {\n    \"token\": \"{{fcm_token}}\",\n    \"data\": {\n      \"silent\": \"true\",\n      \"action\": \"sync_config\"\n    },\n    \"apns\": {\n      \"headers\": {\n        \"apns-push-type\": \"background\",\n        \"apns-priority\": \"5\"\n      },\n      \"payload\": {\n        \"aps\": {\n          \"content-available\": 1\n        }\n      }\n    }\n  }\n}"
+						}
+					}
+				}
+			]
+		}
+	]
+}

package/docs/deep-link-attribution.md

@@ -0,0 +1,281 @@
+# Deep Link Attribution Tracking
+
+Track campaign clicks from email, SMS, and WhatsApp to measure which campaigns drive app engagement.
+
+## Overview
+
+When your marketing team sends emails, SMS, or WhatsApp messages containing links to your app, the Swan SDK automatically detects these clicks and reports them to the Swan backend for campaign attribution. This enables funnel tracking: **link click → app open → add to cart → purchase**.
+
+**No code changes required.** The SDK handles everything automatically after `init()`. Your existing deep link routing continues to work as-is — the SDK only adds silent attribution tracking on top.
+
+## How It Works
+
+```
+User receives email/SMS/WhatsApp with campaign link
+         ↓
+User taps link → App opens via deep link
+         ↓
+React Native Linking API fires → Swan SDK intercepts
+         ↓
+SDK checks for swan_ parameters in the URL
+         ↓
+  ┌─ swan_ params found → Send click ACK to Swan backend
+  └─ No swan_ params → Ignore (not a Swan campaign link)
+         ↓
+App's existing deep link routing handles navigation (unaffected)
+```
+
+The SDK supports both:
+- **Warm start** — app is already running in the background
+- **Cold start** — app is launched from a killed state via the deep link
+
+## Prerequisites
+
+For the SDK to receive deep links, your app must be configured to handle them at the platform level. Most React Native apps that support any form of deep linking already have this set up.
+
+### Android
+
+Add intent filters to your `AndroidManifest.xml` inside the `<activity>` tag for `MainActivity`:
+
+**Custom scheme** (e.g., `yourapp://products/123`):
+
+```xml
+<intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="yourapp" />
+</intent-filter>
+```
+
+**HTTPS App Links** (e.g., `https://yourstore.com/products/123`):
+
+```xml
+<intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="https" android:host="yourstore.com" />
+</intent-filter>
+```
+
+> For HTTPS App Links, you also need to host a Digital Asset Links file at `https://yourstore.com/.well-known/assetlinks.json`. See the [Android App Links documentation](https://developer.android.com/training/app-links) for details.
+
+### iOS
+
+**Custom scheme:**
+
+Add your URL scheme in Xcode: **Target → Info → URL Types → Add URL Scheme** (e.g., `yourapp`).
+
+Or in `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+    <dict>
+        <key>CFBundleURLSchemes</key>
+        <array>
+            <string>yourapp</string>
+        </array>
+    </dict>
+</array>
+```
+
+**AppDelegate setup:**
+
+Ensure your `AppDelegate.mm` passes URLs to React Native (this is included by default in most React Native projects):
+
+```objc
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
+{
+  return [RCTLinkingManager application:application openURL:url options:options];
+}
+
+// For Universal Links
+- (BOOL)application:(UIApplication *)application
+    continueUserActivity:(nonnull NSUserActivity *)userActivity
+      restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
+{
+  return [RCTLinkingManager application:application
+                   continueUserActivity:userActivity
+                     restorationHandler:restorationHandler];
+}
+```
+
+**Universal Links** (e.g., `https://yourstore.com/products/123`):
+
+1. Add the Associated Domains entitlement in Xcode: `applinks:yourstore.com`
+2. Host an `apple-app-site-association` file at `https://yourstore.com/.well-known/apple-app-site-association`
+
+See the [Apple Universal Links documentation](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) for details.
+
+### Expo
+
+Add the `scheme` property to your `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "yourapp"
+  }
+}
+```
+
+Then run `npx expo prebuild` to regenerate native projects.
+
+## Campaign URL Format
+
+For attribution tracking to work, the backend must append Swan parameters to the campaign links before sending them. The SDK looks for query parameters prefixed with `swan_`.
+
+### Required Parameters
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `swan_comm_id` | Communication ID (generated by Swan before sending) | `swan_comm_id=comm_abc123` |
+
+### Optional Parameters
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `swan_link_id` | Identifies which link within the message was clicked (useful for emails with multiple CTAs) | `swan_link_id=hero_banner` |
+
+### Example Campaign URLs
+
+**Email with multiple links:**
+```
+https://yourstore.com/sale?swan_comm_id=email_001&swan_link_id=hero_banner
+https://yourstore.com/products/shoes?swan_comm_id=email_001&swan_link_id=category_cta
+https://yourstore.com/cart?swan_comm_id=email_001&swan_link_id=footer_link
+```
+
+**SMS with single link:**
+```
+https://yourstore.com/offer/50off?swan_comm_id=sms_002
+```
+
+**WhatsApp with custom scheme:**
+```
+yourapp://products/flash-sale?swan_comm_id=wa_003&swan_link_id=buy_now
+```
+
+> URLs without `swan_comm_id` are silently ignored by the SDK — there is zero overhead for non-campaign links.
+
+## Integration
+
+**No code changes required.** The SDK sets up deep link listeners automatically during `init()`. As long as:
+
+1. Your app's platform configuration handles deep links (see Prerequisites above)
+2. Campaign URLs include `swan_comm_id` as a query parameter
+
+...the SDK will automatically track clicks and send them to the Swan backend.
+
+```javascript
+import SwanEcomSDK from '@loyalytics/swan-react-native-sdk';
+
+// This is all you need — deep link tracking is included automatically
+const sdk = SwanEcomSDK.getInstance('YOUR_APP_ID', {
+  isProduction: true,
+});
+```
+
+Your existing deep link navigation code continues to work unchanged. The SDK does not interfere with routing — it only reads the URL parameters for attribution.
+
+## Backend Webhook Payload
+
+When a campaign deep link is clicked, the SDK sends a click acknowledgment to the Swan webhook endpoint. The payload includes:
+
+```json
+{
+  "commId": "email_001",
+  "appId": "your-app-id",
+  "CDID": "customer-device-id",
+  "event": "clicked",
+  "deviceId": "device-id",
+  "type": "deepLink",
+  "linkId": "hero_banner"
+}
+```
+
+| Field | Always present | Description |
+|-------|---------------|-------------|
+| `commId` | Yes | The `swan_comm_id` from the URL |
+| `type` | Yes | Always `"deepLink"` — distinguishes from push notification clicks |
+| `event` | Yes | Always `"clicked"` |
+| `linkId` | Only if `swan_link_id` was in the URL | Identifies which specific link was clicked |
+| `appId` | Yes | Your app ID |
+| `CDID` | Yes | Customer device ID (logged-in user) or generated anonymous ID |
+| `deviceId` | Yes | Device identifier |
+
+## Testing
+
+### Android
+
+```bash
+# Campaign link with all parameters
+adb shell am start -a android.intent.action.VIEW \
+  -d "yourapp://products/123?swan_comm_id=test_001&swan_link_id=cta1"
+
+# Campaign link without link ID (single-link SMS)
+adb shell am start -a android.intent.action.VIEW \
+  -d "yourapp://offer?swan_comm_id=test_002"
+
+# Non-campaign link (should be silently ignored)
+adb shell am start -a android.intent.action.VIEW \
+  -d "yourapp://products/123?utm_source=google"
+```
+
+### iOS Simulator
+
+```bash
+# Campaign link with all parameters
+xcrun simctl openurl booted \
+  "yourapp://products/123?swan_comm_id=test_001&swan_link_id=cta1"
+
+# Campaign link without link ID
+xcrun simctl openurl booted \
+  "yourapp://offer?swan_comm_id=test_002"
+
+# Non-campaign link (should be silently ignored)
+xcrun simctl openurl booted \
+  "yourapp://products/123?utm_source=google"
+```
+
+### Expected Log Output
+
+Enable SDK logging to verify attribution tracking:
+
+```javascript
+SwanEcomSDK.setLoggingEnabled(true);
+```
+
+**Campaign link detected:**
+```
+[SwanSDK] Deep link received (warm start): yourapp://products/123?swan_comm_id=test_001&swan_link_id=cta1
+[SwanSDK] Deep link attribution: found SWAN parameters: {"swan_comm_id":"test_001","swan_link_id":"cta1"}
+[SwanSDK] Notification ACK queued: test_001 clicked
+```
+
+**Non-campaign link (no output):**
+```
+[SwanSDK] Deep link received (warm start): yourapp://products/123?utm_source=google
+```
+No further logs — the SDK silently ignores it.
+
+## FAQ
+
+**Q: Do I need to change any code in my app?**
+No. The SDK handles deep link attribution automatically. Your existing navigation and deep link routing remains unchanged.
+
+**Q: What if my app already uses React Navigation's deep linking?**
+That's fine. The SDK uses `Linking.addEventListener` to listen for URLs, which works alongside React Navigation's `linking` configuration. Both receive the URL — React Navigation handles routing, the SDK handles attribution.
+
+**Q: What happens if the user clicks a link but is offline?**
+The click event is queued in the SDK's local SQLite database and sent to the backend when the network is restored.
+
+**Q: Does this add any overhead for non-campaign links?**
+Negligible. The SDK checks for `swan_` prefixed parameters in the URL query string. If none are found, it returns immediately with no further processing.
+
+**Q: What SDK version is required?**
+Deep link attribution tracking is available from version **2.1.0** onwards.

package/ios/SwanNotificationContentExtension/Info.plist

@@ -0,0 +1,40 @@
+<?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>CFBundleDisplayName</key>
+	<string>SwanNotificationContent</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>NSExtensionAttributes</key>
+		<dict>
+			<key>UNNotificationExtensionCategory</key>
+			<array>
+				<string>swan_carousel</string>
+			</array>
+			<key>UNNotificationExtensionInitialContentSizeRatio</key>
+			<real>0.7</real>
+			<key>UNNotificationExtensionDefaultContentHidden</key>
+			<false/>
+		</dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.usernotifications.content-extension</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>SwanNotificationContentExtension.NotificationViewController</string>
+	</dict>
+</dict>
+</plist>