add support for Flutter Web (#50)

Author: tshedor

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+## 1.3.0
+
+* Add support for Flutter web.
+
 ## 1.2.1
 
 * Add environment configuration on Android (#42)

README.md

@@ -22,6 +22,10 @@ Community implementation of native bindings for Datadog's SDK. **This is not an
 
 :warning: Your Podfile must have `use_frameworks!` (Flutter includes this by default) and your minimum iOS target must be >= 11. This is a requirement [from the Datadog SDK](https://github.com/DataDog/dd-sdk-ios/blob/master/DatadogSDKObjc.podspec#L17).
 
+### Flutter Web Caveats
+
+The Datadog scripts need to be inserted in your `index.html` document. Please add both the [logging script](https://docs.datadoghq.com/logs/log_collection/javascript/#cdn-async) and the [RUM script](https://docs.datadoghq.com/real_user_monitoring/browser/#cdn-async) to [their own](example/web/index.html) `<script>` tags. **DO NOT** add the `.init` on `.onReady` code.
+
 ## Logging
 
 In its default implementation, log data will only be transmitted to Datadog through [`Logger`](https://pub.dev/packages/logging) records. `print` statements are not guaranteed to be captured.
@@ -43,6 +47,10 @@ ddLogger.log('time to cook pizza', Level.FINE, attributes: {
 });
 ```
 
+### Flutter Web Caveats
+
+* `addTag` and `removeTag` are not invoked and resolve silently when using Flutter web. This is a missing feature in Datadog's JS SDK.
+
 ## Real User Monitoring
 
 RUM adds support for error, event, and screen tracking. The integration requires additional configuration for each service.
@@ -55,6 +63,7 @@ RUM adds support for error, event, and screen tracking. The integration requires
       environment: 'production',
       iosRumApplicationId: myiOSRumApplicationId,
       androidRumApplicationId: myAndroidRumApplicationId,
+      webRumApplicationId: myWebRumApplicationId,
     )
     ```
 1. Acknowledge `TrackingConsent` at initialization or later within your application. **Events will not be logged until `trackingConsent` is `.granted`**. This value can be updated via `DatadogFlutter.updateTrackingConsent`.
@@ -110,6 +119,15 @@ RUM adds support for error, event, and screen tracking. The integration requires
     )
     ```
 
+### Flutter Web Caveats
+
+* `addUserAction` ignores the `action` when using Flutter web.
+* `updateTrackingConsent` is not invoked and fails silently when using Flutter web. This is a missing feature in Datadog's JS SDK.
+* `stopView` is not invoked and fails silently when using Flutter web. This is a missing feature in Datadog's JS SDK.
+* `startUserAction` and `stopStopUserAction` are not invoked and fail silently when using Flutter web. This is a missing feature in Datadog's JS SDK.
+* `startResourceLoading` and `stopResourceLoading` are not invoked and resolve silently when using Flutter web. This is a missing feature in Datadog's JS SDK.
+* `setUserInfo` does not support custom attributes when using Flutter web. This is due to Dart's method of strongly typing JS. Only `name`, `id`, and `email` are supported.
+
 ## Tracing
 
 Associate your HTTP requests with your backend service. Be sure to setup (usually immediately after `DatadogFlutter.initialize`):

example/lib/main.dart

@@ -17,8 +17,9 @@ void main() async {
   await DatadogFlutter.initialize(
     clientToken: DATADOG_CLIENT_TOKEN,
     environment: 'production',
-    androidRumApplicationId: 'YOUR_IOS_RUM_APPLICATION_ID',
+    androidRumApplicationId: 'YOUR_ANDROID_RUM_APPLICATION_ID',
     iosRumApplicationId: 'YOUR_IOS_RUM_APPLICATION_ID',
+    webRumApplicationId: 'YOUR_WEB_RUM_APPLICATION_ID',
     serviceName: 'my-cool-app',
     trackingConsent: TrackingConsent.granted,
   );
@@ -57,11 +58,26 @@ class MyApp extends StatelessWidget {
         appBar: AppBar(
           title: Text('My Flutter Homepage'),
         ),
-        body: Center(
-          child: TextButton(
-            onPressed: () => otherLogger.fine('hello datadog'),
-            child: Text('Log to Datadog'),
-          ),
+        body: ListView(
+          children: [
+            TextButton(
+              onPressed: () => otherLogger.fine('FINE log from Flutter'),
+              child: Text('FINE Log to Datadog'),
+            ),
+            TextButton(
+              onPressed: () => otherLogger.warning('WARN log from Flutter'),
+              child: Text('WARN Log to Datadog'),
+            ),
+            TextButton(
+              onPressed: () =>
+                  DatadogRum.instance.addUserAction('Send Event Button'),
+              child: Text('Send Event To RUM'),
+            ),
+            TextButton(
+              onPressed: () => throw StateError('State Error from Flutter'),
+              child: Text('Report Zoned Error To RUM'),
+            ),
+          ],
         ),
       ),
       navigatorObservers: [

example/web/favicon.png

@@ -0,0 +1,113 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <!--
+    If you are serving your web app in a path other than the root, change the
+    href value below to reflect the base path you are serving from.
+
+    The path provided below has to start and end with a slash "/" in order for
+    it to work correctly.
+
+    For more details:
+    * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base
+  -->
+  <base href="/">
+
+  <meta charset="UTF-8">
+  <meta content="IE=Edge" http-equiv="X-UA-Compatible">
+  <meta name="description" content="A new Flutter project.">
+
+  <!-- iOS meta tags & icons -->
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black">
+  <meta name="apple-mobile-web-app-title" content="example">
+  <link rel="apple-touch-icon" href="icons/Icon-192.png">
+
+  <title>example</title>
+  <link rel="manifest" href="manifest.json">
+  <script>
+    (function(h,o,u,n,d) {
+      h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
+      d=o.createElement(u);d.async=1;d.src=n
+      n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
+    })(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-logs-v3.js','DD_LOGS')
+  </script>
+
+  <script>
+    (function(h,o,u,n,d) {
+      h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
+      d=o.createElement(u);d.async=1;d.src=n
+      n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
+    })(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-rum-v3.js','DD_RUM')
+  </script>
+</head>
+<body>
+  <!-- This script installs service_worker.js to provide PWA functionality to
+       application. For more information, see:
+       https://developers.google.com/web/fundamentals/primers/service-workers -->
+  <script>
+    var serviceWorkerVersion = null;
+    var scriptLoaded = false;
+    function loadMainDartJs() {
+      if (scriptLoaded) {
+        return;
+      }
+      scriptLoaded = true;
+      var scriptTag = document.createElement('script');
+      scriptTag.src = 'main.dart.js';
+      scriptTag.type = 'application/javascript';
+      document.body.append(scriptTag);
+    }
+
+    if ('serviceWorker' in navigator) {
+      // Service workers are supported. Use them.
+      window.addEventListener('load', function () {
+        // Wait for registration to finish before dropping the <script> tag.
+        // Otherwise, the browser will load the script multiple times,
+        // potentially different versions.
+        var serviceWorkerUrl = 'flutter_service_worker.js?v=' + serviceWorkerVersion;
+        navigator.serviceWorker.register(serviceWorkerUrl)
+          .then((reg) => {
+            function waitForActivation(serviceWorker) {
+              serviceWorker.addEventListener('statechange', () => {
+                if (serviceWorker.state == 'activated') {
+                  console.log('Installed new service worker.');
+                  loadMainDartJs();
+                }
+              });
+            }
+            if (!reg.active && (reg.installing || reg.waiting)) {
+              // No active web worker and we have installed or are installing
+              // one for the first time. Simply wait for it to activate.
+              waitForActivation(reg.installing ?? reg.waiting);
+            } else if (!reg.active.scriptURL.endsWith(serviceWorkerVersion)) {
+              // When the app updates the serviceWorkerVersion changes, so we
+              // need to ask the service worker to update.
+              console.log('New service worker available.');
+              reg.update();
+              waitForActivation(reg.installing);
+            } else {
+              // Existing service worker is still good.
+              console.log('Loading app from service worker.');
+              loadMainDartJs();
+            }
+          });
+
+        // If service worker doesn't succeed in a reasonable amount of time,
+        // fallback to plaint <script> tag.
+        setTimeout(() => {
+          if (!scriptLoaded) {
+            console.warn(
+              'Failed to load app from service worker. Falling back to plain <script> tag.',
+            );
+            loadMainDartJs();
+          }
+        }, 4000);
+      });
+    } else {
+      // Service workers not supported. Just drop the <script> tag.
+      loadMainDartJs();
+    }
+  </script>
+</body>
+</html>

example/web/index.html

@@ -0,0 +1,11 @@
+{
+    "name": "example",
+    "short_name": "example",
+    "start_url": ".",
+    "display": "standalone",
+    "background_color": "#0175C2",
+    "theme_color": "#0175C2",
+    "description": "A new Flutter project.",
+    "orientation": "portrait-primary",
+    "prefer_related_applications": false
+}

example/web/manifest.json

@@ -23,6 +23,7 @@ class DatadogFlutter {
     String flavorName = '',
     String? iosRumApplicationId,
     bool useEUEndpoints = false,
+    String? webRumApplicationId,
   }) async {
     await channel.invokeMethod('initWithClientToken', {
       'androidRumApplicationId': androidRumApplicationId,
@@ -33,6 +34,7 @@ class DatadogFlutter {
       'serviceName': serviceName,
       'trackingConsent': trackingConsent.index,
       'useEUEndpoints': useEUEndpoints,
+      'webRumApplicationId': webRumApplicationId,
     });
   }
 
@@ -57,6 +59,8 @@ class DatadogFlutter {
   /// and it is changed to `.granted`, the SDK will send all current and
   /// future data to Datadog; if changed to `.notGranted`, the SDK will
   /// wipe all current data and will not collect any future data.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   static Future<void> updateTrackingConsent(
     TrackingConsent trackingConsent,
   ) async {

lib/datadog_flutter.dart

@@ -24,6 +24,7 @@ class DatadogLogger {
     if (bindOnRecord) Logger.root.onRecord.listen(onRecordCallback);
   }
 
+  /// Adds an attribute to all future messages from this logger.
   Future<void> addAttribute(String attributeName, String value) async {
     return await channel.invokeMethod('loggerAddAttribute', {
       'identifier': hashCode.toString(),
@@ -32,6 +33,9 @@ class DatadogLogger {
     });
   }
 
+  /// Adds a tag to all future messages from this logger.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   Future<void> addTag(String tagName, String value) async {
     return await channel.invokeMethod('loggerAddTag', {
       'identifier': hashCode.toString(),
@@ -48,13 +52,17 @@ class DatadogLogger {
         attributes: {'loggerName': record.loggerName},
       );
 
+  /// Removes a previously-added attribute from all future messages from this logger.
   Future<void> removeAttribute(String attributeName) async {
     return await channel.invokeMethod('loggerRemoveAttribute', {
       'identifier': hashCode.toString(),
       'key': attributeName,
     });
   }
 
+  /// Removes a previously-added tag from all future messages from this logger.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   Future<void> removeTag(String tagName) async {
     return await channel.invokeMethod('loggerRemoveTag', {
       'identifier': hashCode.toString(),

lib/datadog_logger.dart

@@ -56,6 +56,8 @@ class DatadogRum {
   }
 
   /// Manually track a user event.
+  ///
+  /// [action] is ignored when using Flutter web.
   Future<void> addUserAction(
     String name, {
     RUMAction action = RUMAction.tap,
@@ -81,6 +83,8 @@ class DatadogRum {
   /// should be used by [stopLoading] when ready.
   ///
   /// [method] should be an uppercase HTTP method.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   static Future<void> startResourceLoading(
     String key, {
     required String url,
@@ -105,6 +109,8 @@ class DatadogRum {
   /// This is used to track long running user actions (e.g. "scroll").
   /// Such an User Action must be stopped with [stopUserAction], and
   /// will be stopped automatically if it lasts for more than 10 seconds.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   Future<void> startUserAction(
     String name, {
     RUMAction action = RUMAction.tap,
@@ -126,6 +132,8 @@ class DatadogRum {
   ///
   /// [attributes] will not be reported if [errorMessage] is present
   /// on Android.
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   static Future<void> stopResourceLoading(
     String key, {
     int? statusCode,
@@ -146,6 +154,8 @@ class DatadogRum {
   ///
   /// This is used to stop tracking long running user actions (e.g. "scroll"),
   /// started with [startUserAction].
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   Future<void> stopUserAction(
     String name, {
     RUMAction action = RUMAction.tap,
@@ -157,6 +167,8 @@ class DatadogRum {
   }
 
   /// Manually track exit from a screen. See [DatadogObserver].
+  ///
+  /// This is not invoked and resolves silently when using Flutter web.
   Future<void> stopView(String screenName) async {
     return await channel.invokeMethod('rumStopView', {'key': screenName});
   }

lib/datadog_rum.dart

@@ -0,0 +1,55 @@
+import 'dart:async';
+
+import 'package:datadog_flutter/src/web/datadog_web_logger.dart';
+import 'package:datadog_flutter/src/web/datadog_web_rum.dart';
+
+import 'package:flutter/services.dart';
+import 'package:datadog_flutter/src/channel.dart';
+import 'package:flutter_web_plugins/flutter_web_plugins.dart';
+
+class DatadogFlutterPlugin {
+  final logger = DatadogWebLogger();
+  final rum = DatadogWebRum();
+
+  static void registerWith(Registrar registrar) {
+    final _channel = MethodChannel(
+      channel.name,
+      const StandardMethodCodec(),
+      registrar,
+    );
+    final instance = DatadogFlutterPlugin();
+    _channel.setMethodCallHandler(instance.handleMethodCall);
+  }
+
+  Future<dynamic> handleMethodCall(MethodCall call) async {
+    switch (call.method) {
+      case 'initWithClientToken':
+        logger.init(call);
+        if (call.arguments['webRumApplicationId'] != null) {
+          rum.init(call);
+        }
+
+        return true;
+      // tracing is handled natively on the browser
+      case 'tracingCreateHeadersForRequest':
+        return {};
+      case 'tracingInitialize':
+        return false;
+      case 'tracingFinishSpan':
+        return true;
+      // trackingConsent is handled by `site:` on the browser
+      case 'updateTrackingConsent':
+        return false;
+
+      default:
+        final result =
+            logger.handleMethodCall(call) ?? rum.handleMethodCall(call);
+        if (result != null) return result;
+        throw PlatformException(
+          code: 'Unimplemented',
+          details:
+              "The datadog_flutter plugin for web doesn't implement '${call.method}'",
+        );
+    }
+  }
+}