Generated Docs for [CHNL-5370] Updating readme to include instruction…

…s on how to use `initialize` and `setToken` from RN code. (#113) * Link to license file in README (#60) Co-authored-by: Evan Masseau <> * Updated readme to include troubleshooting steps when running pod install (#63) updated readme * Updating version to 0.1.1 (#66) * 0.1.1 * updating version * reverting back to use older rn version * updating yarn lock * removing changes to package lock file * Fixes for React Native Apps <= 0.72.0 (#71) * Fix the react-native gradle dependency * Add a local property to enable specifying react-native version for the SDK for local development * Specify Kotlin version that is compatible with Android SDK's (although this didn't seem to actually cause any build errors) * Remove accidental use of an extension method that is technically SDK 24+ --------- Co-authored-by: Evan Masseau <> * Update local.properties template files (#68) * Add template local.properties file to example app * Be clearer about VCS status of these files. --------- Co-authored-by: Evan Masseau <> * Bump example iOS project lockfile (#74) I think this needs to be bumped when we increase the overall project version. Co-authored-by: Evan Masseau <> * Github CI Updates (#75) * Move doc bot to its own file so we don't have to see it as skipped all the time. * Use same ruby version as local dev environment * Stop using `yarn pod-install` because it creates an erroneous xcode.env.local file that breaks the hermes build scripts. --------- Co-authored-by: Evan Masseau <> * Updating to iOS SDK 3.0.2 (#77) * 0.1.1 * updated to us latest iOS SDK * removing package lock * Pod install | static linking issue | RCT Folly | Turbo modules (#70) * 0.1.1 * removed turbo module stuff and added xcconfig * removing package lock * comitting example app pod lock file --------- Co-authored-by: Evan Masseau <> Co-authored-by: Evan C Masseau <[email protected]> * Readme rewrite with references to native SDKs and Klaviyo help center (#62) --------- Co-authored-by: Evan Masseau <> Co-authored-by: Kenny Tsui <[email protected]> * Release 0.1.2 (#84) * 0.1.1 * Release 0.1.2 * removed package lock * podlock file changes * Break up CI files so we can get individual badges (#86) * Break up CI files so we can get individual badges * Add badges and fix names --------- Co-authored-by: Evan Masseau <> * Add action to publish to NPM after publishing a release (#82) --------- Co-authored-by: Evan Masseau <> * Update README.md (#90) * Publish to NPM with the default npm registry configured in package.json (#92) --------- Co-authored-by: Evan Masseau <> * Updated iOS instructions in example app (#99) * 0.1.1 * udpate the example app to implement push * hanlded deep links * removed package json lock file * updated to addressed Evan comments in the pr * Fix mistaken duplicate open push section (#95) Co-authored-by: Evan Masseau <> * Remove local.properties from git index (#96) * remove local.properties from git index, changes were still being tracked despite gitignore * missed variable --------- Co-authored-by: Evan Masseau <> * Update README.md (#105) * Update README.md * Update README.md * Implemented deep links to call react native in example iOS app (#104) * 0.1.1 * implemented deep linking calls to react native * removed unused method * removed package lock * added deep linking hanlder * [CHNL-5592] Adding troubleshooting guide linked from readme (#109) * 0.1.1 * added troubleshooting * removed packagfe lock * added troibleshoting to the contents * swapped android and ios * [Dependabot] Bump ip from 1.1.8 to 1.1.9 (#111) Bumps [ip](https://github.com/indutny/node-ip) from 1.1.8 to 1.1.9. - [Commits](indutny/node-ip@v1.1.8...v1.1.9) --- updated-dependencies: - dependency-name: ip dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Add example app instructions to README, make use of Gemfile (#97) * To make proper use of bundle, lockfile needs to be committed. I specified a cocoapods version since podfile.lock contains cocoapods version! Add explicit instructions about example app * Added alias for entire example app setup script Try updating CI step to use gem to pin cocoapods version --------- Co-authored-by: Evan Masseau <> * Bridge initialize and setPushToken to RN layer (#98) * Add an initialize method to react native layer * Add set push token to RN layer * Updated to latest versions of native SDKs * Elaboration on example app initialize/setPushToken, use a consistent value for example API key * SCREAMING_SNAKE_CASE --------- Co-authored-by: Evan Masseau <> * [CHNL-5370] Updating readme to include instructions on how to use `initialize` and `setToken` from RN code. (#113) * 0.1.1 * added troubleshooting * updated readme with initilize and set token instructions * adding notifee stuff to trouble shooting guide * removed duplicate android * removed package.json * some minor fixes * added example on requesting permission * Apply suggestions from code review Co-authored-by: Evan C Masseau <[email protected]> * minor updates * review comments * updated readme --------- Co-authored-by: Evan C Masseau <[email protected]> * Generated docs for bf5467b --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Evan C Masseau <[email protected]> Co-authored-by: Ajay Subramanya <[email protected]> Co-authored-by: Kenny Tsui <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: github-actions <[email protected]>
klaviyo · Feb 22, 2024 · da50348 · da50348
1 parent 8c12b00
commit da50348
Show file tree

Hide file tree

Showing 15 changed files with 277 additions and 214 deletions.
diff --git a/README.md b/README.md
@@ -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
 

diff --git a/Troubeshooting.md b/Troubeshooting.md
@@ -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).
diff --git a/docs/assets/highlight.css b/docs/assets/highlight.css
@@ -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); }