vialink-react-native-sdk 2.1.10 → 3.1.1

package/android/src/main/java/com/vialink/reactnative/ViaLinkModule.kt

@@ -4,6 +4,7 @@ import com.facebook.react.bridge.*
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.vialink.sdk.ViaLinkSDK
 import com.vialink.sdk.model.DeepLinkData
+import com.vialink.sdk.model.DeferredError
 import com.vialink.sdk.model.PaymentInitiatedArgs
 import kotlinx.coroutines.*
 
@@ -12,11 +13,15 @@ class ViaLinkModule(reactContext: ReactApplicationContext) :
     ActivityEventListener {
 
     companion object {
-        const val WRAPPER_VERSION = "2.1.0"
+        const val WRAPPER_VERSION = "3.1.0"
     }
 
     private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+    /// onDeepLink가 listenerCount==0 시점에 호출된 경우의 캐시.
+    /// 3.1.0부터 일반 진입에서도 콜백이 호출되므로, link 진입(map != null) / 일반 진입(map == null)을
+    /// 구분하기 위해 별도 플래그(`hasPendingDeepLink`)를 둔다.
     private var pendingDeepLink: WritableMap? = null
+    private var hasPendingDeepLink: Boolean = false
     private var pendingDeferred: WritableMap? = null
     private var listenerCount = 0
 
@@ -39,15 +44,24 @@ class ViaLinkModule(reactContext: ReactApplicationContext) :
         ViaLinkSDK.setWrapper("react-native/$WRAPPER_VERSION")
         ViaLinkSDK.init(context, apiKey)
 
+        // 딥링크 콜백 — SDK 3.1.0+: data == null이면 일반 진입을 의미한다.
+        // JS 측 emitter는 null payload를 그대로 전달받아 `data: null`로 콜백을 호출한다.
         ViaLinkSDK.onDeepLink { data ->
-            val map = data.toWritableMap()
+            val map: WritableMap? = data?.toWritableMap()
             if (listenerCount > 0) sendEvent("onDeepLink", map)
-            else pendingDeepLink = map
+            else {
+                pendingDeepLink = map
+                hasPendingDeepLink = true
+            }
         }
-        ViaLinkSDK.onDeferredDeepLink { data ->
-            val map = data.toWritableMap()
-            if (listenerCount > 0) sendEvent("onDeferredDeepLink", map)
-            else pendingDeferred = map
+        // 디퍼드 콜백: SDK 3.0+ 시그니처 (data, error) — 항상 1회 호출
+        // JS 측 emit 페이로드는 `{data, error}` 객체로 전달한다.
+        ViaLinkSDK.onDeferredDeepLink { data, error ->
+            val payload = Arguments.createMap()
+            data?.let { payload.putMap("data", it.toWritableMap()) }
+            error?.let { payload.putMap("error", it.toWritableMap()) }
+            if (listenerCount > 0) sendEvent("onDeferredDeepLink", payload)
+            else pendingDeferred = payload
         }
 
         currentActivity?.intent?.let { ViaLinkSDK.handleIntent(it) }
@@ -161,10 +175,11 @@ class ViaLinkModule(reactContext: ReactApplicationContext) :
     @ReactMethod
     fun addListener(eventName: String) {
         listenerCount++
-        // pending 이벤트 flush
-        if (eventName == "onDeepLink") {
-            pendingDeepLink?.let { sendEvent("onDeepLink", it) }
+        // pending 이벤트 flush — 3.1.0부터 일반 진입(null payload)도 flush해야 한다.
+        if (eventName == "onDeepLink" && hasPendingDeepLink) {
+            sendEvent("onDeepLink", pendingDeepLink)   // null payload도 그대로 전달
             pendingDeepLink = null
+            hasPendingDeepLink = false
         }
         if (eventName == "onDeferredDeepLink") {
             pendingDeferred?.let { sendEvent("onDeferredDeepLink", it) }
@@ -201,3 +216,13 @@ private fun DeepLinkData.toWritableMap(): WritableMap {
     linkId?.let { map.putInt("linkId", it) }
     return map
 }
+
+// DeferredError → WritableMap (JS DeferredError 인터페이스와 키가 일치해야 함)
+private fun DeferredError.toWritableMap(): WritableMap {
+    val map = Arguments.createMap()
+    map.putString("code", code)
+    map.putString("message", message)
+    httpStatus?.let { map.putInt("httpStatus", it) }
+    map.putBoolean("retryable", retryable)
+    return map
+}

package/dist/ViaLinkSDK.d.ts

@@ -4,6 +4,26 @@ export interface DeepLinkData {
     shortCode?: string;
     linkId?: number;
 }
+/**
+ * 디퍼드 매칭 실패 정보
+ *
+ * `onDeferredDeepLink((data, error) => ...)` 콜백의 두 번째 인자로 전달된다.
+ * `data == null && error == null`이면 매칭 결과가 "없음"(organic install)이다.
+ *
+ * - `code`:
+ *   - `'timeout'`: 5초 데드라인 만료
+ *   - `'network'`: DNS 실패, 연결 거부 등 (3회 재시도 모두 실패)
+ *   - `'server_error'`: HTTP 5xx (3회 재시도 모두 실패)
+ *   - `'invalid_response'`: 응답 JSON 파싱 실패
+ *   - `'unknown'`: 그 외 모든 예외
+ * - `retryable`이 true면 SDK가 다음 앱 실행에서 자동으로 다시 시도한다.
+ */
+export interface DeferredError {
+    code: 'timeout' | 'network' | 'server_error' | 'invalid_response' | 'unknown';
+    message: string;
+    httpStatus?: number;
+    retryable: boolean;
+}
 /**
  * 결제 시도 이벤트 입력 인자.
  *
@@ -72,15 +92,47 @@ export declare class ViaLinkSDK {
      */
     configure(apiKey: string): Promise<void>;
     /**
-     * 딥링크 수신 콜백 등록
-     * App Links / Universal Links로 앱이 열렸을 때 호출됩니다.
+     * 딥링크 수신 콜백 등록 (3.1.0+).
+     *
+     * 네이티브 SDK가 진입 알림(`handleIntent`/`handleUniversalLink`/`notifyAppLaunch`)을 처리할 때 항상 1회 호출됩니다.
+     * - App Links / Universal Links 진입이면 매칭된 [DeepLinkData]가 전달됩니다.
+     * - 일반 진입(아이콘 탭 등)이면 `null`이 전달됩니다.
+     *
+     * ```typescript
+     * ViaLinkSDK.shared.onDeepLink((data) => {
+     *   if (!data) {
+     *     // 일반 진입 — 기본 라우트 유지
+     *     return;
+     *   }
+     *   navigation.navigate(data.path, data.params);
+     * });
+     * ```
      */
-    onDeepLink(callback: (data: DeepLinkData) => void): void;
+    onDeepLink(callback: (data: DeepLinkData | null) => void): void;
     /**
      * 디퍼드 딥링크 콜백 등록
-     * 앱 첫 설치 후 실행 시 fingerprint 매칭으로 딥링크 데이터를 전달합니다.
+     *
+     * 앱 첫 실행 시 매칭 결과가 결정되는 즉시 항상 1회 호출됩니다.
+     * 5초 안에 결과가 결정되지 않으면 `error.code === 'timeout'`으로 호출됩니다.
+     *
+     * ```typescript
+     * ViaLinkSDK.shared.onDeferredDeepLink((data, error) => {
+     *   if (error) {
+     *     // 매칭 실패 (timeout/network/server_error 등) — 일반 진입
+     *     return;
+     *   }
+     *   if (!data) {
+     *     // organic install — 일반 진입
+     *     return;
+     *   }
+     *   navigation.navigate(data.path, data.params);
+     * });
+     * ```
+     *
+     * 콜백은 멱등성을 보장합니다 (총 1회 호출).
+     * `error.retryable`이 true면 다음 앱 실행에서 자동 재시도되며, 그 경우 사용자가 앱을 사용 중일 때 콜백이 도착할 수 있습니다.
      */
-    onDeferredDeepLink(callback: (data: DeepLinkData) => void): void;
+    onDeferredDeepLink(callback: (data: DeepLinkData | null, error: DeferredError | null) => void): void;
     /**
      * 커스텀 이벤트 추적
      *

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { ViaLinkSDK } from './ViaLinkSDK';
-export type { DeepLinkData, PaymentInitiatedArgs, PaymentInitiatedResult, } from './ViaLinkSDK';
+export type { DeepLinkData, DeferredError, PaymentInitiatedArgs, PaymentInitiatedResult, } from './ViaLinkSDK';

package/dist/index.js

@@ -1 +1 @@
-'use strict';var reactNative=require('react-native');var {ViaLinkSDK:n}=reactNative.NativeModules,i=new reactNative.NativeEventEmitter(n),m=/^[A-Za-z0-9_-]{1,100}$/,r=class a{constructor(){this.payment={initiated:async e=>{if(!e||typeof e!="object")throw new Error("args\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");if(typeof e.orderId!="string"||!m.test(e.orderId))throw new Error("order_id \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 (1~100\uC790, \uC601\uBB38/\uC22B\uC790/\uD558\uC774\uD508/\uC5B8\uB354\uC2A4\uCF54\uC5B4).");if(typeof e.amount!="number"||!Number.isFinite(e.amount)||e.amount<=0)throw new Error("amount\uB294 0\uBCF4\uB2E4 \uD070 \uC22B\uC790\uC5EC\uC57C \uD569\uB2C8\uB2E4.");if(typeof e.currency!="string"||e.currency.trim().length===0)throw new Error("currency\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");let t=await n.paymentInitiated({orderId:e.orderId,amount:e.amount,currency:e.currency.trim().toUpperCase(),linkId:e.linkId??null,paymentMethod:e.paymentMethod??null,metadata:e.metadata??null});return {success:!!t?.success,paymentEventId:String(t?.paymentEventId??"")}}};}static get shared(){return this._instance||(this._instance=new a),this._instance}async configure(e){await n.configure(e);}onDeepLink(e){this.deepLinkSub?.remove(),this.deepLinkSub=i.addListener("onDeepLink",e);}onDeferredDeepLink(e){this.deferredSub?.remove(),this.deferredSub=i.addListener("onDeferredDeepLink",e);}track(e,t){n.track(e,t??null);}async createLink(e,t,o,s="static",d){return n.createLink(e,t??null,o??null,s,d??null)}destroy(){this.deepLinkSub?.remove(),this.deferredSub?.remove();}};exports.ViaLinkSDK=r;
+'use strict';var reactNative=require('react-native');var {ViaLinkSDK:r}=reactNative.NativeModules,i=new reactNative.NativeEventEmitter(r),l=/^[A-Za-z0-9_-]{1,100}$/,n=class a{constructor(){this.payment={initiated:async e=>{if(!e||typeof e!="object")throw new Error("args\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");if(typeof e.orderId!="string"||!l.test(e.orderId))throw new Error("order_id \uD615\uC2DD\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 (1~100\uC790, \uC601\uBB38/\uC22B\uC790/\uD558\uC774\uD508/\uC5B8\uB354\uC2A4\uCF54\uC5B4).");if(typeof e.amount!="number"||!Number.isFinite(e.amount)||e.amount<=0)throw new Error("amount\uB294 0\uBCF4\uB2E4 \uD070 \uC22B\uC790\uC5EC\uC57C \uD569\uB2C8\uB2E4.");if(typeof e.currency!="string"||e.currency.trim().length===0)throw new Error("currency\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");let t=await r.paymentInitiated({orderId:e.orderId,amount:e.amount,currency:e.currency.trim().toUpperCase(),linkId:e.linkId??null,paymentMethod:e.paymentMethod??null,metadata:e.metadata??null});return {success:!!t?.success,paymentEventId:String(t?.paymentEventId??"")}}};}static get shared(){return this._instance||(this._instance=new a),this._instance}async configure(e){await r.configure(e);}onDeepLink(e){this.deepLinkSub?.remove(),this.deepLinkSub=i.addListener("onDeepLink",t=>{e(t??null);});}onDeferredDeepLink(e){this.deferredSub?.remove(),this.deferredSub=i.addListener("onDeferredDeepLink",t=>{e(t?.data??null,t?.error??null);});}track(e,t){r.track(e,t??null);}async createLink(e,t,o,d="static",s){return r.createLink(e,t??null,o??null,d,s??null)}destroy(){this.deepLinkSub?.remove(),this.deferredSub?.remove();}};exports.ViaLinkSDK=n;

package/ios/ViaLinkModule.swift

@@ -5,9 +5,13 @@ import ViaLinkCore  // xcframework module: ViaLinkCore (class: ViaLinkSDK)
 @objc(ViaLinkSDK)
 class ViaLinkModule: RCTEventEmitter {
 
-    static let wrapperVersion = "2.1.0"
+    static let wrapperVersion = "3.1.0"
 
+    /// onDeepLink가 hasListeners == false 시점에 호출된 경우의 캐시.
+    /// 3.1.0부터 일반 진입(nil payload)도 콜백이 호출되므로, link 진입(map != nil) /
+    /// 일반 진입(map == nil)을 구분하기 위해 별도 플래그(`hasPendingDeepLink`)를 둔다.
     private var pendingDeepLink: [String: Any?]?
+    private var hasPendingDeepLink: Bool = false
     private var pendingDeferred: [String: Any?]?
     private var hasListeners = false
 
@@ -20,9 +24,11 @@ class ViaLinkModule: RCTEventEmitter {
 
     override func startObserving() {
         hasListeners = true
-        if let pending = pendingDeepLink {
-            sendEvent(withName: "onDeepLink", body: pending)
+        // 3.1.0+: pendingDeepLink가 nil이어도 hasPendingDeepLink가 true면 일반 진입 콜백을 flush한다.
+        if hasPendingDeepLink {
+            sendEvent(withName: "onDeepLink", body: pendingDeepLink as Any)
             pendingDeepLink = nil
+            hasPendingDeepLink = false
         }
         if let pending = pendingDeferred {
             sendEvent(withName: "onDeferredDeepLink", body: pending)
@@ -37,21 +43,28 @@ class ViaLinkModule: RCTEventEmitter {
             ViaLinkSDK.shared.setWrapper("react-native/\(Self.wrapperVersion)")
             ViaLinkSDK.shared.configure(apiKey: apiKey)
 
+            // 딥링크 콜백 — SDK 3.1.0+: data == nil이면 일반 진입을 의미한다.
+            // JS 측 emitter는 null payload를 그대로 전달받아 `data: null`로 콜백을 호출한다.
             ViaLinkSDK.shared.onDeepLink { [weak self] data in
-                let map = data.toDictionary()
+                let map: [String: Any?]? = data?.toDictionary()
                 if self?.hasListeners == true {
-                    self?.sendEvent(withName: "onDeepLink", body: map)
+                    self?.sendEvent(withName: "onDeepLink", body: map as Any)
                 } else {
                     self?.pendingDeepLink = map
+                    self?.hasPendingDeepLink = true
                 }
             }
 
-            ViaLinkSDK.shared.onDeferredDeepLink { [weak self] data in
-                let map = data.toDictionary()
+            // 디퍼드 콜백: SDK 3.0+ 시그니처 (data, error) — 항상 1회 호출
+            // JS 측 emit 페이로드는 `{data, error}` 객체로 전달한다.
+            ViaLinkSDK.shared.onDeferredDeepLink { [weak self] data, error in
+                var payload: [String: Any?] = [:]
+                if let data = data { payload["data"] = data.toDictionary() }
+                if let error = error { payload["error"] = error.toDictionary() }
                 if self?.hasListeners == true {
-                    self?.sendEvent(withName: "onDeferredDeepLink", body: map)
+                    self?.sendEvent(withName: "onDeferredDeepLink", body: payload)
                 } else {
-                    self?.pendingDeferred = map
+                    self?.pendingDeferred = payload
                 }
             }
 
@@ -151,3 +164,15 @@ extension DeepLinkData {
         ["path": path, "params": params, "shortCode": shortCode, "linkId": linkId]
     }
 }
+
+extension DeferredError {
+    /// JS DeferredError 인터페이스와 키가 일치해야 함
+    func toDictionary() -> [String: Any?] {
+        [
+            "code": code.rawValue,
+            "message": message,
+            "httpStatus": httpStatus,
+            "retryable": retryable,
+        ]
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vialink-react-native-sdk",
-  "version": "2.1.10",
+  "version": "3.1.1",
   "description": "ViaLink 딥링크 SDK for React Native (네이티브 브릿지)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/vialink-react-native-sdk.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name         = "vialink-react-native-sdk"
-  s.version      = "2.1.10"
+  s.version      = "3.1.1"
   s.summary      = "ViaLink Deep Link SDK for React Native"
   s.homepage     = "https://vialink.app"
   s.license      = "MIT"