@amplitude/plugin-engagement-react-native 0.1.1-alpha.10

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Amplitude, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PluginEngagementReactNative.podspec

@@ -0,0 +1,22 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "PluginEngagementReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://amplitude.com.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,cpp,swift}"
+  s.private_header_files = "ios/**/*.h"
+  #s.dependency "AmplitudeEngagementSwift"
+  s.dependency "AmplitudeEngagementSwift"
+  
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,95 @@
+# @amplitude/plugin-engagement-react-native
+
+Amplitude Engagement plugin for React Native
+
+## Installation
+
+To install:
+- Add `@amplitude/analytics-react-native` and `@amplitude/plugin-engagement-react-native`
+- Also, add `@react-native-async-storage/async-storage`
+  - Why? This is used by the `engagement` native module, but the CLI only auto links native modules which you directly depend on in your app’s `package.json`
+
+
+```sh
+npm install @amplitude/analytics-react-native
+npm install @amplitude/plugin-engagement-react-native
+npm install @react-native-async-storage/async-storage
+```
+
+Add the source for the `AmplitudeEngagementSwift` pod to your Podfile:
+```rb
+target '<your appname>' do
+  ...
+
+  pod "AmplitudeEngagementSwift", :git => "https://github.com/amplitude/Amplitude-Engagement-Swift"
+
+  ...
+end
+```
+
+Re-run `pod install` in the `ios` directory:
+```sh
+$ cd ios
+$ bundle exec pod install
+```
+
+## Usage
+
+### Setup code
+
+Setup by adding the plugin and calling “init” as usual:
+
+```
+// index.js
+
+import {Linking} from 'react-native';
+
+import { init, add } from '@amplitude/analytics-react-native';
+import { getPlugin, handleURL } from '@amplitude/plugin-engagement-react-native';
+
+init('<<< YOUR API KEY HERE >>>');
+add(getPlugin());
+
+Linking.getInitialURL().then(async (url) => {
+    if (url) {
+    const didHandleURL = await handleURL(url);
+    if (didHandleURL) { return; }
+
+    // Handle a non-Amplitude SDK URL
+    }
+});
+
+Linking.addEventListener('url', async ({ url }) => {
+    const didHandleURL = await handleURL(url);
+    if (didHandleURL) { return; }
+
+    // Handle a non-Amplitude SDK URL
+});
+```
+
+### Linking setup
+If you don't already have it set up, please follow this guide to enable deep-linking support in your React Native app in addition to adding the above Linking code:
+https://reactnative.dev/docs/linking#enabling-deep-links
+
+Then, following the Alpha Onboarding guide to setup the "scheme" for the deep links in your Android and iOS projects.
+
+### Boot
+
+Finally, “boot” with the user’s ID:
+
+```
+import {
+  boot
+} from '@amplitude/plugin-engagement-react-native';
+
+export default function App() {
+  useEffect(() => {
+    boot('rn-test-user-1', 'test-device-1');
+  }, []);
+
+```
+
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,89 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['PluginEngagementReactNative_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["PluginEngagementReactNative_" + name]).toInteger()
+}
+
+android {
+  namespace "com.amplitude.pluginengagementreactnative"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+  // Amplitude Engagement SDK
+  implementation "com.amplitude:amplitude-engagement-android:1.0.14"
+
+  // Amplitude Analytics SDK (required dependency)
+  implementation "com.amplitude:analytics-android:1.+"
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "PluginEngagementReactNative"
+  codegenJavaPackageName = "com.amplitude.pluginengagementreactnative"
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+PluginEngagementReactNative_kotlinVersion=2.0.21
+PluginEngagementReactNative_minSdkVersion=24
+PluginEngagementReactNative_targetSdkVersion=34
+PluginEngagementReactNative_compileSdkVersion=35
+PluginEngagementReactNative_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/amplitude/pluginengagementreactnative/PluginEngagementReactNativeModule.kt

@@ -0,0 +1,183 @@
+package com.amplitude.pluginengagementreactnative
+
+import android.app.Activity
+import android.app.Application
+import android.content.Intent
+import android.os.Bundle
+import android.util.Log
+import androidx.core.net.toUri
+import com.amplitude.android.engagement.AmplitudeEngagement
+import com.amplitude.android.engagement.__ReactNative__AESDK
+import com.amplitude.android.engagement.AmplitudeInitOptions
+import com.amplitude.android.engagement.ui.theme.ThemeMode
+import com.amplitude.core.events.BaseEvent
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Callback
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.module.annotations.ReactModule
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.runBlocking
+import java.util.concurrent.ConcurrentHashMap
+
+@ReactModule(name = PluginEngagementReactNativeModule.NAME)
+class PluginEngagementReactNativeModule(val reactContext: ReactApplicationContext) :
+  NativePluginEngagementReactNativeSpec(reactContext) {
+
+  private data class InstanceInfo(val apiKey: String, val instance: AmplitudeEngagement)
+
+  private var instances = ConcurrentHashMap<Double, InstanceInfo>()
+  private var _id: Double = 0.0
+
+  override fun getName(): String {
+    return NAME
+  }
+
+  override fun newInstance(apiKey: String): Double {
+    val existingId = instances.entries.firstOrNull { it.value.apiKey == apiKey }?.key
+    if (existingId != null) {
+      return existingId
+    }
+
+    return synchronized(this) {
+      runBlocking(Dispatchers.Main) {
+        val amplitudeEngagement = __ReactNative__AESDK(reactContext, apiKey, AmplitudeInitOptions())
+
+        // The React Native environment seems to have a different activity management lifecycle;
+        // so we need to register our own listener to get the current activity.
+        amplitudeEngagement.setCurrentActivity(reactContext.currentActivity)
+        val lifecycleEventListener: LifecycleEventListener = object : LifecycleEventListener {
+          override fun onHostResume() {
+            amplitudeEngagement.setCurrentActivity(reactContext.currentActivity)
+          }
+
+          override fun onHostPause() {
+          }
+
+          override fun onHostDestroy() {
+          }
+        }
+
+        reactContext.addLifecycleEventListener(lifecycleEventListener)
+
+        _id++
+        val id = _id
+        instances[id] = InstanceInfo(
+          apiKey,
+          amplitudeEngagement
+        )
+
+        id
+      }
+    }
+  }
+
+  override fun boot(id: Double, userId: String, deviceId: String) {
+    val instance = instances[id]?.instance ?: return
+
+    runBlocking(Dispatchers.Main) {
+      Log.d("PluginEngagementReactNativeModule", "boot: $userId, $deviceId")
+      instance.boot(userId, deviceId)
+    }
+  }
+
+  override fun setThemeMode(id: Double, themeMode: String?) {
+    val instance = instances[id]?.instance ?: return
+
+    runBlocking(Dispatchers.Main) {
+      if (themeMode != null) {
+        instance.setThemeMode(ThemeMode.valueOf(themeMode))
+      }
+    }
+  }
+
+  override fun reset(id: Double, key: String, stepIndex: Double) {
+    val instance = instances[id]?.instance ?: return
+    runBlocking(Dispatchers.Main) {
+      instance.reset(key, stepIndex.toInt())
+    }
+  }
+
+  override fun list(id: Double): WritableArray {
+    val writableArray = Arguments.createArray()
+    val instance = instances[id]?.instance ?: return writableArray
+    runBlocking(Dispatchers.Main) {
+      val guidesAndSurveysList = instance.list()
+      guidesAndSurveysList.forEach { guide ->
+        Log.d("PluginEngagementReactNativeModule", "list: $guide")
+        val map = Arguments.createMap();
+        map.putInt("id", guide.id);
+        map.putString("title", guide.title);
+        map.putString("status", guide.status);
+        map.putInt("step", guide.step);
+        writableArray.pushMap(map);
+      }
+    }
+    return writableArray
+}
+
+  override fun show(id: Double, key: String, stepIndex: Double) {
+    val instance = instances[id]?.instance ?: return
+    runBlocking(Dispatchers.Main) {
+      instance.show(key, stepIndex.toInt())
+    }
+  }
+
+  override fun screen(id: Double, screenName: String) {
+    val instance = instances[id]?.instance ?: return
+    runBlocking(Dispatchers.Main) {
+      instance.screen(screenName)
+    }
+  }
+
+  override fun closeAll(id: Double) {
+    val instance = instances[id]?.instance ?: return
+    runBlocking(Dispatchers.Main) {
+      instance.closeAll()
+    }
+  }
+
+  override fun forwardEvent(id: Double, event: ReadableMap) {
+    val instance = instances[id]?.instance ?: return
+    val baseEvent = BaseEvent()
+    baseEvent.eventType = event.getString("event_type") ?: return
+    baseEvent.eventId = event.getDouble("event_id").toLong()
+    baseEvent.platform = event.getString("platform")
+    baseEvent.osName = event.getString("os_name")
+    baseEvent.osVersion = event.getString("os_version")
+    baseEvent.eventProperties = event.getMap("event_properties")?.toHashMap()
+    baseEvent.groupProperties = event.getMap("group_properties")?.toHashMap()
+    baseEvent.groups = event.getMap("groups")?.toHashMap()
+    baseEvent.userProperties = event.getMap("user_properties")?.toHashMap()
+    Log.d("PluginEngagementReactNativeModule", "forwardEvent: $baseEvent")
+    runBlocking(Dispatchers.Main) {
+      instance.forwardEvent(baseEvent)
+    }
+  }
+
+  override fun addCallback(id: Double, key: String, func: Callback) {
+    val instance = instances[id]?.instance ?: return
+    runBlocking(Dispatchers.Main) {
+      instance.addCallback(key) { func.invoke() }
+    }
+  }
+
+  override fun handleURL(id: Double, url: String): Boolean {
+    val instance = instances[id]?.instance ?: return false
+
+    val uri = url.toUri()
+    val intent = Intent(Intent.ACTION_VIEW, uri)
+
+    return runBlocking(Dispatchers.Main) {
+      instance.handlePreviewLinkIntent(intent)
+    }
+  }
+
+
+  companion object {
+    const val NAME = "PluginEngagementReactNative"
+  }
+}

package/android/src/main/java/com/amplitude/pluginengagementreactnative/PluginEngagementReactNativePackage.kt

@@ -0,0 +1,33 @@
+package com.amplitude.pluginengagementreactnative
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class PluginEngagementReactNativePackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == PluginEngagementReactNativeModule.NAME) {
+      PluginEngagementReactNativeModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      val moduleInfos: MutableMap<String, ReactModuleInfo> = HashMap()
+      moduleInfos[PluginEngagementReactNativeModule.NAME] = ReactModuleInfo(
+        PluginEngagementReactNativeModule.NAME,
+        PluginEngagementReactNativeModule.NAME,
+        false,  // canOverrideExistingModule
+        false,  // needsEagerInit
+        false,  // isCxxModule
+        true // isTurboModule
+      )
+      moduleInfos
+    }
+  }
+}

