본문으로 건너뛰기

H5와 APP SDK 연동

최근 업데이트 2026. 10. 03.

1. 솔루션 소개​

APP에는 H5 페이지로 구성된 페이지가 있을 수 있습니다. 이 경우 APP SDK는 H5 페이지의 데이터를 수집할 수 없으므로 JavaScript SDK를 함께 사용하여 H5 페이지에서의 유저 행동을 수집해야 합니다. JavaScript SDK와 APP SDK의 데이터 일관성을 보장하기 위해 새 버전 SDK에 데이터 연동 기능이 추가되었습니다.

H5 페이지는 JavaScript SDK로 데이터를 수집하며, 수집한 데이터를 직접 전송하지 않고 APP SDK(Android SDK, iOS SDK, Flutter SDK, ReactNative SDK)를 통해 서버로 전송합니다. APP SDK는 JavaScript SDK가 수집한 데이터를 다음 규칙에 따라 조정합니다.

  1. JavaScript SDK가 전달한 #time을 유지합니다. 즉, 이벤트 시간은 트래킹이 트리거된 시간을 기준으로 합니다
  2. APP SDK의 #account_id와 #distinct_id를 사용하며, APP SDK가 관리하는 유저를 기준으로 합니다
  3. APP SDK의 시스템 속성을 추가합니다. JavaScript의 시스템 속성과 충돌하면 APP SDK의 시스템 속성이 충돌 값을 덮어씁니다. 예를 들어 #lib 필드는 APP SDK의 값이 JavaScript SDK의 값을 덮어씁니다
  4. APP SDK의 공통 속성: JavaScript에서 전달한 속성과 충돌하면 네이티브 공통 속성 값을 폐기하고, JavaScript SDK에 해당 속성이 없으면 전송 데이터에 추가합니다
  5. APP SDK의 timeEvent 인터페이스는 JavaScript SDK가 수집한 이벤트에도 적용됩니다
  6. JavaScript SDK의 login, logout, identify 인터페이스로는 APP SDK의 유저 ID를 수정할 수 없습니다. H5와 APP SDK가 연동된 경우 JavaScript SDK에서 위 인터페이스를 사용해 데이터의 유저 ID를 수정할 수 없습니다
  7. H5와 APP SDK 연동 스위치를 켠 후 실행 환경에 APP SDK가 없으면 JavaScript SDK가 데이터를 직접 전송하며, 이는 연동을 활성화하지 않은 상태와 같습니다.

2. 사용 방법​

H5와 APP SDK 연동 기능을 활성화하려면 JavaScript SDK와 APP SDK에서 다음과 같이 설정해야 합니다. SDK의 적용 버전에 유의하십시오. 이전 버전을 사용 중인 경우 최신 버전으로 업그레이드하십시오.

2.1 Android SDK 사용 방법​

Android SDK 1.2.0 이상 버전을 사용해야 합니다

WebView를 초기화할 때 setJsBridge를 호출합니다:

TDAnalytics.setJsBridge(WebView webView);

Tencent의 X5Webview를 지원해야 하는 경우 Android SDK 2.0.1 이상 버전을 사용해야 하며, setJsBridgeForX5WebView를 호출합니다:

TDAnalytics.setJsBridgeForX5WebView(webView);

2.2 iOS SDK 사용 방법​

iOS SDK 1.1.1 이상 버전을 사용해야 합니다

WKWebView​

iOS 17 이후 시스템에서는 NSUserDefaults로 전역 UserAgent를 설정하는 방식이 폐기되었습니다. WKWebView 객체에 ThinkingData SDK 고유의 UserAgent를 수동으로 추가해야 합니다. 그렇지 않으면 H5와 네이티브 앱의 연동을 구현할 수 없습니다.

추가 방법은 다음과 같습니다

WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
config.applicationNameForUserAgent = [NSString stringWithFormat:@"%@ %@", config.applicationNameForUserAgent ?: @"", @"/td-sdk-ios"]; 
WKWebView *webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];

