linktrail-react-native 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinkTrail
+
+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/LinktrailReactNative.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "LinktrailReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/linktrail-io/react-native.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.swift_version = "5.9"
+
+  # The binary LinkTrail iOS SDK, published to the CocoaPods trunk — CocoaPods
+  # resolves it automatically, so the consuming app needs no extra Podfile line.
+  s.dependency "LinkTrailSDK", "~> 0.0.8"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+  }
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,92 @@
+# LinkTrail React Native SDK
+
+Mobile attribution and deferred deep linking for React Native. A New Architecture **TurboModule**
+that wraps the native [LinkTrail iOS](https://github.com/linktrail-io/ios-sdk) and
+[Android](https://github.com/linktrail-io/android-sdk) SDKs — the API type is `LinkTrail`.
+
+Requires React Native **0.76+** (New Architecture, the default), iOS **15.1+**, Android **minSdk 26+**.
+
+## Install
+
+```sh
+npm install linktrail-react-native
+```
+
+The native SDKs resolve automatically — `LinkTrailSDK` from the CocoaPods trunk, `io.linktrail:sdk`
+from Maven Central — so there's nothing else to add.
+
+- **iOS** — `cd ios && pod install`.
+- **Android** — nothing extra; just make sure your app's `minSdkVersion` is **26** or higher.
+- **Expo** — needs a [development build](https://docs.expo.dev/develop/development-builds/introduction/) (not Expo Go). Set `minSdkVersion` via [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/), then `npx expo prebuild`:
+
+  ```json
+  { "expo": { "plugins": [["expo-build-properties", { "android": { "minSdkVersion": 26 } }]] } }
+  ```
+
+## Quick start
+
+```ts
+import LinkTrail from 'linktrail-react-native';
+
+// At app launch. The API key is required.
+await LinkTrail.configure('lt_live_…');
+
+// One listener handles both first-launch (deferred) AND re-engagement links:
+LinkTrail.onLink((link, source) => {
+  router.navigate(link.path, link.customData); // e.g. "/products/aj1" + { voucher: "SUMMER25" }
+});
+
+// Observe failures:
+LinkTrail.onError((error) => console.warn(`[LinkTrail] ${error.code}: ${error.message}`));
+```
+
+The install is tracked automatically by `configure`, and incoming links (Universal Links / App
+Links / custom schemes) are forwarded via React Native's `Linking` API — no extra wiring.
+
+## More
+
+```ts
+// Custom post-install events:
+await LinkTrail.trackEvent('purchase', { value: 59.99, currency: 'USD' });
+
+// Cached results:
+const attribution = await LinkTrail.getLastAttribution();
+const lastLink = await LinkTrail.getLastDeepLink();
+
+// Consent-gated install (defer configure's auto-track, then call manually):
+await LinkTrail.configure('lt_live_…', { autoTrackInstall: false });
+await LinkTrail.trackInstall();
+
+// iOS ATT / SKAdNetwork (no-ops on Android):
+await LinkTrail.requestTrackingAuthorization();
+LinkTrail.registerForSKAdAttribution();
+LinkTrail.updateConversionValue(42, 'medium');
+```
+
+`configure` also takes `{ logEnabled, logLevel, requestTimeoutMillis, retryPolicy, linkDomains,
+autoTrackInstall, autoHandleLinks }`. Set `autoHandleLinks: false` to forward URLs yourself via
+`LinkTrail.handleDeepLink(url)`.
+
+## Deep-link setup
+
+Standard app deep-link config — the wrapper handles the rest. Declare your LinkTrail host as a
+Universal Link (iOS Associated Domains: `applinks:kick.linktrail.io`) and an App Links
+`intent-filter` (Android), plus any custom scheme. LinkTrail infra hosts the
+`apple-app-site-association` / `assetlinks.json` files for your link domains.
+
+## Example app
+
+[`example/`](example/) is **KickFlip**, a storefront that shows deferred deep linking end to end,
+consuming this package the same way your app would:
+
+```sh
+cd example && npm install && npm run ios   # or: npm run android
+```
+
+Set your `lt_live_…` key in [`src/attribution.ts`](example/src/attribution.ts), then tap the 🔗
+button to fire the four scenarios (home · category · product · product+voucher). The simulator
+works without a key.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,74 @@
+buildscript {
+  ext.getExtOrDefault = { name, fallback ->
+    rootProject.ext.has(name) ? rootProject.ext.get(name) : fallback
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.6.0"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion', '2.0.21')}"
+  }
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+if (!isNewArchitectureEnabled()) {
+  throw new GradleException(
+    "linktrail-react-native is a TurboModule and requires the React Native New Architecture. " +
+    "Enable it with newArchEnabled=true in gradle.properties (the default since React Native 0.76)."
+  )
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "io.linktrail.reactnative"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion", 35)
+
+  defaultConfig {
+    // The LinkTrail Android SDK requires API 26+.
+    minSdkVersion getExtOrDefault("minSdkVersion", 26)
+    targetSdkVersion getExtOrDefault("targetSdkVersion", 35)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += ["generated/java", "generated/jni"]
+    }
+  }
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "LinkTrailSpec"
+  codegenJavaPackageName = "io.linktrail.reactnative"
+}
+
+repositories {
+  google()
+  mavenCentral() // the LinkTrail SDK (io.linktrail:sdk) is published to Maven Central
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "io.linktrail:sdk:0.0.3"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0"
+}

package/android/src/main/AndroidManifest.xml

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

package/android/src/main/java/io/linktrail/reactnative/LinkTrailModule.kt

@@ -0,0 +1,243 @@
+package io.linktrail.reactnative
+
+import android.net.Uri
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+import com.facebook.react.bridge.WritableMap
+import io.linktrail.LinkTrail
+import io.linktrail.LinkTrailError
+import io.linktrail.LinkTrailLogLevel
+import io.linktrail.LinkTrailOptions
+import io.linktrail.LinkTrailRetryPolicy
+import io.linktrail.model.LinkTrailAttribution
+import io.linktrail.model.LinkTrailDeepLink
+import io.linktrail.model.LinkTrailLinkSource
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+class LinkTrailModule(reactContext: ReactApplicationContext) :
+  NativeLinkTrailSpec(reactContext) {
+
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+
+  override fun invalidate() {
+    scope.cancel()
+    super.invalidate()
+  }
+
+  // ── Configuration ──────────────────────────────────────────────────────────
+
+  override fun configure(apiKey: String, options: ReadableMap?, promise: Promise) {
+    try {
+      val sdk = LinkTrail.configure(reactApplicationContext, apiKey, parseOptions(options))
+      sdk.onAttribution { attribution -> emitOnAttribution(attributionToMap(attribution)) }
+      sdk.onLink { link, source ->
+        emitOnLink(
+          Arguments.createMap().apply {
+            putMap("link", deepLinkToMap(link))
+            putString("source", sourceName(source))
+          }
+        )
+      }
+      sdk.onError { error ->
+        emitOnError(
+          Arguments.createMap().apply {
+            putString("code", errorCode(error))
+            putString("message", error.message ?: "Unknown error")
+          }
+        )
+      }
+      promise.resolve(null)
+    } catch (t: Throwable) {
+      promise.reject(errorCode(t), t.message, t)
+    }
+  }
+
+  // ── Install / events ───────────────────────────────────────────────────────
+
+  override fun trackInstall(force: Boolean, promise: Promise) {
+    val sdk = requireSdk(promise) ?: return
+    scope.launch {
+      try {
+        promise.resolve(attributionToMap(sdk.trackInstallAsync(force)))
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message, t)
+      }
+    }
+  }
+
+  override fun trackEvent(name: String, value: Double?, currency: String?, promise: Promise) {
+    val sdk = requireSdk(promise) ?: return
+    scope.launch {
+      try {
+        val result = sdk.trackEventAsync(name, value, currency)
+        promise.resolve(
+          Arguments.createMap().apply {
+            result.id?.let { putInt("id", it) }
+            putBoolean("attributed", result.attributed)
+          }
+        )
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message, t)
+      }
+    }
+  }
+
+  // ── Deep linking ───────────────────────────────────────────────────────────
+
+  override fun handleDeepLink(url: String, promise: Promise) {
+    val sdk = requireSdk(promise) ?: return
+    scope.launch {
+      try {
+        promise.resolve(deepLinkToMap(sdk.handleDeepLinkAsync(Uri.parse(url))))
+      } catch (e: LinkTrailError.NotALinkTrailUrl) {
+        promise.resolve(null)
+      } catch (t: Throwable) {
+        promise.reject(errorCode(t), t.message, t)
+      }
+    }
+  }
+
+  override fun getLastAttribution(promise: Promise) {
+    promise.resolve(LinkTrail.shared?.lastAttribution?.let(::attributionToMap))
+  }
+
+  override fun getLastDeepLink(promise: Promise) {
+    promise.resolve(LinkTrail.shared?.lastDeepLink?.let(::deepLinkToMap))
+  }
+
+  // ── iOS-only APIs (no-ops on Android) ──────────────────────────────────────
+
+  override fun requestTrackingAuthorization(promise: Promise) {
+    promise.resolve(false)
+  }
+
+  override fun registerForSKAdAttribution() = Unit
+
+  override fun updateConversionValue(value: Double, coarseValue: String?) = Unit
+
+  // ── Testing ────────────────────────────────────────────────────────────────
+
+  override fun resetForTesting() {
+    LinkTrail.resetForTesting(reactApplicationContext)
+  }
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  private fun requireSdk(promise: Promise): LinkTrail? {
+    val sdk = LinkTrail.shared
+    if (sdk == null) {
+      promise.reject(
+        "not_configured",
+        "LinkTrail is not configured. Call LinkTrail.configure(apiKey) first."
+      )
+    }
+    return sdk
+  }
+
+  private fun parseOptions(map: ReadableMap?): LinkTrailOptions {
+    if (map == null) return LinkTrailOptions()
+    val defaults = LinkTrailOptions()
+
+    val retryMap = if (map.hasKey("retryPolicy")) map.getMap("retryPolicy") else null
+    val defaultRetry = LinkTrailRetryPolicy.DEFAULT
+    val retryPolicy = if (retryMap == null) defaultRetry else LinkTrailRetryPolicy(
+      maxAttempts = retryMap.intOrDefault("maxAttempts", defaultRetry.maxAttempts),
+      baseDelayMillis = retryMap.longOrDefault("baseDelayMillis", defaultRetry.baseDelayMillis),
+      maxDelayMillis = retryMap.longOrDefault("maxDelayMillis", defaultRetry.maxDelayMillis),
+    )
+
+    val linkDomains = mutableListOf<String>()
+    if (map.hasKey("linkDomains")) {
+      map.getArray("linkDomains")?.let { array ->
+        for (i in 0 until array.size()) array.getString(i)?.let(linkDomains::add)
+      }
+    }
+
+    return LinkTrailOptions(
+      logEnabled = map.booleanOrDefault("logEnabled", defaults.logEnabled),
+      logLevel = logLevel(map.stringOrNull("logLevel"), defaults.logLevel),
+      requestTimeoutMillis = map.longOrDefault("requestTimeoutMillis", defaults.requestTimeoutMillis),
+      retryPolicy = retryPolicy,
+      linkDomains = linkDomains,
+      autoTrackInstall = map.booleanOrDefault("autoTrackInstall", defaults.autoTrackInstall),
+    )
+  }
+
+  private fun logLevel(name: String?, fallback: LinkTrailLogLevel): LinkTrailLogLevel =
+    when (name) {
+      "debug" -> LinkTrailLogLevel.DEBUG
+      "info" -> LinkTrailLogLevel.INFO
+      "warning" -> LinkTrailLogLevel.WARNING
+      "error" -> LinkTrailLogLevel.ERROR
+      "none" -> LinkTrailLogLevel.NONE
+      else -> fallback
+    }
+
+  private fun sourceName(source: LinkTrailLinkSource): String = when (source) {
+    LinkTrailLinkSource.DEFERRED -> "deferred"
+    LinkTrailLinkSource.REENGAGEMENT -> "reengagement"
+  }
+
+  private fun attributionToMap(attribution: LinkTrailAttribution): WritableMap =
+    Arguments.createMap().apply {
+      attribution.id?.let { putInt("id", it) }
+      putBoolean("attributed", attribution.attributed)
+      attribution.deepLink?.let { putMap("deepLink", deepLinkToMap(it)) }
+    }
+
+  private fun deepLinkToMap(link: LinkTrailDeepLink): WritableMap =
+    Arguments.createMap().apply {
+      link.slug?.let { putString("slug", it) }
+      link.url?.let { putString("url", it) }
+      link.deepLinkPath?.let { putString("deepLinkPath", it) }
+      link.iosUrl?.let { putString("iosUrl", it) }
+      link.androidUrl?.let { putString("androidUrl", it) }
+      link.fallbackUrl?.let { putString("fallbackUrl", it) }
+      link.campaign?.let { putString("campaign", it) }
+      link.channel?.let { putString("channel", it) }
+      link.utm?.let { putMap("utm", stringMapToMap(it)) }
+      link.customData?.let { putMap("customData", stringMapToMap(it)) }
+      putString("path", link.path)
+      putBoolean("hasRoutableDestination", link.hasRoutableDestination)
+    }
+
+  private fun stringMapToMap(values: Map<String, String>): WritableMap =
+    Arguments.createMap().apply {
+      values.forEach { (key, value) -> putString(key, value) }
+    }
+
+  private fun errorCode(error: Throwable): String = when (error) {
+    is LinkTrailError.MissingApiKey -> "missing_api_key"
+    is LinkTrailError.InvalidApiKey -> "invalid_api_key"
+    is LinkTrailError.Transport -> "transport"
+    is LinkTrailError.Server -> "server"
+    is LinkTrailError.Decoding -> "decoding"
+    is LinkTrailError.EmptyResponse -> "empty_response"
+    is LinkTrailError.InvalidUrl -> "invalid_url"
+    is LinkTrailError.NotALinkTrailUrl -> "not_a_linktrail_url"
+    else -> "unknown"
+  }
+
+  private fun ReadableMap.booleanOrDefault(key: String, fallback: Boolean): Boolean =
+    if (hasKey(key) && getType(key) == ReadableType.Boolean) getBoolean(key) else fallback
+
+  private fun ReadableMap.intOrDefault(key: String, fallback: Int): Int =
+    if (hasKey(key) && getType(key) == ReadableType.Number) getInt(key) else fallback
+
+  private fun ReadableMap.longOrDefault(key: String, fallback: Long): Long =
+    if (hasKey(key) && getType(key) == ReadableType.Number) getDouble(key).toLong() else fallback
+
+  private fun ReadableMap.stringOrNull(key: String): String? =
+    if (hasKey(key) && getType(key) == ReadableType.String) getString(key) else null
+
+  companion object {
+    const val NAME = "LinkTrail"
+  }
+}

package/android/src/main/java/io/linktrail/reactnative/LinkTrailPackage.kt

@@ -0,0 +1,26 @@
+package io.linktrail.reactnative
+
+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
+
+class LinkTrailPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+    if (name == LinkTrailModule.NAME) LinkTrailModule(reactContext) else null
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider =
+    ReactModuleInfoProvider {
+      mapOf(
+        LinkTrailModule.NAME to ReactModuleInfo(
+          name = LinkTrailModule.NAME,
+          className = LinkTrailModule::class.java.name,
+          canOverrideExistingModule = false,
+          needsEagerInit = false,
+          isCxxModule = false,
+          isTurboModule = true,
+        )
+      )
+    }
+}

