Connect H5 with the app SDK

Last updated 10/03/2026

1. Solution overview

An app may contain some pages built with H5. The app SDK can't collect data from H5 pages, so you need to use the JavaScript SDK alongside it to collect user behavior on H5 pages. To keep the data from the JavaScript SDK consistent with the app SDK, newer SDK versions provide a data connection feature:

H5 pages use the JavaScript SDK to collect data. Instead of sending the collected data directly, the JavaScript SDK sends it to the server through the app SDK (that is, the Android SDK, iOS SDK, Flutter SDK, or ReactNative SDK). The app SDK adjusts the data collected by the JavaScript SDK according to the following rules:

1. The #time passed in by the JavaScript SDK is kept, that is, the event time is the time when the tracking point was triggered
2. The #account_id and #distinct_id of the app SDK are used, that is, the user maintained by the app SDK prevails
3. The preset properties of the app SDK are added. If they conflict with the JavaScript preset properties, the app SDK's preset properties overwrite the conflicting values. For example, for the #lib field, the app SDK's value overwrites the JavaScript SDK's value
4. Super properties of the app SDK: if they conflict with properties passed in by JavaScript, the native super property values are discarded; if the JavaScript SDK doesn't have the property, it is added to the reported data
5. The timeEvent API in the app SDK takes effect on events collected by the JavaScript SDK
6. The login, logout, and identify APIs in the JavaScript SDK can't modify the user ID in the app SDK. When H5 is connected with the app SDK, you can't modify the user ID of the data through these APIs in the JavaScript SDK
7. After you turn on the H5–app SDK connection switch, if the app SDK doesn't exist in the runtime environment, the JavaScript SDK reports data directly, the same as when the connection isn't enabled.

2. Usage

To enable the H5–app SDK connection, configure the JavaScript SDK and the app SDK as follows. Note the applicable SDK versions. If you're using an earlier version, upgrade to the latest version.

2.1 Android SDK usage

Android SDK 1.2.0 or later is required

Call setJsBridge when initializing the WebView:

TDAnalytics.setJsBridge(WebView webView);

To support Tencent's X5Webview, Android SDK 2.0.1 or later is required. Call setJsBridgeForX5WebView:

TDAnalytics.setJsBridgeForX5WebView(webView);

2.2 iOS SDK usage

iOS SDK 1.1.1 or later is required

WKWebView

Starting from iOS 17, setting a global UserAgent through NSUserDefaults is deprecated. You need to manually add the ThinkingData SDK-specific UserAgent to the WKWebView object. Otherwise, H5 can't be connected with the native app.

Add it as follows

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

Add the following code to the WKWebView delegate method 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. After initializing the SDK, call addWebViewUserAgent:

[TDAnalytics addWebViewUserAgent];

2. When initializing the WebView, make the following call based on the WebView type:

- (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 usage

Flutter SDK 3.1.0-beta.1 or later is required

Call addJavaScriptChannel when initializing the WebView, and call TDAnalytics.h5ClickHandler(); in the onMessageReceived callback

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

2.4 ReactNative SDK usage

ReactNative SDK 3.1.0-beta.1 or later is required

Call the injectedJavaScript method to inject JS when initializing the WebView, and call TDAnalytics.h5ClickHandler(); in the onMessage callback

<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 usage

JavaScript SDK 2.0.4 or later is required

• Add useAppTrack: true to the initialization parameters. Example:

(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 assigned by the system
  name: "ta", //Global variable name for calls. You can set it to any value and use this name in subsequent calls
  sdkUrl: "http://www.a.com/thinkingdata.js", //URL of the tracking script
  serverUrl: "https://global-receiver-ta.thinkingdata.cn:9080", //Data upload URL
  send_method: "image", //Data upload method
  useAppTrack: true // Connect the app with H5
});