package/ios/AmplitudeEngagementAdapter.swift

@@ -0,0 +1,121 @@
+//
+//  AmplitudeEngagementAdapter.swift
+//  PluginEngagementReactNative
+//
+//  Created by Jared Luxenberg on 5/19/25.
+//
+
+import Foundation
+import AmplitudeEngagementSwift
+
+
+extension Encodable {
+    /// Converting object to postable dictionary
+    func toDictionary(_ encoder: JSONEncoder = JSONEncoder()) throws -> [String: Any] {
+        let data = try encoder.encode(self)
+        let object = try JSONSerialization.jsonObject(with: data)
+        if let json = object as? [String: Any]  { return json }
+        
+        let context = DecodingError.Context(codingPath: [], debugDescription: "Deserialized object is not a dictionary")
+        throw DecodingError.typeMismatch(type(of: object), context)
+    }
+}
+
+// id -> (api_key, amplitude engagement instance)
+var instances: [Int: (String, AmplitudeEngagement)] = [:]
+var _id = 0
+
+/** `@objc` attribute exposes Swift methods to the Objective-C runtime**/
+@objc public class AmplitudeEngagementAdapter: NSObject {
+  @objc public func newInstance(_ apiKey: String) -> Int {
+    if let existingId = instances.first(where: { $0.value.0 == apiKey })?.key {
+        return existingId
+    }
+    
+    return DispatchQueue.main.sync {
+      _id += 1;
+      let id = _id + 1;
+      instances[id] = (apiKey, __ReactNative__AESDK(apiKey, AmplitudeInitOptions(logLevel: AmplitudeLogLevel.verbose)))
+      return id
+    }
+  }
+  
+  
+  @objc public func boot(_ instanceId: Int, _ user_id: String, device_id: String? = nil) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { return }
+      
+      return instance.boot(user_id, device_id: device_id)
+    }
+  }
+  
+  @objc public func setThemeMode(_ instanceId: Int, themeMode: String) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      guard let themeModeParsed = ThemeMode(rawValue: themeMode) else { return }
+      
+      return instance.setThemeMode(themeMode: themeModeParsed)
+    }
+  }
+  
+  @objc public func reset(_ instanceId: Int, key: String, stepIndex: Int = 0) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      
+      return instance.reset(key: key, stepIndex: stepIndex)
+    }
+  }
+  
+  @objc public func list(_ instanceId: Int) -> [[String: Any]] {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      
+      return instance.list().compactMap { x in try? x.toDictionary() }
+    }
+  }
+  
+  @objc public func handleUrl(_ instanceId: Int, _ url: String) -> Bool {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      guard let url = URL(string: url) else { return false; }
+      
+      return instance.handleUrl(url)
+    }
+  }
+  
+  @objc public func show(_ instanceId: Int, key: String, stepIndex: Int = 0) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      return instance.show(key: key, stepIndex: stepIndex)
+    }
+  }
+  
+  @objc public func screen(_ instanceId: Int, _ screenName: String) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      return instance.screen(screenName)
+    }
+  }
+  
+  @objc public func closeAll(_ instanceId: Int) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      return instance.closeAll()
+    }
+  }
+  
+  @objc public func forwardEvent(_ instanceId: Int, _ event: [String: Any]) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      return instance.forwardEvent(event)
+    }
+  }
+  
+  @objc(addCallback:::) public func addCallback(_ instanceId: Int, _ key: String, _ function: @escaping () -> Void) {
+    DispatchQueue.main.sync {
+      guard let (_, instance) = instances[instanceId] else { fatalError("🚨 Runtime exception: no instance found for id “\(instanceId)”") }
+      return instance.addCallback(key, function)
+    }
+  }
+  
+}