package/ios/LinkTrailModule.mm

@@ -0,0 +1,129 @@
+// The codegen spec header (and the -Swift.h bridge) are C++-heavy; importing
+// them only from this ObjC++ (.mm) translation unit — never from a public
+// header — keeps them out of the pod's Clang module umbrella, which otherwise
+// fails to build (libc++ headers unresolved under explicit modules).
+#if __has_include(<LinkTrailSpec/LinkTrailSpec.h>)
+#import <LinkTrailSpec/LinkTrailSpec.h>
+#else
+#import "LinkTrailSpec.h"
+#endif
+
+#if __has_include("LinktrailReactNative-Swift.h")
+#import "LinktrailReactNative-Swift.h"
+#else
+#import <LinktrailReactNative/LinktrailReactNative-Swift.h>
+#endif
+
+// TurboModule registered as "LinkTrail". Delegates to LinkTrailModuleImpl
+// (Swift), which talks to the binary LinkTrailSDK framework. Declared here
+// (not in a public header) on purpose — see the note above.
+@interface LinkTrailModule : NativeLinkTrailSpecBase <NativeLinkTrailSpec>
+@end
+
+@implementation LinkTrailModule {
+  LinkTrailModuleImpl *_impl;
+}
+
+RCT_EXPORT_MODULE(LinkTrail)
+
+- (instancetype)init
+{
+  if (self = [super init]) {
+    _impl = [LinkTrailModuleImpl new];
+    __weak LinkTrailModule *weakSelf = self;
+    _impl.onLink = ^(NSDictionary *payload) {
+      [weakSelf emitOnLink:payload];
+    };
+    _impl.onAttribution = ^(NSDictionary *payload) {
+      [weakSelf emitOnAttribution:payload];
+    };
+    _impl.onError = ^(NSDictionary *payload) {
+      [weakSelf emitOnError:payload];
+    };
+  }
+  return self;
+}
+
+- (void)configure:(NSString *)apiKey
+          options:(NSDictionary *)options
+          resolve:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl configure:apiKey
+           options:options
+           resolve:resolve
+            reject:^(NSString *code, NSString *message) { reject(code, message, nil); }];
+}
+
+- (void)trackInstall:(BOOL)force
+             resolve:(RCTPromiseResolveBlock)resolve
+              reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl trackInstall:force
+              resolve:resolve
+               reject:^(NSString *code, NSString *message) { reject(code, message, nil); }];
+}
+
+- (void)trackEvent:(NSString *)name
+             value:(NSNumber *)value
+          currency:(NSString *)currency
+           resolve:(RCTPromiseResolveBlock)resolve
+            reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl trackEvent:name
+              value:value
+           currency:currency
+            resolve:resolve
+             reject:^(NSString *code, NSString *message) { reject(code, message, nil); }];
+}
+
+- (void)handleDeepLink:(NSString *)url
+               resolve:(RCTPromiseResolveBlock)resolve
+                reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl handleDeepLink:url
+                resolve:resolve
+                 reject:^(NSString *code, NSString *message) { reject(code, message, nil); }];
+}
+
+- (void)getLastAttribution:(RCTPromiseResolveBlock)resolve
+                    reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl getLastAttribution:resolve];
+}
+
+- (void)getLastDeepLink:(RCTPromiseResolveBlock)resolve
+                 reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl getLastDeepLink:resolve];
+}
+
+- (void)requestTrackingAuthorization:(RCTPromiseResolveBlock)resolve
+                              reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl requestTrackingAuthorization:resolve
+                               reject:^(NSString *code, NSString *message) { reject(code, message, nil); }];
+}
+
+- (void)registerForSKAdAttribution
+{
+  [_impl registerForSKAdAttribution];
+}
+
+- (void)updateConversionValue:(double)value coarseValue:(NSString *)coarseValue
+{
+  [_impl updateConversionValue:(NSInteger)llround(value) coarseValue:coarseValue];
+}
+
+- (void)resetForTesting
+{
+  [_impl resetForTesting];
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeLinkTrailSpecJSI>(params);
+}
+
+@end