@tryheliumai/paywall-sdk-react-native 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Anish Doshi
+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/PaywallSdkReactNative.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+folly_compiler_flags = '-DFOLLY_NO_CONFIG -DFOLLY_MOBILE=1 -DFOLLY_USE_LIBCPP=1 -Wno-comma -Wno-shorten-64-to-32'
+
+Pod::Spec.new do |s|
+  s.name         = "PaywallSdkReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "14.0" }
+  s.source       = { :git => "https://github.com/cloudcaptainai/helium-react-native-sdk.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+
+  s.dependency 'Helium', '~> 1.5.6'
+
+  # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
+  # See https://github.com/facebook/react-native/blob/febf6b7f33fdb4904669f99d795eba4c0f95d7bf/scripts/cocoapods/new_architecture.rb#L79.
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+end

package/README.md

@@ -0,0 +1,224 @@
+---
+title: 'SDK Quickstart (React Native)'
+description: 'Integrate Helium into your React Native App'
+icon: 'code'
+---
+
+## **Background**
+
+Get set up with the Helium SDK for iOS in 5 minutes. Reach out over your Helium slack channel, or email founders@tryhelium.com for any questions.
+## **Installation**
+
+Install **@tryheliumai/paywall-sdk-react-native** using your preferred package manager:
+
+```bash
+npm install @tryheliumai/paywall-sdk-react-native
+# or
+yarn add @tryheliumai/paywall-sdk-react-native
+```
+
+The package should be autolinked. If not, you can manually link it by running:
+
+```bash
+cd ios
+npx pod-install
+cd ..
+npx react-native link @tryheliumai/paywall-sdk-react-native
+```
+
+## **Configuration**
+
+### Provider Setup
+
+Wrap your app's root component with `HeliumProvider`. This provider makes Helium's functionality available throughout your app:
+
+```tsx
+import { HeliumProvider } from '@tryheliumai/paywall-sdk-react-native';
+
+function App() {
+  return (
+    <HeliumProvider
+      apiKey="<your-helium-api-key>"
+      fallbackComponent={YourFallbackComponent}
+    >
+      <YourAppComponent />
+    </HeliumProvider>
+  );
+}
+```
+
+### Initialization
+
+Initialize Helium by calling `Helium.initialize()` early in your app's lifecycle, typically in your root component:
+
+```tsx
+import { initializeHelium } from '@tryheliumai/paywall-sdk-react-native';
+
+function App() {
+  useEffect(() => {
+    initializeHelium({
+      // Helium provided api key
+      apiKey: '<your-helium-api-key>',
+
+      // Purchase handlers: described in next section
+      delegate: yourDelegate
+
+      // Custom user id - e.g. your amplitude analytics user id.
+      customUserId: '<your-custom-user-id>',
+
+      // Helium provided custom API endpoint
+      customApiEndpoint: '<your-custom-api-endpoint>',
+
+      // Custom user traits
+      customUserTraits: {
+        "example_trait": "example_value",
+      },
+    });
+  }, []);
+}
+```
+
+### Payment Delegate Implementation
+
+Create a payment delegate object that implements the `HeliumPaymentDelegate` interface. This delegate handles purchase logic for your paywalls:
+
+```typescript
+export type HeliumTransactionStatus =
+  | { type: 'purchased' }
+  | { type: 'cancelled' }
+  | { type: 'abandoned' }
+  | { type: 'failed', error: Error }
+  | { type: 'restored' }
+  | { type: 'pending' };
+
+export interface HeliumPaymentDelegate {
+  // [REQUIRED] Trigger the purchase of a product
+  makePurchase: (productId: string) => Promise<HeliumTransactionStatus>;
+
+  // [OPTIONAL] Restore existing subscriptions
+  restorePurchases?: () => Promise<boolean>;
+
+  // [OPTIONAL] Handle Helium paywall events
+  onPaywallEvent?: (event: HeliumPaywallEvent) => void;
+
+  // [OPTIONAL] Provides custom variables for dynamic paywall content
+  getCustomVariables?: () => Record<string, any>;
+}
+```
+
+### Example Delegate
+
+Here's an example delegate using React Native's in-app purchases:
+
+```typescript
+import * as RNIap from 'react-native-iap';
+
+const paymentDelegate: HeliumPaymentDelegate = {
+  async makePurchase(productId: string): Promise<HeliumTransactionStatus> {
+    try {
+      const products = await RNIap.getProducts([productId]);
+      const purchase = await RNIap.requestPurchase(productId);
+      
+      if (purchase) {
+        return { type: 'purchased' };
+      }
+      return { type: 'cancelled' };
+    } catch (error) {
+      return { type: 'failed', error };
+    }
+  },
+
+  async restorePurchases(): Promise<boolean> {
+    try {
+      await RNIap.initConnection();
+      const restored = await RNIap.restorePurchases();
+      return restored.length > 0;
+    } catch (error) {
+      console.error('Restore failed:', error);
+      return false;
+    }
+  },
+
+  getCustomVariables() {
+    return {
+      userSubscriptionStatus: checkUserSubscriptionStatus(),
+      userIntent: checkUserIntent(),
+    };
+  }
+};
+```
+
+### Checking Download Status
+
+Monitor the status of paywall configuration downloads using the `useHeliumStatus` hook:
+
+```typescript
+import { useHeliumStatus } from '@tryhelium/paywall-sdk';
+
+function YourComponent() {
+  const status = useHeliumStatus();
+
+  useEffect(() => {
+    switch (status.type) {
+      case 'not_downloaded':
+        console.log('Download not started or in progress');
+        break;
+      case 'success':
+        console.log('Download successful with config ID:', status.configId);
+        break;
+      case 'error':
+        console.log('Download failed');
+        break;
+    }
+  }, [status]);
+
+  return <YourContent />;
+}
+```
+
+## **Presenting Paywalls**
+
+### Using the Hook
+
+Use the `presentPaywall` method in any component under the `HeliumProvider` to present a paywall:
+
+```typescript
+import { presentPaywall } from '@tryhelium/paywall-sdk';
+
+function YourComponent() {
+  const handlePremiumPress = useCallback(async () => {
+    await presentPaywall({ trigger: 'premium_feature_press' });
+  }, [presentPaywall]);
+
+  return (
+    <Button title="Try Premium" onPress={handlePremiumPress} />
+  );
+}
+```
+
+### Custom Navigation
+
+Handle custom navigation or dismissal by implementing the `onPaywallEvent` method in your payment delegate:
+
+```typescript
+const paymentDelegate: HeliumPaymentDelegate = {
+  // ... other methods
+
+  onPaywallEvent(event: HeliumPaywallEvent) {
+    switch (event.type) {
+      case 'cta_pressed':
+        const { ctaName, trigger, templateName } = event;
+        if (ctaName === 'dismiss') {
+          // Handle custom dismissal
+        }
+        break;
+      // ... handle other events
+    }
+  }
+};
+```
+
+## **Paywall Events**
+
+Helium emits various events during the lifecycle of a paywall. You can handle these events in your payment delegate. See the iOS docs
+for more details.

package/android/build.gradle

@@ -0,0 +1,88 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['PaywallSdkReactNative_' + 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')}"
+  }
+}
+
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["PaywallSdkReactNative_" + name]).toInteger()
+}
+
+def supportsNamespace() {
+  def parsed = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')
+  def major = parsed[0].toInteger()
+  def minor = parsed[1].toInteger()
+
+  // Namespace support was added in 7.3.0
+  return (major == 7 && minor >= 3) || major >= 8
+}
+
+android {
+  if (supportsNamespace()) {
+    namespace "com.paywallsdkreactnative"
+
+    sourceSets {
+      main {
+        manifest.srcFile "src/main/AndroidManifestNew.xml"
+      }
+    }
+  }
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+}
+

