
Wagmi v3 & AppKit 모바일 연동: 새로고침 후 딥링크가 먹통이 되는 원인과 해결 방법
모바일 브라우저에서 웹3 서비스를 개발할 때 가장 빈번하게 겪는 문제는 지갑 연결 후 조금만 시간이 지나도 트랜잭션 요청이 먹통이 되는 현상입니다. 화면에는 정상 연결로 표시되지만, 모바일 운영체제의 백그라운드 자원 관리 정책 때문에 실제 통신 채널인 웹소켓 세션이 끊기기 때문입니다. 이 글에서는 Wagmi v3와 Reown AppKit 환경에서 발생하는 모바일 세션 불일치와 무한 딥링크 루프의 원인을 짚어보고, 이를 완벽하게 해결할 수 있는 실전 대응 전략을 소개합니다.
Wagmi v3의 연결 모델 변화와 모바일 세션 불일치 현상
Wagmi v3 마이그레이션 가이드에 따르면 핵심 계정 연동 훅인 useAccount가 useConnection으로, useAccountEffect가 useConnectionEffect로 변경되었습니다. 이번 개편은 EIP-1193 표준 인터페이스와의 정렬을 강화하여 연결 상태와 커넥터 데이터를 보다 명확하게 다룰 수 있도록 돕습니다. 하지만 이 새로운 연결 모델을 모바일 브라우저에 적용할 때 세션 불일치 현상으로 인해 사용자 경험이 크게 저하되는 문제가 발생하고 있습니다.
Reown AppKit 이슈에 따르면 모바일 환경에서 사용자가 페이지를 새로고침할 때 브라우저의 로컬 스토리지는 기존 연결 세션을 유지하므로 화면에는 연결된 상태로 표시됩니다. 하지만 실제 지갑과 통신하던 웹소켓 페어링 채널은 모바일 운영체제의 백그라운드 및 샌드박스 보안 정책에 의해 끊어지거나 초기화됩니다. 이 상태에서 트랜잭션을 실행하면 지갑 앱을 호출하는 딥링크가 정상적으로 트리거되지 않고 무반응 상태에 갇히게 됩니다.
useReconnect와 Visibility API를 활용한 세션 자동 복구
모바일 브라우저의 자원 관리 방식은 Web3 개발자에게 까다로운 문제를 던집니다. 모바일 사파리나 크롬은 사용자가 화면을 잠그거나 지갑 앱으로 전환해 백그라운드로 밀려나는 즉시 웹소켓 연결을 일시 중단하거나 종료합니다. 이 때문에 화면에는 지갑 주소가 여전히 노출되고 로컬 스토리지 상으로는 연결된 것처럼 보이지만, 실제 통신 채널은 끊어져 버리는 상태 불일치 현상이 발생합니다. 이 상황에서 다시 트랜잭션을 제출하려고 하면, 지갑 앱을 여는 딥링크가 전혀 동작하지 않고 로딩에만 갇히게 됩니다.
이 문제를 해결하려면 dApp이 다시 포그라운드로 활성화되는 시점을 포착하여 웹소켓 페어링 터널을 강제로 재구축해야 합니다. Wagmi 코어 팀 가이드에 따르면 Wagmi v3에서는 기존 계정 상태를 가져오던 useAccount 훅이 useConnection으로 변경되었으며, 수동으로 커넥션 핸드셰이크를 유도할 수 있는 useReconnect 훅을 새롭게 제공합니다. useReconnect가 반환하는 reconnect.mutate() 함수를 수동으로 발화시키면 세션 채널을 즉시 되살릴 수 있습니다.
브라우저의 화면 활성화 상태를 감지하는 Page Visibility API와 창 포커스 이벤트를 활용해 세션을 자동으로 복구하는 커스텀 훅은 다음과 같이 구현할 수 있습니다.
이 커스텀 훅은 사용자가 모바일 지갑 앱에서 서명 처리를 마친 뒤 다시 dApp 화면으로 전환하여 활성화될 때 유기적으로 작동합니다. document.visibilityState가 visible로 바뀌거나 브라우저 창이 다시 포커스를 얻을 때마다 자동으로 reconnect.mutate()를 발화해 일시 정지 상태였던 소켓 채널을 즉각 복구합니다.
이를 연동해 두면 모바일 웹 브라우저의 절전 및 메모리 제한 정책 하에서도 사용자가 인위적으로 새로고침 버튼을 누르거나 화면을 추가로 터치할 필요가 없습니다. 백그라운드에서 복귀할 때마다 완벽한 연결 상태가 담보되므로, 연속적인 트랜잭션 호출과 딥링크 요청이 에러 없이 깔끔하게 전달되는 환경을 보장해 줍니다.
메타마스크 지연 컨펌으로 인한 무한 딥링크 루프 우회하기
모바일 환경에서 토큰 승인 후 민팅으로 이어지는 연속적인 트랜잭션을 처리할 때, 메타마스크의 서명 팝업 지연으로 발생하는 무한 딥링크 루프를 반드시 차단해야 합니다. 모바일 메타마스크 앱은 서명 승인 팝업을 띄우는 데 종종 5초에서 10초 이상의 지연 시간이 걸립니다.
Reown AppKit 이슈 분석에 따르면, 이 지연 시간 동안 유저가 대기를 참지 못하고 dApp 브라우저로 직접 돌아올 경우 자동 연결 상태 검증 리스너가 즉시 실행됩니다. 이 리스너가 세션을 복구하려고 유저를 다시 메타마스크로 강제 호출하면서, 브라우저와 지갑 앱을 무한히 오가는 딥링크 루프가 발생합니다.
이 문제를 해결하려면 트랜잭션 요청이 진행 중일 때는 강제 연결 복구 로직이 동작하지 않도록 상태 제어를 적용하고, Wagmi의 shimDisconnect 설정을 활성화해야 합니다. shimDisconnect는 로컬 스토리지의 세션 캐시 상태를 안전하게 관리하여, 불필요한 자동 재연결 시도로 인한 무한 리다이렉션을 방지합니다.
iOS와 Android 네이티브 설정: 딥링크 허용 기준 수립
하이브리드 앱이나 PWA 환경을 빌드하고 있다면, 프론트엔드 코드 수정뿐만 아니라 모바일 운영체제 수준의 딥링크 허용 설정을 선행해야 합니다. Reown 공식 문서에 따르면 모바일 환경에서는 보안을 위해 외부 앱 감지를 엄격하게 차단하므로, 네이티브 설정 파일에 대상 지갑들을 미리 등록해주어야 정상적으로 딥링크가 트리거됩니다.
iOS 환경에서는 지갑 앱의 커스텀 URL 스키마를 감지할 수 있도록 Info.plist 내 LSApplicationQueriesSchemes 배열에 메타마스크나 레인보우 등 타겟 지갑 스키마를 명확히 선언해야 합니다.
Android 11 이상 빌드 환경에서도 보안 정책으로 인해 기본적으로 패키지 노출이 제한됩니다. 따라서 AndroidManifest.xml 파일의 <queries> 엘리먼트 하위에 연동하려는 지갑 앱들의 실제 패키지 명을 명시적으로 명기해 주어야 시스템 수준에서 딥링크 가로채기나 차단 없이 정상적인 실행이 보장됩니다.
결론: 모바일 중심의 Web3 프런트엔드 구축을 위한 제언
모바일 환경에서의 Web3 연동은 데스크톱보다 훨씬 더 까다로운 자원 제약과 샌드박스 보안 정책을 마주하게 됩니다. 단순히 라이브러리를 기본 옵션으로 설치하는 것만으로는 실제 운영 환경의 사용자들에게 끊김 없는 지갑 서명 경험을 보장하기 어렵습니다.
Wagmi v3의 새로운 연결 모델과 모바일 운영체제의 특성을 정확히 파악해야 안정적인 서비스를 빌드할 수 있습니다. 브라우저 포커스 기반의 재연결 훅으로 소켓 끊김을 방지하고, 네이티브 딥링크 통합 설정을 철저히 조율하여 모바일 디앱의 완성도를 한 단계 높여보시기 바랍니다.
참고 링크
- Reown AppKit GitHub Issues — Looping Auto-Switch and MetaMask Delayed Confirmations (AppKit Issue #4785)
- Wagmi Core Team (Official v3 Migration Guide) — Wagmi v3 Renames Core Connection Hooks (useAccount to useConnection)
- Reown AppKit GitHub Issues — Mobile Reload Connection Desync & Deep Link Failures (AppKit Issue #4788)