Generated Docs for "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 scriptTry updating CI step to use gem to pin cocoapods version---------Co-authored-by: Evan Masseau <>" (#114) * 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 <> * Generated docs for ed0836a --------- 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 21, 2024 · 6cc0fb7 · 6cc0fb7
1 parent 9e8c460
commit 6cc0fb7
Show file tree

Hide file tree

Showing 22 changed files with 429 additions and 130 deletions.
diff --git a/.github/workflows/ios-ci.yml b/.github/workflows/ios-ci.yml
@@ -58,8 +58,8 @@ jobs:
       - name: Install cocoapods
         if: env.turbo_cache_hit != 1 && steps.cocoapods-cache.outputs.cache-hit != 'true'
         run: |
-          cd example/ios
-          pod install
+          yarn example-setup
+          rm -f example/ios/.xcode.env.local
         env:
           NO_FLIPPER: 1
 

diff --git a/README.md b/README.md
@@ -3,7 +3,38 @@
 [![Android](https://github.com/klaviyo/klaviyo-react-native-sdk/actions/workflows/android-ci.yml/badge.svg?branch=master&event=push)](https://github.com/klaviyo/klaviyo-react-native-sdk/actions/workflows/android-ci.yml)
 [![iOS](https://github.com/klaviyo/klaviyo-react-native-sdk/actions/workflows/ios-ci.yml/badge.svg?branch=master&event=push)](https://github.com/klaviyo/klaviyo-react-native-sdk/actions/workflows/ios-ci.yml)
 
-⚠️ This repository is in beta development ⚠️
+> ⚠️ This repository is in beta development ⚠️
+
+## Contents
+
+- [klaviyo-react-native-sdk](#klaviyo-react-native-sdk)
+  - [Introduction](#introduction)
+  - [Requirements](#requirements)
+    - [React Native](#react-native)
+    - [Android](#android)
+    - [iOS](#ios)
+  - [Installation](#installation)
+    - [Android](#android-1)
+    - [iOS](#ios-1)
+  - [Initialization](#initialization)
+  - [Identifying a Profile](#identifying-a-profile)
+    - [Reset Profile](#reset-profile)
+    - [Anonymous Tracking](#anonymous-tracking)
+  - [Event Tracking](#event-tracking)
+  - [Push Notifications](#push-notifications)
+    - [Prerequisites](#prerequisites)
+    - [Setup](#setup)
+    - [Collecting Push Tokens](#collecting-push-tokens)
+    - [Receiving Push Notifications](#receiving-push-notifications)
+    - [Rich Push](#rich-push)
+    - [Tracking Open Events](#tracking-open-events)
+    - [Deep Linking](#deep-linking)
+  - [Troubleshooting](#troubleshooting)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code Documentation](#code-documentation)
+
+## Introduction
 
 The Klaviyo React Native SDK allows developers to incorporate Klaviyo analytics and push notification functionality in
 their React Native applications for Android and iOS. It is a Typescript wrapper (native module bridge) around the native
@@ -19,21 +50,26 @@ Once integrated, your marketing team will be able to better understand your app
 push notifications via FCM (Firebase Cloud Messaging) and APNs (Apple Push Notification Service).
 
 ## Requirements
+
 For initial beta release, the SDK was developed and tested against the latest minor release of React Native (0.73).
 We are actively testing and expanding support to the latest patch releases of recent minor versions of React Native.
 
 ### React Native
+
 - `0.68.7+` - We have successfully compiled this SDK on a bare React Native template app down to `0.68.7`.
   Testing is ongoing to verify on older versions.
 
 ### Android
+
 - `minSdkVersion` of `23+`
 - `compileSdkVersion` of `34+`
 
 ### iOS
+
 - Minimum Deployment Target `13.0+`
 
 ## Installation
+
 The Klaviyo React Native SDK is available via [NPM](http://npmjs.com). To add it to your project,
 run the following from your project's root directory:
 
@@ -45,15 +81,46 @@ npm install klaviyo-react-native-sdk
 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
+  - 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
+
+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.
+
 #### 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:
@@ -76,38 +143,14 @@ pod install
 ```
 > ℹ️ 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.
 
-#### iOS Troubleshooting
-If you are seeing issues related to `minimum deployment target` when installing pods, you may need to update your
-minimum iOS version to 13.0 in your Podfile with one of the following strategies.
-- Specify iOS version directly in the `Podfile`:
-  ```ruby
-  MIN_IOS_OVERRIDE = '13.0'
-  if Gem::Version.new(MIN_IOS_OVERRIDE) > Gem::Version.new(min_ios_version_supported)
-      min_ios_version_supported = MIN_IOS_OVERRIDE
-  end
-  # existing code
-  platform :ios, min_ios_version_supported
-  ```
-- Set the deployment target to 13.0 in XCode, and then pull `IPHONEOS_DEPLOYMENT_TARGET` from the XCode project:
-  ```ruby
-  #######
-  # Read min iOS version from Xcode project and set as min iOS version for Podfile
-  require 'xcodeproj'
-
-  project_path = './YOUR_XCODE_PROJECT.xcodeproj'
-  project = Xcodeproj::Project.open(project_path)
-  min_ios_version_supported = project.build_configurations.first.build_settings['IPHONEOS_DEPLOYMENT_TARGET']
-  ######
-
-  platform :ios, min_ios_version_supported
-  ```
-
 ## 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
@@ -118,6 +161,10 @@ The SDK provides methods to identify profiles via the
 [Create Client Profile API](https://developers.klaviyo.com/en/reference/create_client_profile).
 A profile can be identified by any combination of the following:
 
+The SDK provides methods to identify profiles via the
+[Create Client Profile API](https://developers.klaviyo.com/en/reference/create_client_profile).
+A profile can be identified by any combination of the following:
+
 - External ID: A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system,
   such as a point-of-sale system. Format varies based on the external system.
 - Individual's email address
@@ -160,6 +207,7 @@ Klaviyo.setProfileAttribute(ProfilePropertyKey.FIRST_NAME, 'Kermit');
 Either way, the native SDKs will group and batch API calls to improve performance.
 
 ### Reset Profile
+
 To start a _new_ profile altogether (e.g. if a user logs out), either call `Klaviyo.resetProfile()`
 to clear the currently tracked profile identifiers (e.g. on logout), or use `Klaviyo.setProfile(profile)`
 to overwrite it with a new profile object.
@@ -171,11 +219,13 @@ Klaviyo.resetProfile();
 ```
 
 ### Anonymous Tracking
+
 Klaviyo will track unidentified users with an autogenerated ID whenever a push token is set or an event is created.
 That way, you can collect push tokens and track events prior to collecting profile identifiers such as email or
 phone number. When an identifier is provided, Klaviyo will merge the anonymous user with an identified user.
 
 ## Event Tracking
+
 The SDK also provides tools for tracking analytics events via the
 [Create Client Event API](https://developers.klaviyo.com/en/reference/create_client_event).
 A list of common Klaviyo-defined event metrics is provided in [`MetricName`](https://github.com/klaviyo/klaviyo-react-native-sdk/blob/master/src/Event.ts),
@@ -208,54 +258,68 @@ Klaviyo.createEvent({
 ## Push Notifications
 
 ### Prerequisites
+
 Integrating push notifications is highly platform-specific. Begin by thoroughly reviewing the setup
 instructions for Push Notifications in the README from each native Klaviyo SDK:
+
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Push-Notifications)
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Push-Notifications)
 
 ### Setup
+
 Refer to the following README sections on push setup:
+
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Setup)
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Setup)
 
 ### Collecting Push Tokens
+
 Push tokens must be collected in the native layer. 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.
 
 ### Receiving Push Notifications
+
 You can send test notifications to a specific token using the
 [push notification preview](https://help.klaviyo.com/hc/en-us/articles/18011985278875)
 feature in order to test your integration.
 
 #### Rich Push
+
 [Rich Push](https://help.klaviyo.com/hc/en-us/articles/16917302437275) is the ability to add images to
 push notification messages. On iOS, you will need to implement an extension service to attach images to notifications.
 No additional setup is needed to support rich push on Android.
+
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Rich-Push)
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Rich-Push)
 
 #### Tracking Open Events
+
 Klaviyo tracks push opens events with a specially formatted event `Opened Push` that includes message tracking
 parameters in the event properties. To track push opens, you will need to follow platform-specific instructions:
+
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Tracking-Open-Events)
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Tracking-Open-Events)
 
 #### Deep Linking
+
 [Deep Links](https://help.klaviyo.com/hc/en-us/articles/14750403974043) allow you to navigate to a particular
 page within your app in response to the user opening a notification. Familiarize yourself with the
 [React Native Guide](https://reactnative.dev/docs/linking) to deep linking, then read through the platform-specific
 instructions below.
+
 - [Android](https://github.com/klaviyo/klaviyo-android-sdk#Deep-Linking) instructions for handling intent filters
 - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk#Deep-Linking)
   As shown in the native SDK documentation, you can follow option 1 or 2.
-  
+
   With option 1, when you handle the open url (in [`application(_:open:options)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623112-application)),
   you call the linking code block above similar to what you would do with option 1.
 
@@ -281,13 +345,22 @@ Linking.getInitialURL().then((url) => {
 });
 ```
 
+## Troubleshooting
+
+Use the [troubleshooting guide](Troubeshooting.md) to resolve common issues with the Klaviyo React Native SDK.
+If the issues you are facing isn't in the troubleshooting guide, and you believe it's a bug in the SDK, please file an issue in our repository.
+
 ## Contributing
+
 Refer to the [contributing guide](.github/CONTRIBUTING.md) to learn how to contribute to the Klaviyo React Native SDK.
 We welcome your feedback in the [discussion](https://github.com/klaviyo/klaviyo-react-native-sdk/discussions)
 and [issues](https://github.com/klaviyo/klaviyo-react-native-sdk/issues) sections of our public GitHub repository.
 
 ## License
 The Klaviyo React Native SDK is available under the terms of the MIT license. See [LICENSE](./LICENSE) for more info.
 
+The Klaviyo React Native SDK is available under the terms of the MIT license. See [LICENSE](./LICENSE) for more info.
+
 ## Code Documentation
+
 Browse complete autogenerated code documentation [here](https://klaviyo.github.io/klaviyo-react-native-sdk/).
diff --git a/Troubeshooting.md b/Troubeshooting.md
@@ -0,0 +1,41 @@
+# Troubleshooting Guide
+
+## Android Troubleshooting
+
+1. 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.
+
+## iOS Troubleshooting
+
+### CocoaPods Installation Issues
+
+1. If you are seeing issues related to `minimum deployment target` when installing pods, you may need to update your
+   minimum iOS version to 13.0 in your Podfile with one of the following strategies.
+
+   - Specify iOS version directly in the `Podfile`:
+     ```ruby
+     MIN_IOS_OVERRIDE = '13.0'
+     if Gem::Version.new(MIN_IOS_OVERRIDE) > Gem::Version.new(min_ios_version_supported)
+         min_ios_version_supported = MIN_IOS_OVERRIDE
+     end
+     # existing code
+     platform :ios, min_ios_version_supported
+     ```
+   - Set the deployment target to 13.0 in XCode, and then pull `IPHONEOS_DEPLOYMENT_TARGET` from the XCode project:
+
+     ```ruby
+     #######
+     # Read min iOS version from Xcode project and set as min iOS version for Podfile
+     require 'xcodeproj'
+
+     project_path = './YOUR_XCODE_PROJECT.xcodeproj'
+     project = Xcodeproj::Project.open(project_path)
+     min_ios_version_supported = project.build_configurations.first.build_settings['IPHONEOS_DEPLOYMENT_TARGET']
+     ######
+
+     platform :ios, min_ios_version_supported
+     ```
+
+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.
diff --git a/docs/assets/highlight.css b/docs/assets/highlight.css
@@ -7,16 +7,16 @@
     --dark-hl-2: #D4D4D4;
     --light-hl-3: #A31515;
     --dark-hl-3: #CE9178;
-    --light-hl-4: #0070C1;
-    --dark-hl-4: #4FC1FF;
-    --light-hl-5: #AF00DB;
-    --dark-hl-5: #C586C0;
-    --light-hl-6: #267F99;
-    --dark-hl-6: #4EC9B0;
-    --light-hl-7: #0000FF;
-    --dark-hl-7: #569CD6;
-    --light-hl-8: #001080;
-    --dark-hl-8: #9CDCFE;
+    --light-hl-4: #AF00DB;
+    --dark-hl-4: #C586C0;
+    --light-hl-5: #001080;
+    --dark-hl-5: #9CDCFE;
+    --light-hl-6: #0000FF;
+    --dark-hl-6: #569CD6;
+    --light-hl-7: #0070C1;
+    --dark-hl-7: #4FC1FF;
+    --light-hl-8: #267F99;
+    --dark-hl-8: #4EC9B0;
     --light-hl-9: #098658;
     --dark-hl-9: #B5CEA8;
     --light-code-background: #FFFFFF;