package/android/gradle.properties

@@ -0,0 +1,5 @@
+PaywallSdkReactNative_kotlinVersion=2.0.21
+PaywallSdkReactNative_minSdkVersion=24
+PaywallSdkReactNative_targetSdkVersion=34
+PaywallSdkReactNative_compileSdkVersion=35
+PaywallSdkReactNative_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/AndroidManifestNew.xml

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

package/android/src/main/java/com/paywallsdkreactnative/PaywallSdkReactNativeModule.kt

@@ -0,0 +1,25 @@
+package com.paywallsdkreactnative
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.Promise
+
+class PaywallSdkReactNativeModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String {
+    return NAME
+  }
+
+  // Example method
+  // See https://reactnative.dev/docs/native-modules-android
+  @ReactMethod
+  fun multiply(a: Double, b: Double, promise: Promise) {
+    promise.resolve(a * b)
+  }
+
+  companion object {
+    const val NAME = "PaywallSdkReactNative"
+  }
+}

package/android/src/main/java/com/paywallsdkreactnative/PaywallSdkReactNativePackage.kt

@@ -0,0 +1,17 @@
+package com.paywallsdkreactnative
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+
+class PaywallSdkReactNativePackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(PaywallSdkReactNativeModule(reactContext))
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return emptyList()
+  }
+}

