Track WebViews (Beta)

Once the WebView Tracking Tag is implemented in the web pages, you need to wrap any tracked WebView in the ContentsquareWebViewTrackerBuilder Widget.

Generic API

You can omit using our plugin and implement tracking your webviews manually (for example if you use a custom webView package).
In that case you need to use the ContentsquareWebViewTrackerBuilder widget constructor.

The builder provides a tracker with three methods, that need to be called in the following order:

tracker.registerWebViewController: registers the ContentsquareWebViewController with the tracker.
tracker.javascriptChannels: a set of (JavaScript) channels that you must register for the communication between Contentsquare and the WebView
tracker.startPageTracking: this method must be called every time a new page has finished loading.

See the following section for implementation examples featuring the most popular webview packages.

Implementation examples

If you are using the flutter_inappwebview ↗, use the following code can be used to track a webview:

ContentsquareWebViewTrackerBuilder(
  builder: (context, tracker) {
    return InAppWebView(
      initialUrlRequest: URLRequest(
        url: Uri.parse('https://your_tracked_webview.com'),
      ),
      onWebViewCreated: (controller) {

        tracker.registerWebViewController(
          ContentsquareWebViewController(
            evaluateJavascript: (source) async {
              return '${await controller.evaluateJavascript(source: source)}';
            },
            currentUrl: () async => '${await controller.getUrl()}',
            javascriptChannelCall: (channelName, data) {
              return 'window.flutter_inappwebview.callHandler("$channelName", $data)';
            },
          ),
        );


        for (final javascriptChannel in tracker.javascriptChannels) {
          controller.addJavaScriptHandler(
            handlerName: javascriptChannel.name,
            callback: (args) {
              return javascriptChannel.onMessageReceived(args.first);
            },
          );
        }
      },
      onLoadStop: (controller, uri) async {

        //
        // This MUST be called AFTER the controller is registered and the JavaScript
        // channels are available
        await tracker.startPageTracking();
      },
    );
  },
)

If you are using the webview_flutter ↗, use the following code can be used to track a webview:

Start by defining a WebViewTrackerInitializer widget:

class WebViewTrackerInitializer extends StatefulWidget {
  const WebViewTrackerInitializer({
    Key? key,
    required this.initialUrl,
    required this.tracker,
    required this.webviewController,
    required this.child,
  }) : super(key: key);

  final String initialUrl;
  final ContentsquareWebViewTracker tracker;
  final WebViewController webviewController;

  final Widget child;

  @override
  State<WebViewTrackerInitializer> createState() =>
      _WebViewTrackerInitializerState();
}

class _WebViewTrackerInitializerState extends State<WebViewTrackerInitializer> {
  Future<void> _initTracking() async {
    final tracker = widget.tracker;
    final controller = widget.webviewController;


    await controller.setJavaScriptMode(JavaScriptMode.unrestricted);


    tracker.registerWebViewController(
      ContentsquareWebViewController(
        evaluateJavascript: (source) async {
          return '${await controller.runJavaScriptReturningResult(source)}';
        },
        currentUrl: controller.currentUrl,
        javascriptChannelCall: (channelName, data) {
          return 'window.$channelName.postMessage($data)';
        },
      ),
    );


    for (final javascriptChannel in tracker.javascriptChannels) {
      await controller.addJavaScriptChannel(
        javascriptChannel.name,
        onMessageReceived: (javascriptMessage) {
          javascriptChannel.onMessageReceived(javascriptMessage.message);
        },
      );
    }

    await controller.setNavigationDelegate(
      NavigationDelegate(
        onPageFinished: (_) async {

          // This will be called AFTER the controller is registered and the
          // JavaScript channels are available since we register the controller
          // and the JavaScript channels BEFORE loading the initial url.
          await tracker.startPageTracking();
        },
      ),
    );

    await controller.loadRequest(Uri.parse(widget.initialUrl));
  }

  @override
  void initState() {
    super.initState();
    _initTracking();
  }

  @override
  Widget build(BuildContext context) => widget.child;
}

Which you can then use to track your webview:

ContentsquareWebViewTrackerBuilder(
  builder: (context, tracker) {
    return WebViewTrackerInitializer(
      initialUrl: 'https://your_tracked_webview.com',
      tracker: tracker,
      webviewController: webviewController,
      child: WebViewWidget(controller: webviewController),
    );
  },
)

If you are using the webview_flutter ↗ v2 or v3, use the following code can be used to track a webview:

ContentsquareWebViewTrackerBuilder(
  builder: (context, tracker) {
    return WebView(
      initialUrl: 'https://your_tracked_webview.com',

      javascriptMode: JavascriptMode.unrestricted,


      onWebViewCreated: (controller) {
        tracker.registerWebViewController(
          ContentsquareWebViewController(
            evaluateJavascript: controller.runJavascriptReturningResult,
            javascriptChannelCall: (channelName, data) {
              return 'window.$channelName.postMessage($data)';
            },
          ),
        );
      },


      javascriptChannels: {
        for (final channel in tracker.javascriptChannels)
          JavascriptChannel(
            name: channel.name,
            onMessageReceived: (message) => channel.onMessageReceived(
              message.message,
            ),
          ),
      },
      onPageFinished: (_) async {

        await tracker.startPageTracking();
      }
    );
  },
)

Validate WebView tracking

To validate that the WebView tracking is working correctly, check the logs in your Flutter console.
Opening a screen with tracked WebView will result in the following log:

┌───────────────────────────────────────────────────────────────────────────────
│ ℹ️ INFO ℹ️ (CSLIB) [Tracked WebView]
├───────────────────────────────────────────────────────────────────────────────
│ WebView tracking enabled on WebView with initialUrl:
│ https://your.tracked.website
└───────────────────────────────────────────────────────────────────────────────