브릿지 호출 기록
interceptor, autoCapture, DariMacros로 iOS 브릿지 트래픽을 기록합니다
세 가지 방법 중 하나로 브릿지 호출을 기록합니다. 먼저 시작하기대로 Dari를 시작하세요.
기록 방법 고르기
세 방법 모두 데스크톱 앱에는 똑같이 보이므로, 기록 코드가 어떤 식으로 들어가길 원하는지에 따라 고르면 됩니다.
| Interceptor | autoCapture | DariMacros | |
|---|---|---|---|
| 기록 방식 | 브릿지 코드에서 interceptor를 직접 호출 | 런타임에 WebKit 메서드를 바꿔치기(method swizzling) | 컴파일할 때 매크로가 handler에 기록 코드를 넣음 |
| 바꿀 코드 | 모든 송수신 지점 | start() 한 줄 | handler 타입마다 어트리뷰트 하나, evaluateJavaScript 대신 dari* 호출 |
| 서드파티 SDK의 handler | 수집 안 됨 | 수집됨 | 수집 안 됨 |
팀에서 swizzling을 피하거나, 다른 SDK가 이미 WebKit을 swizzling하거나, 어떤 handler가 기록되는지 코드로 드러나길 원하면 DariMacros를 고릅니다. 그렇지 않다면 autoCapture가 더 간단합니다.
브릿지 호출 기록
WKWebView마다 interceptor를 하나씩 만들고, 브릿지가 메시지를 받고 응답하는 곳에서 호출합니다. 메서드 구성은 Android의 DariInterceptor와 같습니다.
final class Bridge: NSObject, WKScriptMessageHandler, WKNavigationDelegate {
private let dari = Dari.shared.interceptor(tag: "main")
weak var webView: WKWebView?
// 이후에 기록하는 요청에 이 페이지 URL이 붙습니다. query와 fragment는 빠집니다.
func webView(_ webView: WKWebView, didCommit navigation: WKNavigation!) {
dari.onPageUrlChanged(webView.url?.absoluteString)
}
// Web → App
func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
let body = message.body as? [String: Any] ?? [:]
let handler = body["handler"] as? String ?? message.name
let requestId = body["requestId"] as? String
dari.onWebToAppRequest(handlerName: handler, requestId: requestId, requestData: body["data"] as? String)
let result = #"{"ok":true}"#
dari.onWebToAppResponse(handlerName: handler, requestId: requestId, responseData: result, isSuccess: true)
// ...결과를 페이지로 전달
}
// App → Web
func notifyPage(_ requestId: String, _ payload: String) {
dari.onAppToWebRequest(handlerName: "onResume", requestId: requestId, data: payload)
webView?.evaluateJavaScript("onResume(\(payload))") { value, error in
self.dari.onAppToWebResponse(requestId: requestId, isSuccess: error == nil, responseData: value.map { "\($0)" })
}
}
}- 요청과 응답은
requestId로 짝을 맞춥니다. 응답은 ID, tag, 방향이 같은 요청 가운데 아직 열려 있는 가장 최근 요청을 완료합니다. fireAndForget: true를 넘기면 보내는 즉시 완료된 메시지로 기록합니다.requestId만 nil로 넘기면 짝짓기를 건너뛸 뿐,fireAndForget(호출별 또는DariConfiguration)이 true가 아니면 진행 중으로 남습니다.- 핸들러 이름만으로 알아보기 어려우면
displayName:을 넘깁니다. start()전에 한 호출은 무시됩니다.- protobuf 바이트는
…Protobuf…메서드로 넘깁니다. Protocol Buffers를 참고하세요.
자동 수집
3.1.0부터는 Android의 Gradle 플러그인처럼 interceptor 호출 없이 브릿지 트래픽을 기록할 수 있습니다. 앱이 web view를 만들기 전에 start()에 autoCapture를 넘깁니다.
try Dari.shared.start(DariConfiguration(autoCapture: DariAutoCapture(tag: "main")))그러면 Dari가 런타임에 WebKit을 훅합니다.
| WebKit 호출 | 기록 방식 |
|---|---|
add(_:name:)로 등록한 handler가 메시지를 받음 | Web → App 요청 |
WKScriptMessageHandlerWithReply가 응답함 | 그 요청의 응답 |
evaluateJavaScript | App → Web 요청. completion의 결과나 에러가 응답 |
WKWebView마다 interceptor가 따로 생기고, 페이지 URL은 호출할 때마다 web view에서 읽습니다.
기본적으로 딕셔너리 body의 handler, requestId, data 필드로 호출 이름을 정하고 짝을 맞추며, 스크립트는 호출하는 함수 이름으로 기록합니다. 브릿지가 다른 필드를 쓰거나 콜백 스크립트로 페이지에 응답한다면 직접 매핑합니다.
DariAutoCapture(
tag: "main",
parseMessage: { name, body in
let fields = body as? [String: Any] ?? [:]
if fields["type"] as? String == "appToWebResponse" {
return .response(requestId: fields["requestId"] as? String ?? "", data: fields["data"] as? String, isSuccess: fields["success"] as? Bool ?? false)
}
return DariAutoCapture.defaultMessage(name: name, body: body)
},
parseScript: { script in
// onBridgeResponse("<id>", true, "<json>")는 Web → App 요청에 대한 응답입니다.
guard script.hasPrefix("onBridgeResponse(") else { return DariAutoCapture.defaultScript(script) }
return .response(requestId: parseRequestId(script), data: script, isSuccess: !script.contains(", false,"))
}
)requestId가 있는.request는 같은 ID의 응답을 기다립니다. 없으면 Dari가 ID를 만들어 reply나 completion과 짝을 맞춥니다.- 보고 싶지 않은 트래픽은
.ignore를 반환합니다. start()전에 등록한 handler나, 이 WebKit 호출을 거치지 않는 Swift 브릿지 코드는 수집되지 않습니다. 이런 경우는 interceptor를 씁니다.- 브릿지에서 이미 interceptor를 호출하고 있다면
autoCapture를 켜지 마세요. 메시지가 두 번 기록됩니다.
매크로로 컴파일 시점 수집
3.2.0부터는 브릿지 트래픽을 기록하는 세 번째 방법으로, 컴파일할 때 handler에 기록 코드를 넣어 주는 Swift 매크로를 제공합니다. 다른 방법과의 비교는 기록 방법 고르기를 참고하세요.
Swift 매크로가 처음이라면: 매크로는 컴파일러 안에서 돌면서 내 코드에 코드를 덧붙이는 코드입니다. 결과는 별도의 생성 파일이 아니라, 어트리뷰트를 붙인 선언 안에 바로 합쳐집니다. Xcode에서 어트리뷰트를 우클릭하고 Expand Macro를 고르면 만들어진 코드를 볼 수 있습니다.
1. DariMacros 라이브러리 추가
Xcode에서 타깃의 General → Frameworks, Libraries, and Embedded Content를 열고 **+**를 눌러 dari 패키지의 DariMacros를 추가합니다. Dari가 함께 들어오므로 import DariMacros 하나면 됩니다. Package.swift에서는 다음과 같이 추가합니다.
.product(name: "DariMacros", package: "dari")처음 빌드할 때 매크로를 신뢰할지 묻습니다. Trust & Enable을 고르세요. CI에서는 xcodebuild에 -skipMacroValidation을 넘깁니다. 매크로는 Xcode 16 이상이 필요한데, 지금 쓰는 Xcode라면 모두 해당합니다.
2. 메시지 handler에 표시
WKScriptMessageHandler를 구현한 클래스, 즉 add(_:name:)로 등록하는 클래스에 @DariBridge를 붙입니다.
import DariMacros
@DariBridge(tag: "main")
final class Bridge: NSObject, WKScriptMessageHandler, WKScriptMessageHandlerWithReply {
func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
// 기존 코드 그대로
}
func userContentController(
_ controller: WKUserContentController,
didReceive message: WKScriptMessage,
replyHandler: @escaping (Any?, String?) -> Void
) {
// 기존 코드 그대로
}
}Web → App 쪽은 이걸로 끝입니다. 매크로가 메시지 handler 메서드를 찾아 맨 위에 한 줄을 넣습니다. 두 번째 메서드는 개념상 다음처럼 바뀝니다.
func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage, replyHandler: @escaping (Any?, String?) -> Void) {
let replyHandler = _DariBridgeSupport.record(message, tag: "main", replyHandler: replyHandler)
// 기존 코드 그대로
}메시지는 Web → App 요청으로 기록되고, 감싼 replyHandler가 내가 보낸 답을 그 요청의 응답으로 기록합니다. _DariBridgeSupport를 직접 호출할 일은 없습니다.
- 대상 메서드:
userContentController(_:didReceive:),userContentController(_:didReceive:replyHandler:), 그리고async -> (Any?, String?)형태입니다. 타입의 다른 메서드는 건드리지 않습니다. tag,parseMessage는DariAutoCapture와 같게 동작합니다.- extension에 선언한 handler는 그 extension에도
@DariBridge를 붙여야 합니다. 매크로는 자신이 붙은 선언만 볼 수 있기 때문입니다.
@DariBridge(tag: "main")
extension Bridge: WKScriptMessageHandlerWithReply {
func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) async -> (Any?, String?) { … }
}3. WebKit 스크립트 호출 대신 dari 버전 호출
App → Web 호출은 handler 안이 아니라 코드 곳곳에서 일어나고, 매크로는 자신이 붙은 선언만 바꿀 수 있습니다. 그래서 이 호출은 같은 WebKit 호출을 실행하면서 기록도 하는 dari 버전으로 바꿉니다.
| 기존 호출 | 바꿀 호출 |
|---|---|
evaluateJavaScript(_:completionHandler:) | dariEvaluateJavaScript(_:tag:completionHandler:) |
evaluateJavaScript(_:in:in:completionHandler:) | dariEvaluateJavaScript(_:in:in:tag:completionHandler:) |
callAsyncJavaScript(_:arguments:in:in:completionHandler:) | dariCallAsyncJavaScript(_:arguments:in:in:tag:completionHandler:) |
모두 async 형태도 있습니다.
webView.dariEvaluateJavaScript("onPush(\(json))", tag: "main") { result, error in … }
let title = try await webView.dariEvaluateJavaScript("document.title", tag: "main")DariAutoCapture와 같은 parseScript를 받습니다. dariCallAsyncJavaScript는 함수 본문을 넘겨 줍니다.
알아 두면 좋은 점
- 매크로는 컴파일할 때 Mac에서 돌기 때문에 swift-syntax는 앱에 링크되지 않습니다. 다만
Dari만 쓰는 앱도 패키지를 받을 때 SPM이 swift-syntax를 내려받습니다. start()전에는 아무것도 기록하지 않으므로, Dari를 시작하지 않는 빌드에서는 기록되는 것이 없습니다.- 서드파티 SDK 안의 브릿지 handler에는 매크로를 붙일 수 없습니다. 이런 handler는
autoCapture로 수집합니다. - 함께 써도 됩니다.
autoCapture도 켜면 메시지는autoCapture의 tag로 한 번만 기록됩니다. - WebKit의 메시지 handler 메서드는 throw하지 않으므로, throw하는 handler는 지원하지 않습니다.
parseMessage는 매크로를 붙인 타입 바깥에 선언하세요.MyBridge에@DariBridge(parseMessage: MyBridge.parse)를 붙이면 "circular reference resolving attached macro" 에러가 나므로, 파서는 별도enum이나 전역에 둡니다.