package/ios/HeliumSwiftInterface.swift

@@ -0,0 +1,269 @@
+//
+//  HeliumSwiftInterface.swift
+//  HeliumBridgeNative
+//
+//  Created by Anish Doshi on 2/11/25.
+//
+
+import Foundation
+import Helium
+import SwiftUI
+import UIKit
+import React
+import AnyCodable
+import Combine
+
+struct UIViewWrapper: UIViewRepresentable, View {
+    let view: UIView
+    
+    func makeUIView(context: Context) -> UIView {
+        return view
+    }
+    
+    func updateUIView(_ uiView: UIView, context: Context) {
+    }
+}
+
+class PurchaseState: ObservableObject {
+    struct PurchaseResponse {
+        let transactionId: String
+        let status: String
+    }
+    
+    @Published var pendingResponses: [String: (PurchaseResponse) -> Void] = [:]
+}
+
+
+class BridgingPaywallDelegate: HeliumPaywallDelegate {
+    private let purchaseState = PurchaseState()
+    private weak var bridge: HeliumBridge?
+    
+    init(
+          bridge: HeliumBridge
+      ) {
+          self.bridge = bridge
+      }
+  
+    public func makePurchase(productId: String) async -> HeliumPaywallTransactionStatus {
+          return await withCheckedContinuation { continuation in
+              let transactionId = UUID().uuidString
+              
+              // Store continuation callback
+              purchaseState.pendingResponses[transactionId] = { response in
+                  let status: HeliumPaywallTransactionStatus = switch response.status {
+                      case "purchased": .purchased
+                      case "cancelled": .cancelled
+                      case "restored": .restored
+                      case "pending": .pending
+                      default: .failed(NSError())
+                  }
+                  continuation.resume(returning: status)
+              }
+              
+              // Send event to initiate purchase
+              bridge?.sendEvent(
+                  withName: "helium_make_purchase",
+                  body: [
+                      "productId": productId,
+                      "transactionId": transactionId,
+                      "status": "starting"
+                  ]
+              )
+          }
+      }
+      
+    func handlePurchaseResponse(_ response: NSDictionary) {
+        guard let transactionId = response["transactionId"] as? String,
+              let status = response["status"] as? String,
+              let callback = purchaseState.pendingResponses[transactionId] else {
+            return
+        }
+        
+        // Remove callback before executing to prevent multiple calls
+        purchaseState.pendingResponses.removeValue(forKey: transactionId)
+        
+        callback(PurchaseState.PurchaseResponse(
+            transactionId: transactionId,
+            status: status
+        ))
+    }
+    
+  
+  func restorePurchases() async -> Bool {
+      return await withCheckedContinuation { continuation in
+          let transactionId = UUID().uuidString
+          
+          // Store continuation callback
+          purchaseState.pendingResponses[transactionId] = { response in
+              // Convert string status to bool
+              let success = response.status == "restored"
+              continuation.resume(returning: success)
+          }
+          
+          // Send event to initiate restore
+          bridge?.sendEvent(
+              withName: "helium_restore_purchases",
+              body: [
+                  "transactionId": transactionId,
+                  "status": "starting"
+              ]
+          )
+      }
+  }
+
+  func handleRestoreResponse(_ response: NSDictionary) {
+      guard let transactionId = response["transactionId"] as? String,
+            let status = response["status"] as? String,
+            let callback = purchaseState.pendingResponses[transactionId] else {
+          return
+      }
+      
+      // Remove callback before executing to prevent multiple calls
+      purchaseState.pendingResponses.removeValue(forKey: transactionId)
+      
+      callback(PurchaseState.PurchaseResponse(
+          transactionId: transactionId,
+          status: status
+      ))
+  }
+    
+    func onHeliumPaywallEvent(event: HeliumPaywallEvent) {
+          let eventDict = event.toDictionary()
+          bridge?.sendEvent(
+              withName: "helium_paywall_event",
+              body: eventDict
+          )
+      }
+    
+    func getCustomVariableValues() -> [String: Any?] {
+        return [:];
+    }
+}
+
+@objc(HeliumBridge)
+class HeliumBridge: RCTEventEmitter {
+   private var bridgingDelegate: BridgingPaywallDelegate?
+   var customVariables: [String: Any?] = [:]
+   private var cancellables = Set<AnyCancellable>()
+
+  @objc(init)
+  public override init() {
+      super.init()
+  }
+  
+   public override func supportedEvents() -> [String] {
+       return [
+           "helium_paywall_event",
+           "helium_make_purchase",
+           "helium_restore_purchases",
+           "helium_download_state_changed"
+       ]
+   }
+   
+   @objc
+   override static func requiresMainQueueSetup() -> Bool {
+       return true
+   }
+   
+  @objc
+  public func initialize(
+      _ config: NSDictionary,
+      customVariableValues:NSDictionary
+  ) {
+      guard let apiKey = config["apiKey"] as? String,
+            let viewTag = config["fallbackPaywall"] as? NSNumber else {
+          return
+      }
+      
+      let triggers = config["triggers"] as? [String]
+      let customUserId = config["customUserId"] as? String
+      let customAPIEndpoint = config["customAPIEndpoint"] as? String
+      let customUserTraits = config["customUserTraits"] as? [String: AnyCodable];
+      
+      self.bridgingDelegate = BridgingPaywallDelegate(
+          bridge: self
+      )
+    
+      HeliumFetchedConfigManager.shared.$downloadStatus
+                .sink { newValue in
+                    var newValueString = "";
+                    switch (newValue) {
+                      case .downloadFailure:
+                      newValueString = "downloadFailure";
+                      break;
+                      case .downloadSuccess:
+                      newValueString = "downloadSuccess";
+                      break;
+                      case .inProgress:
+                      newValueString = "inProgress";
+                      break;
+                      case .notDownloadedYet:
+                      newValueString = "notDownloadedYet";
+                      break;
+                    }
+                    self.sendEvent(
+                        withName: "helium_download_state_changed",
+                        body: [
+                          "status": newValueString
+                        ]
+                    )
+                }
+                .store(in: &cancellables)
+    
+      // Always do view lookup on main queue
+      DispatchQueue.main.async {
+          guard let bridge = self.bridge,
+                let fallbackPaywall = bridge.uiManager.view(forReactTag: viewTag) else {
+              return
+          }
+          
+          let wrappedView = UIViewWrapper(view: fallbackPaywall)
+          
+          // Move initialization off main queue
+          DispatchQueue.global().async {
+              Helium.shared.initialize(
+                  apiKey: apiKey,
+                  heliumPaywallDelegate: self.bridgingDelegate!,
+                  fallbackPaywall: wrappedView,
+                  triggers: triggers,
+                  customUserId: customUserId,
+                  customAPIEndpoint: customAPIEndpoint,
+                  customUserTraits: HeliumUserTraits(customUserTraits ?? [:])
+              )
+          }
+      }
+  }
+  
+  @objc
+  public func handlePurchaseResponse(_ response: NSDictionary) {
+      bridgingDelegate?.handlePurchaseResponse(response)
+  }
+  
+  @objc
+  public func handleRestoreResponse(_ response: NSDictionary) {
+      bridgingDelegate?.handleRestoreResponse(response)
+  }
+   
+   @objc
+   public func upsellViewForTrigger(
+       _ trigger: String,
+       resolver: @escaping RCTPromiseResolveBlock,
+       rejecter: @escaping RCTPromiseRejectBlock
+   ) {
+       let swiftUIView = Helium.shared.upsellViewForTrigger(trigger: trigger)
+       let hostingController = UIHostingController(rootView: swiftUIView)
+       resolver(hostingController.view)
+   }
+  
+  @objc
+  public func presentUpsell(
+      _ trigger: String
+  ) {
+    Helium.shared.presentUpsell(trigger: trigger);
+  }
+  
+  @objc
+  public func hideUpsell() {
+    _ = Helium.shared.hideUpsell();
+  }
+}