package/ios/PluginEngagementReactNative.h

@@ -0,0 +1,5 @@
+#import <PluginEngagementReactNativeSpec/PluginEngagementReactNativeSpec.h>
+
+@interface PluginEngagementReactNative : NSObject <NativePluginEngagementReactNativeSpec>
+
+@end

package/ios/PluginEngagementReactNative.mm

@@ -0,0 +1,87 @@
+#import "PluginEngagementReactNative.h"
+#import "PluginEngagementReactNative-Swift.h"
+
+//@interface RCT_EXTERN_MODULE(AmplitudeEngagementAdapter, NSObject)
+
+@implementation PluginEngagementReactNative {
+  AmplitudeEngagementAdapter *adapter;
+}
+//RCT_EXPORT_MODULE()
+
+
+- (id) init {
+  if (self = [super init]) {
+    adapter = [AmplitudeEngagementAdapter new];
+  }
+  return self;
+}
+
+// TODO: binding for AmplitudeEngagement here
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+    return std::make_shared<facebook::react::NativePluginEngagementReactNativeSpecJSI>(params);
+}
+
++ (NSString *)moduleName { 
+  return @"PluginEngagementReactNative";
+}
+
+- (void)boot:(double)id user_id:(nonnull NSString *)user_id device_id:(nonnull NSString *)device_id {
+  [adapter boot:id :user_id device_id:device_id];
+}
+
+- (nonnull NSArray<NSDictionary *> *)list:(double)id {
+  return [adapter list:id];
+}
+
+- (NSNumber *)newInstance:(nonnull NSString *)apiKey {
+  return @([adapter newInstance:apiKey]);
+}
+
+- (NSNumber*)handleURL:(double)id url:(NSString *)url {
+  BOOL success = [adapter handleUrl:id :url];
+  return @(success);
+}
+
+- (void)addCallback:(double)id key:(nonnull NSString *)key func:(nonnull RCTResponseSenderBlock)func {
+  RCTResponseSenderBlock jsCallback = func;
+  void (^callback)(void) = ^{
+          jsCallback(@[]);  // or pass whatever args you need
+      };
+  
+  [adapter addCallback:id :key :callback];
+}
+
+
+- (void)closeAll:(double)id { 
+  [adapter closeAll:id];
+}
+
+
+- (void)forwardEvent:(double)id event:(nonnull NSDictionary *)event { 
+  [adapter forwardEvent:id :event];
+}
+
+
+- (void)reset:(double)id key:(nonnull NSString *)key stepIndex:(double)stepIndex { 
+  [adapter reset:id key:key stepIndex:stepIndex];
+}
+
+
+- (void)screen:(double)id screenName:(nonnull NSString *)screenName { 
+  [adapter screen:id :screenName];
+}
+
+
+- (void)setThemeMode:(double)id themeMode:(nonnull NSString *)themeMode { 
+  [adapter setThemeMode:id themeMode:themeMode];
+}
+
+
+- (void)show:(double)id key:(nonnull NSString *)key stepIndex:(double)stepIndex { 
+  [adapter show:id key:key stepIndex:stepIndex];
+}
+
+@end