klaviyo
diff --git a/Diff for: ‎README.md
+119-76 b/Diff for: ‎README.md
+119-76
diff --git a/Diff for: ‎Troubeshooting.md
+7 b/Diff for: ‎Troubeshooting.md
+7
diff --git a/Diff for: ‎docs/assets/highlight.css
+14 b/Diff for: ‎docs/assets/highlight.css
+14
@@ -17,6 +17,8 @@
     - [Android](#android-1)
     - [iOS](#ios-1)
   - [Initialization](#initialization)
+    - [React Native Initialization](#react-native-initialization)
+    - [Native Initialization](#native-initialization)
   - [Identifying a Profile](#identifying-a-profile)
     - [Reset Profile](#reset-profile)
     - [Anonymous Tracking](#anonymous-tracking)
@@ -25,6 +27,8 @@
     - [Prerequisites](#prerequisites)
     - [Setup](#setup)
     - [Collecting Push Tokens](#collecting-push-tokens)
+      - [React Native Token Collection](#react-native-token-collection)
+      - [Native Token Collection](#native-token-collection)
     - [Receiving Push Notifications](#receiving-push-notifications)
     - [Rich Push](#rich-push)
     - [Tracking Open Events](#tracking-open-events)
@@ -86,9 +90,11 @@ yarn add klaviyo-react-native-sdk
 ```
 
 ### Example App
+
 We have included a bare-bones example app in this repository for reference of how to integrate with our SDK.
 It is primarily intended to give code samples such as how and where to `initialize` or how to implement notification
 delegate methods on iOS. To actually run the example app:
+
 - Clone this repository
 - From the root directory, run `yarn example-setup`. This is an alias that will do the following:
   - Run `yarn install --immutable` from the root directory
@@ -129,85 +135,28 @@ Install [Cocoapods](https://cocoapods.org/) if you have not already.
 
 ## Initialization
 
-The SDK must be initialized with the short alphanumeric
-[public API key](https://help.klaviyo.com/hc/en-us/articles/115005062267#difference-between-public-and-private-api-keys1)
-for your Klaviyo account, also known as your Site ID. Initialization is done in the native layer, and must occur before
-any other SDK methods can be invoked. Follow the native SDK instructions for initialization, and refer to the
-[example app](./example) in this repository for guidance:
-
-- [Android SDK instructions](https://github.com/klaviyo/klaviyo-android-sdk#Initialization), and
-  [example app `MainApplication.kt`](./example/android/app/src/main/java/com/klaviyoreactnativesdkexample/MainApplication.kt#L39)
-- [iOS SDK instructions](https://github.com/klaviyo/klaviyo-swift-sdk#Initialization), and
-  [example app `AppDelegate.mm`](./example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm#L14)
-
-### Example App
-We have included a bare-bones example app in this repository for reference of how to integrate with our SDK.
-It is primarily intended to give code samples such as how and where to `initialize` or how to implement notification
-delegate methods on iOS. To actually run the example app:
-- Clone this repository
-- From the root directory, run `yarn example-setup`. This is an alias that will do the following:
-  - Run `yarn install --immutable` from the root directory
-  - Navigate to the `example` directory and run `bundle install`
-  - Navigate to the `example/ios` directory and run `bundle exec pod install`
-- From the project's root directory, run `yarn example start` to start the example application. Follow the
-  metro instructions from here, i.e. press `i` to run on iOS or `a` to run on Android.
-
-### Android
-
-Android installation requirements may vary depending upon your project configuration and other dependencies.
-The Klaviyo React Native SDK's `build.gradle` file exposes transitive dependencies upon the Klaviyo Android SDK,
-so you can import Android Klaviyo SDK references from your Kotlin/Java files without modifying your gradle configuration.
-
-#### React Native 0.73.x
-
-There are no additional installation requirements. Android support is fully tested and verified,
-including `minSdkVersion=23`.
-
-#### React Native 0.68.x - 0.72.x
-
-We have successfully compiled the Klaviyo React Native SDK in a bare React Native template app for these versions
-with the following modifications to the `android/build.gradle` file:
-
-- Set `compileSdkVersion=34`
-- Set `minSdkVersion=23`
-
-#### React Native <= 0.67.x
-
-We are actively working to verify compatibility with these versions. If you encounter issues, please file an issue.
-
-### iOS
+The SDK must be initialized with the short alphanumeric [public API key](https://help.klaviyo.com/hc/en-us/articles/115005062267#difference-between-public-and-private-api-keys1)
+for your Klaviyo account, also known as your Site ID.
 
-After installing the npm package, run the following command in the `ios` directory of your React Native project.
-Install [Cocoapods](https://cocoapods.org/) if you have not already.
+Initialize _must_ be called prior to invoking any other SDK methods so that Klaviyo SDK can track profiles, events and push tokens toward the correct Klaviyo account.
+Any SDK operations invoked before initialize will be dropped, and result in a logged error.
 
-#### React Native 0.68.x - 0.72.x
-We have successfully compiled the Klaviyo React Native SDK in a bare React Native template app for these versions
-with the following modifications to the `android/build.gradle` file:
-- Set `compileSdkVersion=34`
-- Set `minSdkVersion=23`
+You can call `initialize` from your app's React Native layer or from the platform-specific native code.
+This decision is dependent on your app's architecture. It is not required to initialize the SDK in both places!
+Note: It is safe to re-initialize, e.g. if your app needs to connect to more than one Klaviyo account.
 
-#### React Native <= 0.67.x
-We are actively working to verify compatibility with these versions. If you encounter issues, please file an issue.
+### React Native Initialization
 
-#### Android Troubleshooting
-- We have seen projects, particularly on react-native versions `0.72.x` and `0.71.x`, that required a `minSdkVersion`
-  of `24`, despite the Klaviyo Android SDK supporting API 23+. If you encounter this, please file an issue in our
-  repository and provide version numbers of your react-native dependencies.
+Below is an example of how to initialize the SDK from your React Native code:
 
-### iOS
-After installing the npm package, run the following command in the `ios` directory of your React Native project.
-Install [Cocoapods](https://cocoapods.org/) if you have not already.
-```sh
-pod install
+```typescript
+import { Klaviyo } from 'klaviyo-react-native-sdk';
+Klaviyo.initialize('YOUR_KLAVIYO_PUBLIC_API_KEY');
 ```
-> ℹ️ if the above command is outputting version mismatch errors for `KlaviyoSwift`, please run `pod update KlaviyoSwift` as indicated in the error message to update your local pods spec repo.
 
-## Initialization
+### Native Initialization
 
-The SDK must be initialized with the short alphanumeric
-[public API key](https://help.klaviyo.com/hc/en-us/articles/115005062267#difference-between-public-and-private-api-keys1)
-for your Klaviyo account, also known as your Site ID. Initialization is done in the native layer, and must occur before
-any other SDK methods can be invoked. Follow the native SDK instructions for initialization, and refer to the
+Follow the native SDK instructions for initialization, and refer to the
 [example app](./example) in this repository for guidance:
 
 - [Android SDK instructions](https://github.com/klaviyo/klaviyo-android-sdk#Initialization), and
@@ -333,17 +282,111 @@ Refer to the following README sections on push setup:
 
 ### Collecting Push Tokens
 
-Push tokens must be collected in the native layer. Follow the platform-specific instructions below:
+Push tokens can be collected either from your app's react native code or in the native code. Below sections discuss both approaches, and
+you are free to pick one that best suits your app's architecture. Note that doing this in one location is sufficient.
+
+#### React Native Token Collection
+
+In order to collect the APNs push token in your React Native code you need to:
+
+1.  Import a library such as [`@react-native-firebase/messaging`](https://www.npmjs.com/package/@react-native-firebase/messaging) to your react native project. The below instructions are specific for `@react-native-firebase/messaging` library.
+2.  Import Firebase iOS SDK to your iOS project. Setup instructions can be found [here](https://firebase.google.com/docs/ios/setup).
+3.  In order for the `UNUserNotificationCenter` delegate methods to be called in `AppDelegate`, method swizzling should be disabled for the Firebase SDK. For more information on this,
+    please refer to the [Firebase documentation](https://firebase.google.com/docs/cloud-messaging/ios/client). Disabling method swizzling be done by adding the following to your `Info.plist`:
+
+```xml
+<key>FirebaseAppDelegateProxyEnabled</key>
+<false/>
+```
+
+4. In `application:didRegisterForRemoteNotificationsWithDeviceToken:` method in your `AppDelegate.m` file, you can add the following code to set the push token to the firebase SDK:
+
+```objective-c
+// since we disbaled swizzling, we have to manually set this
+FIRMessaging.messaging.APNSToken = deviceToken;
+```
+
+5. Finally, in your React Native code, you can collect & set the push token as follows:
+
+```typescript
+import messaging from '@react-native-firebase/messaging';
+import { Klaviyo } from 'klaviyo-react-native-sdk';
+import { Platform } from 'react-native';
+
+const fetchAndSetPushToken = async () => {
+  try {
+    let deviceToken: string | null = null;
+    if (Platform.OS === 'android') {
+      deviceToken = await messaging().getToken();
+      console.log('FCM Token:', deviceToken);
+    } else {
+      deviceToken = await messaging().getAPNSToken();
+      console.log('APNs Token:', deviceToken);
+    }
+
+    if (deviceToken != null && deviceToken.length > 0) {
+      Klaviyo.setPushToken(deviceToken!);
+    }
+  } catch (error) {
+    console.error('Error in fetchAndSetPushToken:', error);
+  }
+};
+```
+
+For android token collection, there isn't any additional setup required on the native side. The above code should work as is.
+
+#### Native Token Collection
+
+Follow the platform-specific instructions below:
 
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Collecting-Push-Tokens)
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Collecting-Push-Tokens)
 
 #### Notification Permission
 
-Requesting user permission to display notifications can be managed in the native layer as instructed in our native SDK
-documentation, or with a third party library that provides cross-platform permissions APIs. If you opt for a
-cross-platform permission solution, you will still need to provide the Klaviyo SDK with the push token from the
-native layer after a permission change.
+Requesting user permission to display notifications can be managed in:
+
+1. The native layer as instructed in our native SDK documentation,
+
+   - [Android](https://github.com/klaviyo/klaviyo-android-sdk#collecting-push-tokens)
+   - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk?tab=readme-ov-file#request-push-notification-permission)
+
+   If you requested permission using native code then continue using Klaviyo's native platform SDKs `setToken` method to inform the SDK of permission change.
+
+2. Leveraging a third party library that provides cross-platform permissions APIs like firebase [`react-native-firebase/messaging`](https://www.npmjs.com/package/@react-native-firebase/messaging). If you opt for a
+   cross-platform permission solution, you can now call the Klaviyo's react native SDK's `setToken` method to refresh the token's enablement status.
+
+   Below is an example of how to use `@react-native-firebase/messaging` to request permission and set the token:
+
+```typescript
+import messaging from '@react-native-firebase/messaging';
+
+const requestUserPermission = async () => {
+  let isAuthorized = false;
+
+  if (Platform.OS === 'android') {
+    const androidAuthStatus = await PermissionsAndroid.request(
+      PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
+    );
+    isAuthorized = androidAuthStatus === 'granted';
+  } else if (Platform.OS === 'ios') {
+    const iOsAuthStatus = await messaging().requestPermission();
+    isAuthorized =
+      iOsAuthStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+      iOsAuthStatus === messaging.AuthorizationStatus.PROVISIONAL;
+  }
+
+  // refer the `fetchAndSetPushToken` method from the previous section for how to get and set the push token
+
+  if (isAuthorized) {
+    console.log('User has notification permissions enabled.');
+  } else {
+    console.log('User has notification permissions disabled');
+  }
+};
+```
+
+Note that either one of the above approaches is sufficient to inform the Klaviyo SDK of the permission change.
 
 ### Receiving Push Notifications
 
 
@@ -39,3 +39,10 @@
 
 2. If the command `pod install` is outputting version mismatch errors for `KlaviyoSwift`, please run `pod update KlaviyoSwift`
    as indicated in the error message to update your local pods spec repo.
+
+### `UNUserNotificationCenter` delegate methods not being called
+
+If you are not seeing the delegate methods for `UNUserNotificationCenter` being called in `AppDelegate`, there are two possible reasons for this,
+
+1. [Notifee](https://notifee.app/) intercepts the AppDelegate delegate methods and hence you may not receive the delegate calls if notifee is included in the iOS project. The solution is to remove notifee dependency from your project or exclude it for iOS.
+2. Firebase iOS SDK also swizzles AppDelegate methods when configured on your iOS app. If after disabling notifee, if the delegates are still not called, this may be the reason. Method swizzling can be turned off by following [Firebase's documentation](https://firebase.google.com/docs/cloud-messaging/ios/client).
@@ -19,6 +19,10 @@
     --dark-hl-8: #4EC9B0;
     --light-hl-9: #098658;
     --dark-hl-9: #B5CEA8;
+    --light-hl-10: #800000;
+    --dark-hl-10: #808080;
+    --light-hl-11: #800000;
+    --dark-hl-11: #569CD6;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -34,6 +38,8 @@
     --hl-7: var(--light-hl-7);
     --hl-8: var(--light-hl-8);
     --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --hl-11: var(--light-hl-11);
     --code-background: var(--light-code-background);
 } }
 
@@ -48,6 +54,8 @@
     --hl-7: var(--dark-hl-7);
     --hl-8: var(--dark-hl-8);
     --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --hl-11: var(--dark-hl-11);
     --code-background: var(--dark-code-background);
 } }
 
@@ -62,6 +70,8 @@
     --hl-7: var(--light-hl-7);
     --hl-8: var(--light-hl-8);
     --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --hl-11: var(--light-hl-11);
     --code-background: var(--light-code-background);
 }
 
@@ -76,6 +86,8 @@
     --hl-7: var(--dark-hl-7);
     --hl-8: var(--dark-hl-8);
     --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --hl-11: var(--dark-hl-11);
     --code-background: var(--dark-code-background);
 }
 
@@ -89,4 +101,6 @@
 .hl-7 { color: var(--hl-7); }
 .hl-8 { color: var(--hl-8); }
 .hl-9 { color: var(--hl-9); }
+.hl-10 { color: var(--hl-10); }
+.hl-11 { color: var(--hl-11); }
 pre, code { background: var(--code-background); }