WKWebView의 델리게이트 메서드 decidePolicyForNavigationAction에 다음 코드를 추가합니다

- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
    if ([TDAnalytics showUpWebView:webView withRequest:navigationAction.request]) {
        decisionHandler(WKNavigationActionPolicyCancel);
        return;
    }
    
    decisionHandler(WKNavigationActionPolicyAllow);
}

UIWebView​

1. SDK 초기화를 완료한 후 addWebViewUserAgent를 호출합니다:

[TDAnalytics addWebViewUserAgent];

2. WebView를 초기화할 때 WebView의 타입에 따라 다음과 같이 호출합니다:

- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType {
    if ([TDAnalytics showUpWebView:webView withRequest:request]) {
        return NO;
    }
    /*
        other code
    */
    return YES;
}

2.3 Flutter SDK 사용 방법​

Flutter SDK 3.1.0-beta.1 이상 버전을 사용해야 합니다

WebView를 초기화할 때 addJavaScriptChannel을 호출하고, onMessageReceived 콜백에서 TDAnalytics.h5ClickHandler();를 호출합니다

controller = WebViewController();
controller.addJavaScriptChannel("ThinkingData_APP_Flutter_Bridge", onMessageReceived: (JavaScriptMessage message){
    TDAnalytics.h5ClickHandler(message.message);
});

2.4 ReactNative SDK 사용 방법​

ReactNative SDK 3.1.0-beta.1 이상 버전을 사용해야 합니다

WebView를 초기화할 때 injectedJavaScript 메서드를 호출하여 js를 주입하고, onMessage 콜백에서 TDAnalytics.h5ClickHandler();를 호출합니다

<WebView
  ref={webViewRef}
  source={localHtmlFile}
  onMessage={ event => {
    console.log(event.nativeEvent.data);
    TDAnalytics.h5ClickHandler(event.nativeEvent.data);
  }}
  javaScriptEnabled={true}
  injectedJavaScript='window.ThinkingData_APP_ReactNative_Bridge = function(data) { window.ReactNativeWebView.postMessage(data); };'
/>

2.5 JavaScript SDK 사용 방법​

JavaScript SDK 2.0.4 이상 버전을 사용해야 합니다

  • 초기화 파라미터 설정에 useAppTrack: true를 추가합니다. 예시는 다음과 같습니다:
(function(param) {
  var p = param.sdkUrl,
    n = param.name,
    w = window,
    d = document,
    s = "script",
    x = null,
    y = null;
  w["ThinkingDataAnalyticalTool"] = n;
  w[n] =
    w[n] ||
    function(a) {
      return function() {
        (w[n]._q = w[n]._q || []).push([a, arguments]);
      };
    };
  var methods = [
    "track",
    "quick",
    "login",
    "logout",
    "trackLink",
    "userSet",
    "userSetOnce",
    "userAdd",
    "userDel",
    "setPageProperty"
  ];
  for (var i = 0; i < methods.length; i++) {
    w[n][methods[i]] = w[n].call(null, methods[i]);
  }
  if (!w[n]._t) {
    (x = d.createElement(s)), (y = d.getElementsByTagName(s)[0]);
    x.async = 1;
    x.src = p;
    y.parentNode.insertBefore(x, y);
    w[n].param = param;
  }
})({
  appId: "APP_ID", //시스템에서 할당한 APPID
  name: "ta", //전역 호출 변수 이름, 임의로 설정할 수 있으며 이후에는 이 이름으로 호출하면 됨
  sdkUrl: "http://www.a.com/thinkingdata.js", //통계 스크립트 URL
  serverUrl: "https://global-receiver-ta.thinkingdata.cn:9080", //데이터 업로드 URL
  send_method: "image", //데이터 업로드 방식
  useAppTrack: true // APP과 H5 연동
});
이 문서가 도움이 되었나요?
이 페이지의 내용