WebView 연동
Sophonz Browser SDK를 모바일 네이티브 앱의 WebView와 연동해, 네이티브가 만든 세션을 웹 화면이 그대로 이어받게 하는 방법입니다.
Sophonz Browser SDK는 모바일 네이티브 앱의 WebView와 연동하여 네이티브 파라미터를 자동으로 공유할 수 있습니다. 이를 통해 네이티브 앱과 웹 애플리케이션 간의 데이터 통합 및 일관된 계측 경험을 제공합니다.
WebView 연동
네이티브 앱의 WebView에서 Browser SDK를 초기화하면, 네이티브 SDK가 이미 만든 세션과 앱 식별자를 그대로 이어받습니다. 같은 사용자의 네이티브 화면과 웹 화면이 하나의 세션으로 묶입니다.
연동 방식은 두 가지이고, SDK가 초기화 시 자동으로 감지합니다. 웹 브라우저 단독으로
열린 경우에는 둘 다 감지되지 않으므로 init()에 전달한 값을 그대로 사용합니다.
방식 1: 브릿지
네이티브가 JavaScript 인터페이스를 주입하고, SDK가 그것을 호출해 세션을 가져옵니다. 플랫폼마다 인터페이스가 다릅니다.
iOS — 네이티브가 webkit.messageHandlers.SophonzNative를 등록하면, SDK가 이를
감지해 window.SophonzNativeIOS 브릿지를 스스로 만듭니다. 브릿지는 invoke(action, data)로
네이티브에 메시지를 보내고, 네이티브는 window.SophonzNativeIOS.onNativeCallback(callbackId, result)로
응답합니다. 응답 대기는 5초에서 타임아웃됩니다.
Android — 네이티브가 window.SophonzNative 객체를 주입합니다. SDK는 동기 메서드
두 개를 호출하며, 각각 JSON 문자열을 반환해야 합니다.
| 메서드 | 필수 | 반환 |
|---|---|---|
getSession() | 필수 | 아래 세션 파라미터 객체 |
getResources() | 선택 | 리소스 속성 객체 |
방식 2: window 전역 변수
네이티브가 페이지 로드 전에 window.__sophonz_* 값을 직접 주입하는 방식입니다.
브릿지를 지원하지 않는 구버전 iOS WebView와의 호환을 위해 유지됩니다. SDK는
window.__sophonz_session_id의 존재로 이 방식을 판별합니다.
브릿지 방식도 결국 받아온 값을 같은 전역 변수에 기록하므로, 두 방식이 읽는 파라미터는 동일합니다.
| 변수 | 설명 |
|---|---|
__sophonz_session_id | 세션 ID. 이 값의 존재가 레거시 방식의 판별 기준입니다 |
__sophonz_app_name | 앱 이름. init()의 appName을 대체합니다 |
__sophonz_app_version | 네이티브 앱 버전. appVersion을 대체하며, 웹이 설정한 값은 web.version으로 유지됩니다 |
__sophonz_app_key | 앱 키 |
__sophonz_project | 프로젝트(service.namespace) |
__sophonz_collector_url | 콜렉터 URL |
__sophonz_service_type | 앱 타입. 비어 있으면 web |
__sophonz_deployment_environment_name | 배포 환경 이름 |
__sophonz_shared_session | 세션·앱 파라미터 공유 여부. 이 값이 있을 때만 WebView로 판별합니다 |
__sophonz_deactivated | true면 SDK가 동작하지 않습니다 |
__sophonz_resources | 추가 리소스 속성 |
전달된 값은 init()에 넘긴 값을 덮어씁니다. __sophonz_shared_session이 없으면 WebView로
보지 않고 init() 값을 그대로 사용합니다.
감지 순서
webkit.messageHandlers.SophonzNative가 있으면 iOS 브릿지- 없고
window.__sophonz_session_id가 있으면 레거시 iOS(window 전역) - 없고
window.SophonzNative가 있으면 Android 브릿지
리소스 속성
세션 파라미터와 별개로, 네이티브가 리소스 속성을 넘기면 웹 스팬의 리소스에 병합됩니다.
iOS 브릿지는 리소스 조회 액션으로, Android 브릿지는 getResources()로, 두 방식 모두
window.__sophonz_resources로도 전달할 수 있습니다. 세 경로 모두 병합되며, 나중에
읽힌 값이 앞의 값을 덮습니다.
웹 버전과 소스맵
WebView에서는 앱 버전과 웹 버전이 따로 움직입니다. 네이티브 바이너리는 스토어 심사를 거쳐 몇 주에 한 번 나가지만, WebView가 여는 웹은 웹 팀이 배포할 때마다 바뀝니다.
Browser SDK(2.1.0 이상)는 두 값을 따로 보냅니다.
| 리소스 속성 | 값 |
|---|---|
service.version | 브릿지가 전달한 네이티브 앱 버전(__sophonz_app_version) |
web.version | 페이지가 init()에 넘긴 appVersion. 브릿지가 덮어쓰지 않습니다 |
브릿지가 appVersion을 앱 버전으로 바꾸기 전에 SDK가 페이지의 값을 붙잡아 두므로, 네이티브 리소스 속성에 web.version이 들어 있어도 페이지의 값이 우선합니다.
WebView에서 난 JavaScript 에러는 web.version의 소스맵으로 복원됩니다. 웹 빌드마다 그 웹 버전으로 소스맵을 올리세요.
npx @sophonz/cli upload-sourcemaps --path dist --web-version "$WEB_VERSION"토큰은 텔레메트리가 도착하는 앱의 토큰을 씁니다. 브릿지로 세션을 공유하면 웹 텔레메트리도 네이티브 앱의 앱 키로 들어오므로, 네이티브 앱의 액세스 토큰으로 올립니다.
설정 > 프로젝트 > 앱 > 매핑 파일에서 네이티브 앱은 앱 버전과 웹 버전 목록을 함께 보여 줍니다. 웹 버전에 소스맵이 없으면 경고가 표시됩니다. 업로드 방법 전체는 소스맵 업로드를 참고하세요.