WebApp Integration

This feature is supported in Flutter SDK 2.13.0 and above, and JavaScript SDK 11.25.1 and above.

For information about WebApps, refer to the documentation.

Starting with Flutter SDK 3.0.0, a Message Channel integration method has been added for asynchronous processing. If you set getWebBridgeScript(messageChannel: true), you must register HackleApp.webViewMessageHandler in onWebViewCreated.

When rendering your own website via InAppWebView, you can configure the Hackle JavaScript SDK embedded in the website to work identically to the Hackle Flutter SDK features without modifying the website code by applying the following settings.

In this case, all Hackle events are collected through the Flutter SDK.

For initialUserScripts, it is not guaranteed to be called before the web page loads on Android, so you must load the page from the controller returned in onWebViewCreated.

If your website fires events at beforeunload or unload and closes the WebView at that point, events may not fire correctly or unexpected behavior such as OS popups may occur.

To fire events during these lifecycle hooks, use Flutter InAppWebView's KeepAlive feature to keep the WebView object alive at the native level even after it is removed from the Flutter widget tree, which ensures events are fired correctly.

import 'dart:collection';

import 'package:flutter_inappwebview/flutter_inappwebview.dart';
import 'package:hackle/hackle.dart';

final keepAlive = InAppWebViewKeepAlive();

InAppWebView(
  initialSettings: InAppWebViewSettings(
    javaScriptEnabled: true,
  ),
  keepAlive: keepAlive,
  initialUserScripts: UnmodifiableListView<UserScript>([
    UserScript(
      source: HackleApp.getWebBridgeScript(messageChannel: true),
      injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
      forMainFrameOnly: true
    )]),
  onWebViewCreated: (controller) {
    controller.addJavaScriptHandler(
      handlerName: HackleApp.webViewMessageHandlerName,
      callback: HackleApp.webViewMessageHandler,
    );
    controller.loadUrl(urlRequest: URLRequest(url: WebUri('YOUR_WEB_URL')));
  },
  onJsPrompt: (controller, jsPromptRequest) async {
    if(HackleApp.isInvocableCommandInWebView(jsPromptRequest.message)) {
      var result = await HackleApp.handleWebInterfaceCommand(jsPromptRequest.message);
      return JsPromptResponse(action: JsPromptResponseAction.CONFIRM, handledByClient: true, value: result);
    } else {
      return JsPromptResponse(handledByClient: false);
    }
  },
);

To use this feature, the JavaScript web page must use the same App SDK Key.

The Hackle Flutter WebView configuration uses Android Javascript Userscript and similar mechanisms to interact with the Hackle JavaScript SDK.

Integrating Auto-collected Events from WebView

This feature is supported in Flutter SDK 2.26.0 and above, and JavaScript SDK 11.51.0 and above.

$page_view events occurring on the website inside the WebView are disabled by default. You can enable auto-collected events by configuring HackleWebViewConfig when setting up the WebView bridge.

import 'dart:collection';

import 'package:flutter_inappwebview/flutter_inappwebview.dart';
import 'package:hackle/hackle.dart';

final webViewConfig = HackleWebViewConfig.builder()
  .automaticScreenTracking(true)
	.automaticEngagementTracking(true)
  .build();

...
UserScript(
  source: HackleApp.getWebBridgeScript(webViewConfig: webViewConfig),
  injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
  forMainFrameOnly: true
)]),
...

Configuration Options

Config	Description	Default	Supported Version
automaticScreenTracking	Whether to collect $page_view events occurring on the website	false	2.26.0+
automaticEngagementTracking	Whether to collect $engagement events occurring on the website	false	2.28.0+
automaticRouteTracking	Whether to automatically collect page information occurring on the website	true	2.28.0+