From 149cfd8bc2e88f4c8b0e6498e92013490942893c Mon Sep 17 00:00:00 2001 From: Evan C Masseau <5167687+evan-masseau@users.noreply.github.com> Date: Tue, 6 Feb 2024 16:33:15 -0500 Subject: [PATCH] Readme rewrite with references to native SDKs and Klaviyo help center (#62) --------- Co-authored-by: Evan Masseau <> Co-authored-by: Kenny Tsui <63658871+kennyklaviyo@users.noreply.github.com> --- .github/workflows/doc-bot.yml | 8 +- README.md | 294 +++++++++++------- .../AppDelegate.mm | 1 + .../PushNotificationsHelper.swift | 10 +- 4 files changed, 194 insertions(+), 119 deletions(-) diff --git a/.github/workflows/doc-bot.yml b/.github/workflows/doc-bot.yml index 7055f37..7fa9943 100644 --- a/.github/workflows/doc-bot.yml +++ b/.github/workflows/doc-bot.yml @@ -10,6 +10,7 @@ permissions: pull-requests: write jobs: + generate-documentation: runs-on: ubuntu-22.04 env: @@ -42,10 +43,15 @@ jobs: - name: Commit and push docs run: | + if [ $(git status -s -uno | wc -l) -eq 0 ]; then + echo "No documentation to change" + exit 0 + fi + git add docs git commit -m "${{ env.CI_COMMIT_MESSAGE }}" git push -u origin "documentation-${{ github.sha }}" - name: Create PR for doc updates run: | - gh pr create --draft --title "Generated Docs for \"$(git show -s --format=%B ${{ github.sha }})\"" --body "This PR was automatically generated by a GitHub Action for ${{ github.sha }}." -B "documentation" -H "documentation-${{ github.sha }}" + gh pr create --title "Generated Docs for \"$(git show -s --format=%B ${{ github.sha }})\"" --body "This PR was automatically generated by a GitHub Action for ${{ github.sha }}." -B "documentation" -H "documentation-${{ github.sha }}" diff --git a/README.md b/README.md index 2fdb3c2..32adfff 100644 --- a/README.md +++ b/README.md @@ -2,99 +2,124 @@ ⚠️ This repository is in beta development ⚠️ -Official Klaviyo React Native SDK +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 +Klaviyo iOS and Android SDKs. For more information on the native SDKs, please see the +[iOS](https://github.com/klaviyo/klaviyo-swift-sdk) and [Android](https://github.com/klaviyo/klaviyo-android-sdk). +repositories. This repo also contains a basic [React Native sample app](./example) to assist your integration. -## Overview +The SDK assists in identifying users and tracking user events via the latest [Klaviyo Client APIs](https://developers.klaviyo.com/en/reference/api_overview). +To reduce performance overhead, API requests are queued and sent in batches. The queue is persisted to local storage +so that data is not lost if the device is offline or the app is terminated. -klaviyo-react-native-sdk is an SDK, written in TypeScript, that can be integrated into your React Native App. -The SDK enables you to engage with your customers using push notifications. In addition, you will be able to take advantage of Klaviyo's identification and event tracking functionality. -Once integrated, your marketing team will be able to better understand your app users' needs and send them timely messages via APNs/Google FCM. +Once integrated, your marketing team will be able to better understand your app users' needs and send them timely +push notifications via FCM (Firebase Cloud Messaging) and APNs (Apple Push Notification Service). -This SDK is a wrapper (native module bridge) around the native Klaviyo iOS and Android SDKs. -For more information on the native SDKs, please see the [iOS](https://github.com/klaviyo/klaviyo-swift-sdk) and [Android](https://github.com/klaviyo/klaviyo-android-sdk) repositories. +## 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. -## 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: +### 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. -```sh -npm install klaviyo-react-native-sdk -``` +### Android +- `minSdkVersion` of `23+` +- `compileSdkVersion` of `34+` -### iOS Setup +### iOS +- Minimum Deployment Target `13.0+` -To get started with iOS setup, you need to run the following command in the `ios` directory of your React Native project: +## 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: ```sh -pod install -``` - -This may require you to install [Cocoapods](https://cocoapods.org/). - -Once you have installed all the dependencies using cocoapods, you should have access to the native Klaviyo iOS SDK which we will use in the following section to setup your react native iOS project. - -### Troubleshooting pod install issues - -if you are seeing issues with deployment versions when installing pods, -you may need to update you minimum iOS version to 13.0 in your Podfile. - -An example of overriding the minimum iOS version in your Podfile is shown below: - -```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 -``` - -Another option is to use `IPHONEOS_DEPLOYMENT_TARGET` from your Xcode project file like below, - -```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'] -###### +# Using npm +npm install klaviyo-react-native-sdk -platform :ios, min_ios_version_supported +# Using yarn +yarn add klaviyo-react-native-sdk ``` -### Android Setup - -For Android, there are no additional installation requirements. The React Native SDK gradle file exposes transitive dependencies upon the Klaviyo Android SDK -so you can import in your kotlin/java classes without modifying your gradle files. +### 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. -## SDK Initialization +#### React Native 0.73.x +There are no additional installation requirements. Android support is fully tested and verified, +including `minSdkVersion=23`. -Initialization should be done from the native layer: +#### 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` -### Android +#### React Native <= 0.67.x +We are actively working to verify compatibility with these versions. If you encounter issues, please file an issue. -Follow the [Android](https://github.com/klaviyo/klaviyo-android-sdk#Initialization) guide on initializing. +#### 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. ### iOS - -Here we'll create the native iOS SDK instance and initialize it with your Klaviyo public key. - -```swift -KlaviyoSDK().initialize(with: "YOUR_KLAVIYO_PUBLIC_API_KEY") +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 --repo-update ``` +#### 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 + [example app `AppDelegate.mm`](./example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm#L14) + ## Identifying a Profile +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 helpers for identifying profiles and syncing via the -[Klaviyo client API](https://developers.klaviyo.com/en/reference/create_client_profile). -All profile identifiers (email, phone, external ID, anonymous ID) are persisted to local storage -so that the SDK can keep track of the current profile. +- 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 +- Individual's phone number in [E.164 format](https://help.klaviyo.com/hc/en-us/articles/360046055671#h_01HE5ZYJEAHZKY6WZW7BAD36BG) -The Klaviyo SDK does not validate email address or phone number inputs locally. See -[documentation](https://help.klaviyo.com/hc/en-us/articles/360046055671-Accepted-phone-number-formats-for-SMS-in-Klaviyo) -for guidance on proper phone number formatting. +Identifiers are persisted to local storage on each platform so that the SDK can keep track of the current profile. Profile attributes can be set all at once: @@ -128,7 +153,12 @@ Klaviyo.setExternalId('12345'); Klaviyo.setProfileAttribute(ProfilePropertyKey.FIRST_NAME, 'Kermit'); ``` -If a user is logged out or if you want to reset the profile for some reason, use the following: +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. ```typescript import { Klaviyo } from 'klaviyo-react-native-sdk'; @@ -136,11 +166,16 @@ import { Klaviyo } from 'klaviyo-react-native-sdk'; Klaviyo.resetProfile(); ``` -## Event Tracking +### 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. -The SDK also provides tools for tracking analytics events to the Klaviyo API. -A list of common Klaviyo-defined event names is provided in [MetricName](https://github.com/klaviyo/klaviyo-react-native-sdk/blob/master/src/Event.ts), or -you can just provide a string for a custom event name. +## 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), +or you can just provide a string for a custom event name. Below is an example using one of the Klaviyo-defined event names: @@ -164,40 +199,75 @@ import { Klaviyo } from 'klaviyo-react-native-sdk'; Klaviyo.createEvent({ name: 'My Custom Event', }); -Klaviyo.createEvent(event); ``` ## Push Notifications -When setting up push notifications (including rich push notifications), you will need to follow directions from the [iOS](https://github.com/klaviyo/klaviyo-swift-sdk?tab=readme-ov-file#Push-Notifications) and [Android](https://github.com/klaviyo/klaviyo-android-sdk?tab=readme-ov-file#Push-Notifications) SDKs. - -## Deep Linking - -To handle deep links in your app, start by familiarizing yourself with the React Native [guide](https://reactnative.dev/docs/linking) to deep linking. Once you've done that, you should follow directions from the [iOS](https://github.com/klaviyo/klaviyo-swift-sdk?tab=readme-ov-file#Deep-Linking) and [Android](https://github.com/klaviyo/klaviyo-android-sdk?tab=readme-ov-file#Deep-Linking) SDKs. -The sections below give additional details for each platform as it pertains to React Native. - -### iOS - -As shown in the native SDK documentation, you can follow option 1 or 2. - -With option 1, when you get the callback, you can handle it as follows: - -```objective-c -[RCTLinkingManager application:application openURL:url options:options] -``` - -Since you won't have `options`, you can just pass in an empty dictionary for that parameter. - -With option 2, 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. - -### Android - -On Android, simply follow the [Android SDK docs](https://github.com/klaviyo/klaviyo-android-sdk?tab=readme-ov-file#Deep-Linking) on handling intent filters. - -### React Native Changes - -Then on the React Native side, you can handle the deep link as follows: +### 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) + +#### Tracking Open Events +To track push notification opens, you must call `Klaviyo.handlePush(intent)` when your app is launched from an intent. +This method will check if the app was opened from a notification originating from Klaviyo and if so, create an +`Opened Push` event with required message tracking parameters. For example: + +#### 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 get the callback, you can handle it as follows: + + ```objective-c + [RCTLinkingManager application:application openURL:url options:options] + ``` + + Since you won't have `options`, you can just pass in an empty dictionary for that parameter. + + With option 2, 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. + +In your React Native code, you can handle the deep link as follows: ```typescript import { Linking } from 'react-native'; @@ -211,15 +281,13 @@ Linking.getInitialURL().then((url) => { }); ``` -## Push Permissions - -It is recommended that handling push permissions be done from the native layer. On iOS, you can follow the [iOS](https://github.com/klaviyo/klaviyo-swift-sdk?tab=readme-ov-file#sending-push-notifications) guide on requesting permissions. On Android, you can follow the [Android](https://source.android.com/docs/core/display/notification-perm) guide on requesting permissions. - ## Contributing - -See the [contributing guide](.github/CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow. +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. -## License -The Klaviyo React Native SDK is available under 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/example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm b/example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm index 78af675..d321cc6 100644 --- a/example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm +++ b/example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm @@ -11,6 +11,7 @@ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:( // They will be passed down to the ViewController used by React Native. self.initialProps = @{}; + [PushNotificationsHelper initializeSDK]; [PushNotificationsHelper requestPushPermission]; return [super application:application didFinishLaunchingWithOptions:launchOptions]; diff --git a/example/ios/KlaviyoReactNativeSdkExample/PushNotificationsHelper.swift b/example/ios/KlaviyoReactNativeSdkExample/PushNotificationsHelper.swift index 9cdbf8e..99fc528 100644 --- a/example/ios/KlaviyoReactNativeSdkExample/PushNotificationsHelper.swift +++ b/example/ios/KlaviyoReactNativeSdkExample/PushNotificationsHelper.swift @@ -5,6 +5,11 @@ import KlaviyoSwift @objc(PushNotificationsHelper) class PushNotificationsHelper: NSObject { + @objc + static func initializeSDK() { + KlaviyoSDK().initialize(with: "YOUR_PUBLIC_API_KEY") + } + @objc static func requestPushPermission() { // since we need the SDK to be initialized before setting the push token to it @@ -30,9 +35,4 @@ class PushNotificationsHelper: NSObject { static func setPushToken(token: Data) { KlaviyoSDK().set(pushToken: token) } - - @objc - private static func initializeSDK() { - KlaviyoSDK().initialize(with: "YOUR_PUBLIC_API_KEY") - } }