appsprint-react-native 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppSprint
+
+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/README.md

@@ -0,0 +1,173 @@
+# appsprint-react-native
+
+AppSprint mobile attribution SDK for React Native. It tracks installs, attribution, lifecycle events, custom events, and revenue events, with local event queueing for transient failures.
+
+## Installation
+
+```bash
+npm install appsprint-react-native
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+## Expo config plugin
+
+If you use Expo prebuild, add the plugin to your app config:
+
+```json
+{
+  "plugins": [
+    [
+      "appsprint-react-native",
+      {
+        "trackingDescription": "This identifier will be used to deliver personalized ads to you."
+      }
+    ]
+  ]
+}
+```
+
+Plugin options:
+
+| Option | Type | Description | Default |
+|---|---|---|---|
+| `trackingDescription` | `string` | ATT permission dialog text for `NSUserTrackingUsageDescription` | `"This identifier will be used to deliver personalized ads to you."` |
+| `advertisingAttributionEndpoint` | `string` | Sets `NSAdvertisingAttributionReportEndpoint` | — |
+
+## Quick start
+
+Initialize the SDK as early as possible in app startup:
+
+```tsx
+import { AppSprint } from "appsprint-react-native";
+
+await AppSprint.configure({
+  apiKey: "YOUR_API_KEY",
+});
+```
+
+### Configuration
+
+| Option | Type | Required | Default |
+|---|---|---|---|
+| `apiKey` | `string` | Yes | — |
+| `apiUrl` | `string` | No | `https://api.appsprint.app` |
+| `enableAppleAdsAttribution` | `boolean` | No | `true` |
+| `isDebug` | `boolean` | No | `false` |
+| `logLevel` | `0 \| 1 \| 2 \| 3` | No | `2` |
+| `customerUserId` | `string \| null` | No | `null` |
+
+Log levels:
+
+`0 = debug`, `1 = info`, `2 = warn`, `3 = error`
+
+## Sending events
+
+```tsx
+import { AppSprint } from "appsprint-react-native";
+
+await AppSprint.sendEvent("login");
+await AppSprint.sendEvent("sign_up");
+await AppSprint.sendEvent("purchase", null, {
+  revenue: 9.99,
+  currency: "USD",
+});
+
+await AppSprint.sendEvent("custom", "onboarding_step", {
+  screen: "welcome",
+  step: 1,
+});
+```
+
+Supported `eventType` values:
+
+`login` | `sign_up` | `register` | `purchase` | `subscribe` | `start_trial` | `add_to_cart` | `add_to_wishlist` | `initiate_checkout` | `view_content` | `view_item` | `search` | `share` | `tutorial_complete` | `level_start` | `level_complete` | `custom`
+
+Notes:
+
+- Use `eventType: "custom"` together with the optional `name` argument for custom event names.
+- Revenue fields are accepted through `params.revenue` and `params.currency`.
+- If an event cannot be delivered, it is queued locally and retried on the next initialization or explicit flush.
+
+## Public API
+
+### `AppSprint`
+
+```tsx
+import { AppSprint } from "appsprint-react-native";
+```
+
+Available methods:
+
+- `configure(config)` initializes the SDK and performs install tracking when needed.
+- `sendEvent(eventType, name?, params?)` sends or queues an event.
+- `sendTestEvent()` sends a diagnostic event and returns `{ success, message }`.
+- `flush()` retries queued events immediately.
+- `clearData()` clears cached SDK state and the local event queue.
+- `isSdkDisabled()` returns whether the SDK has been disabled because the API key was rejected.
+- `setCustomerUserId(userId)` updates the customer user id locally and remotely when possible.
+- `getAppSprintId()` returns the cached AppSprint install identifier, if available.
+- `getAttribution()` returns the last cached attribution result, if available.
+- `enableAppleAdsAttribution()` re-enables Apple Ads attribution in the current runtime config.
+- `isInitialized()` reports whether `configure()` completed.
+- `destroy()` removes SDK listeners.
+
+### `NativeAppSprint`
+
+```tsx
+import { NativeAppSprint } from "appsprint-react-native";
+```
+
+Available methods:
+
+- `getDeviceInfo()`
+- `getAdServicesToken()`
+- `requestTrackingAuthorization()`
+
+Example ATT request on iOS:
+
+```tsx
+import { NativeAppSprint } from "appsprint-react-native";
+
+const authorized = await NativeAppSprint.requestTrackingAuthorization();
+```
+
+## Attribution
+
+The SDK tracks install attribution once an install is registered. You can read the cached values at any time:
+
+```tsx
+const attribution = await AppSprint.getAttribution();
+const appsprintId = await AppSprint.getAppSprintId();
+```
+
+`AttributionResult.source` can be:
+
+`apple_ads` | `fingerprint` | `organic`
+
+## Offline and retry behavior
+
+- The SDK keeps up to `100` queued events in local storage.
+- Queued events are flushed after `configure()` and when the app moves to the background.
+- Failed flushes keep the unsent events queued for a later retry.
+- A rejected API key (`401` or `403`) disables the SDK and drops future events until cached data is cleared.
+
+## Local development
+
+Point the SDK at a non-production backend during development:
+
+```tsx
+await AppSprint.configure({
+  apiKey: "YOUR_API_KEY",
+  apiUrl: "http://localhost:3000",
+  isDebug: true,
+});
+```
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,39 @@
+buildscript {
+  ext.safeExtGet = {prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+  namespace "com.appsprint"
+  compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+    targetSdkVersion safeExtGet('targetSdkVersion', 35)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = '17'
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += 'src/main/kotlin'
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android:+"
+  implementation files('libs/appsprint-sdk.aar')
+  implementation "androidx.lifecycle:lifecycle-process:2.8.7"
+}

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/kotlin/com/appsprint/AppSprintBridgeModule.kt

@@ -0,0 +1,182 @@
+package com.appsprint
+
+import com.appsprint.sdk.AppSprint
+import com.appsprint.sdk.AppSprintConfig
+import com.appsprint.sdk.AppSprintEventType
+import com.facebook.react.bridge.*
+import kotlin.concurrent.thread
+
+class AppSprintBridgeModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = "AppSprintModule"
+
+    private fun sdk(): AppSprint {
+        val sdkClass = AppSprint::class.java
+
+        runCatching {
+            val shared = sdkClass.getMethod("shared", android.content.Context::class.java)
+            return shared.invoke(null, reactApplicationContext) as AppSprint
+        }
+
+        val companion = sdkClass.getField("Companion").get(null)
+        val shared = companion.javaClass.getMethod("shared", android.content.Context::class.java)
+        return shared.invoke(companion, reactApplicationContext) as AppSprint
+    }
+
+    private fun runAsync(code: String, promise: Promise, block: () -> Unit) {
+        thread(start = true) {
+            try {
+                block()
+            } catch (e: Exception) {
+                promise.reject(code, e.message, e)
+            }
+        }
+    }
+
+    // Core SDK
+
+    @ReactMethod
+    fun configure(config: ReadableMap, promise: Promise) {
+        val apiKey = config.getString("apiKey")?.trim().orEmpty()
+        if (apiKey.isEmpty()) {
+            promise.reject("CONFIGURE_ERROR", "AppSprint.configure requires a non-empty apiKey.")
+            return
+        }
+
+        runAsync("CONFIGURE_ERROR", promise) {
+            val sdkConfig = AppSprintConfig(
+                apiKey = apiKey,
+                apiUrl = if (config.hasKey("apiUrl")) config.getString("apiUrl") ?: "https://api.appsprint.app" else "https://api.appsprint.app",
+                enableAppleAdsAttribution = if (config.hasKey("enableAppleAdsAttribution")) config.getBoolean("enableAppleAdsAttribution") else true,
+                isDebug = if (config.hasKey("isDebug")) config.getBoolean("isDebug") else false,
+                logLevel = if (config.hasKey("logLevel")) config.getInt("logLevel") else if (config.hasKey("isDebug") && config.getBoolean("isDebug")) 0 else 2,
+                customerUserId = if (config.hasKey("customerUserId")) config.getString("customerUserId") else null,
+            )
+            sdk().configure(sdkConfig)
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun sendEvent(eventType: String, name: String?, revenue: Double?, currency: String?, parameters: ReadableMap?, promise: Promise) {
+        runAsync("SEND_EVENT_ERROR", promise) {
+            val type = AppSprintEventType.entries.find { it.wireValue == eventType } ?: AppSprintEventType.CUSTOM
+            val params = mutableMapOf<String, Any?>()
+            parameters?.toHashMap()?.forEach { (key, value) -> params[key] = value }
+            if (revenue != null && revenue != 0.0) params["revenue"] = revenue
+            if (currency != null) params["currency"] = currency
+            sdk().sendEvent(type, name, if (params.isNotEmpty()) params else null)
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun sendTestEvent(promise: Promise) {
+        runAsync("TEST_EVENT_ERROR", promise) {
+            val result = sdk().sendTestEvent()
+            val map = Arguments.createMap()
+            map.putBoolean("success", result.success)
+            map.putString("message", result.message)
+            promise.resolve(map)
+        }
+    }
+
+    @ReactMethod
+    fun flush(promise: Promise) {
+        runAsync("FLUSH_ERROR", promise) {
+            sdk().flush()
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun clearData(promise: Promise) {
+        runAsync("CLEAR_DATA_ERROR", promise) {
+            sdk().clearData()
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun setCustomerUserId(userId: String, promise: Promise) {
+        runAsync("SET_USER_ID_ERROR", promise) {
+            sdk().setCustomerUserId(userId)
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun enableAppleAdsAttribution(promise: Promise) {
+        sdk().enableAppleAdsAttribution()
+        promise.resolve(null)
+    }
+
+    @ReactMethod
+    fun getAppSprintId(promise: Promise) {
+        promise.resolve(sdk().getAppSprintId())
+    }
+
+    @ReactMethod
+    fun getAttribution(promise: Promise) {
+        val attr = sdk().getAttribution()
+        if (attr == null) {
+            promise.resolve(null)
+            return
+        }
+        val map = Arguments.createMap()
+        map.putString("source", attr.source)
+        map.putDouble("confidence", attr.confidence)
+        attr.campaignName?.let { map.putString("campaignName", it) }
+        attr.utmSource?.let { map.putString("utmSource", it) }
+        attr.utmMedium?.let { map.putString("utmMedium", it) }
+        attr.utmCampaign?.let { map.putString("utmCampaign", it) }
+        promise.resolve(map)
+    }
+
+    @ReactMethod
+    fun isInitialized(promise: Promise) {
+        promise.resolve(sdk().isInitialized())
+    }
+
+    @ReactMethod
+    fun isSdkDisabled(promise: Promise) {
+        promise.resolve(sdk().isSdkDisabled())
+    }
+
+    @ReactMethod
+    fun destroy(promise: Promise) {
+        runAsync("DESTROY_ERROR", promise) {
+            sdk().destroy()
+            promise.resolve(null)
+        }
+    }
+
+    // Utility
+
+    @ReactMethod
+    fun getDeviceInfo(promise: Promise) {
+        try {
+            val info = Arguments.createMap()
+            info.putString("deviceModel", android.os.Build.MODEL)
+            val metrics = reactApplicationContext.resources.displayMetrics
+            info.putInt("screenWidth", metrics.widthPixels)
+            info.putInt("screenHeight", metrics.heightPixels)
+            info.putString("locale", java.util.Locale.getDefault().toLanguageTag())
+            info.putString("timezone", java.util.TimeZone.getDefault().id)
+            info.putString("osVersion", android.os.Build.VERSION.RELEASE)
+            promise.resolve(info)
+        } catch (e: Exception) {
+            promise.reject("DEVICE_INFO_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun getAdServicesToken(promise: Promise) {
+        promise.resolve(null) // iOS only
+    }
+
+    @ReactMethod
+    fun requestTrackingAuthorization(promise: Promise) {
+        promise.resolve(false) // iOS only
+    }
+}

package/android/src/main/kotlin/com/appsprint/AppSprintPackage.kt

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

package/app.plugin.js

@@ -0,0 +1,3 @@
+"use strict";
+
+module.exports = require("./plugin/build");

package/appsprint-react-native.podspec

@@ -0,0 +1,23 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "appsprint-react-native"
+  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 => package["repository"], :tag => "#{s.version}" }
+
+  s.source_files = "ios/AppSprintBridge.{swift,m}"
+  s.swift_version = "5.0"
+
+  s.dependency "React-Core"
+
+  s.ios.vendored_frameworks = "ios/AppSprintSDK.xcframework"
+  s.frameworks = "AdServices", "AppTrackingTransparency", "AdSupport"
+end

package/ios/AppSprintBridge.m

@@ -0,0 +1,59 @@
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(AppSprintModule, NSObject)
+
+// Core SDK
+RCT_EXTERN_METHOD(configure:(NSDictionary *)config
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(sendEvent:(NSString *)eventType
+                  name:(NSString * _Nullable)name
+                  revenue:(NSNumber * _Nullable)revenue
+                  currency:(NSString * _Nullable)currency
+                  parameters:(NSDictionary * _Nullable)parameters
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(sendTestEvent:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(flush:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(clearData:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setCustomerUserId:(NSString *)userId
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(enableAppleAdsAttribution:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getAppSprintId:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getAttribution:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(isInitialized:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(isSdkDisabled:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(destroy:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+// Utility
+RCT_EXTERN_METHOD(getDeviceInfo:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getAdServicesToken:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(requestTrackingAuthorization:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end