refactor(llc, core, ui): update X-Stream-Client header for enhanced client identification (#2131)

* refactor(llc, core, ui): update X-Stream-Client header for enhanced client identification

* chore: update CHANGELOG.md

* chore: fix analysis

* fix: downgrade device_info_plus for lower flutter versions

* test: fix tests

* chore: remove extra methods

* refactor: append CurrentPlatform in default SystemEnvironment

* fix: fix test

* chore: fix lint

Author: xsahil03x

melos.yaml

@@ -32,6 +32,7 @@ command:
       contextmenu: ^3.0.0
       cupertino_icons: ^1.0.3
       desktop_drop: ^0.5.0
+      device_info_plus: ^11.3.0
       diacritic: ^0.1.5
       dio: ^5.4.3+1
       drift: ^2.22.1
@@ -65,6 +66,7 @@ command:
       media_kit_video: ^1.2.4
       meta: ^1.9.1
       mime: ^2.0.0
+      package_info_plus: ^8.3.0
       path: ^1.8.3
       path_provider: ^2.1.3
       photo_manager: ^3.2.0

packages/stream_chat/CHANGELOG.md

@@ -12,6 +12,7 @@
 🔄 Changed
 
 - Refactored identifying the `Attachment.uploadState` logic for local and remote attachments. Also updated the logic for determining the attachment type to check for ogScrapeUrl instead of `AttachmentType.giphy`.
+- Improved the `x-stream-client` header generation for better client identification and analytics.
 
 ✅ Added
 

packages/stream_chat/lib/src/client/client.dart

@@ -1,5 +1,3 @@
-// ignore_for_file: unnecessary_getters_setters
-
 import 'dart:async';
 
 import 'package:dio/dio.dart';
@@ -14,6 +12,7 @@ import 'package:stream_chat/src/core/api/stream_chat_api.dart';
 import 'package:stream_chat/src/core/error/error.dart';
 import 'package:stream_chat/src/core/http/connection_id_manager.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
+import 'package:stream_chat/src/core/http/system_environment_manager.dart';
 import 'package:stream_chat/src/core/http/token.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
 import 'package:stream_chat/src/core/models/attachment_file.dart';
@@ -27,10 +26,10 @@ import 'package:stream_chat/src/core/models/poll.dart';
 import 'package:stream_chat/src/core/models/poll_option.dart';
 import 'package:stream_chat/src/core/models/poll_vote.dart';
 import 'package:stream_chat/src/core/models/user.dart';
-import 'package:stream_chat/src/core/platform_detector/platform_detector.dart';
 import 'package:stream_chat/src/core/util/utils.dart';
 import 'package:stream_chat/src/db/chat_persistence_client.dart';
 import 'package:stream_chat/src/event_type.dart';
+import 'package:stream_chat/src/system_environment.dart';
 import 'package:stream_chat/src/ws/connection_status.dart';
 import 'package:stream_chat/src/ws/websocket.dart';
 import 'package:stream_chat/version.dart';
@@ -85,7 +84,6 @@ class StreamChatClient {
       baseUrl: baseURL,
       connectTimeout: connectTimeout,
       receiveTimeout: receiveTimeout,
-      headers: {'X-Stream-Client': defaultUserAgent},
     );
 
     _chatApi = chatApi ??
@@ -94,6 +92,7 @@ class StreamChatClient {
           options: options,
           tokenManager: _tokenManager,
           connectionIdManager: _connectionIdManager,
+          systemEnvironmentManager: _systemEnvironmentManager,
           attachmentFileUploaderProvider: attachmentFileUploaderProvider,
           logger: detachedLogger('🕸️'),
           interceptors: chatApiInterceptors,
@@ -105,11 +104,9 @@ class StreamChatClient {
           apiKey: apiKey,
           baseUrl: baseWsUrl ?? options.baseUrl,
           tokenManager: _tokenManager,
+          systemEnvironmentManager: _systemEnvironmentManager,
           handler: handleEvent,
           logger: detachedLogger('🔌'),
-          queryParameters: {
-            'X-Stream-Client': '$defaultUserAgent-$packageVersion',
-          },
         );
 
     _retryPolicy = retryPolicy ??
@@ -130,10 +127,31 @@ class StreamChatClient {
 
   final _tokenManager = TokenManager();
   final _connectionIdManager = ConnectionIdManager();
+  static final _systemEnvironmentManager = SystemEnvironmentManager();
+
+  /// Updates the system environment information used by the client.
+  ///
+  /// It allows you to set environment-specific information that will be
+  /// included in API requests, such as the application name, platform details,
+  /// and version information.
+  ///
+  /// Example:
+  /// ```dart
+  /// client.updateSystemEnvironment(
+  ///   SystemEnvironment(
+  ///     name: 'my_app',
+  ///     version: '1.0.0',
+  ///   ),
+  /// );
+  /// ```
+  ///
+  /// See [SystemEnvironment] for more information on the available fields.
+  void updateSystemEnvironment(SystemEnvironment environment) {
+    _systemEnvironmentManager.updateEnvironment(environment);
+  }
 
   /// Default user agent for all requests
-  static String defaultUserAgent =
-      'stream-chat-dart-client-${CurrentPlatform.name}';
+  static String defaultUserAgent = _systemEnvironmentManager.userAgent;
 
   /// Additional headers for all requests
   static Map<String, Object?> additionalHeaders = {};

packages/stream_chat/lib/src/core/api/stream_chat_api.dart

@@ -13,6 +13,7 @@ import 'package:stream_chat/src/core/api/threads_api.dart';
 import 'package:stream_chat/src/core/api/user_api.dart';
 import 'package:stream_chat/src/core/http/connection_id_manager.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
+import 'package:stream_chat/src/core/http/system_environment_manager.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
 
 export 'device_api.dart' show PushProvider;
@@ -26,6 +27,7 @@ class StreamChatApi {
     StreamHttpClientOptions? options,
     TokenManager? tokenManager,
     ConnectionIdManager? connectionIdManager,
+    SystemEnvironmentManager? systemEnvironmentManager,
     AttachmentFileUploaderProvider attachmentFileUploaderProvider =
         StreamAttachmentFileUploader.new,
     Logger? logger,
@@ -38,6 +40,7 @@ class StreamChatApi {
               options: options,
               tokenManager: tokenManager,
               connectionIdManager: connectionIdManager,
+              systemEnvironmentManager: systemEnvironmentManager,
               logger: logger,
               interceptors: interceptors,
               httpClientAdapter: httpClientAdapter,

packages/stream_chat/lib/src/core/http/interceptor/additional_headers_interceptor.dart

@@ -1,16 +1,25 @@
 import 'package:dio/dio.dart';
+import 'package:stream_chat/src/core/http/system_environment_manager.dart';
 import 'package:stream_chat/stream_chat.dart';
 
 /// Interceptor that sets additional headers for all requests.
 class AdditionalHeadersInterceptor extends Interceptor {
+  /// Initialize a new [AdditionalHeadersInterceptor].
+  const AdditionalHeadersInterceptor([this._systemEnvironmentManager]);
+
+  final SystemEnvironmentManager? _systemEnvironmentManager;
+
   @override
   Future<void> onRequest(
     RequestOptions options,
     RequestInterceptorHandler handler,
   ) async {
+    final userAgent = _systemEnvironmentManager?.userAgent;
+
     options.headers = {
       ...options.headers,
       ...StreamChatClient.additionalHeaders,
+      if (userAgent != null) 'X-Stream-Client': userAgent,
     };
     return handler.next(options);
   }

packages/stream_chat/lib/src/core/http/stream_http_client.dart

@@ -10,6 +10,7 @@ import 'package:stream_chat/src/core/http/interceptor/auth_interceptor.dart';
 import 'package:stream_chat/src/core/http/interceptor/connection_id_interceptor.dart';
 import 'package:stream_chat/src/core/http/interceptor/logging_interceptor.dart';
 import 'package:stream_chat/src/core/http/stream_chat_dio_error.dart';
+import 'package:stream_chat/src/core/http/system_environment_manager.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
 
 part 'stream_http_client_options.dart';
@@ -24,6 +25,7 @@ class StreamHttpClient {
     StreamHttpClientOptions? options,
     TokenManager? tokenManager,
     ConnectionIdManager? connectionIdManager,
+    SystemEnvironmentManager? systemEnvironmentManager,
     Logger? logger,
     Iterable<Interceptor>? interceptors,
     HttpClientAdapter? httpClientAdapter,
@@ -43,7 +45,7 @@ class StreamHttpClient {
         ..._options.headers,
       }
       ..interceptors.addAll([
-        AdditionalHeadersInterceptor(),
+        AdditionalHeadersInterceptor(systemEnvironmentManager),
         if (tokenManager != null) AuthInterceptor(this, tokenManager),
         if (connectionIdManager != null)
           ConnectionIdInterceptor(connectionIdManager),

packages/stream_chat/lib/src/core/http/system_environment_manager.dart

@@ -0,0 +1,65 @@
+// ignore_for_file: use_setters_to_change_properties
+
+import 'package:stream_chat/src/core/platform_detector/platform_detector.dart';
+import 'package:stream_chat/src/system_environment.dart';
+import 'package:stream_chat/version.dart';
+
+/// {@template systemEnvironmentManager}
+/// A manager class to handle the current [SystemEnvironment].
+/// {@endtemplate}
+class SystemEnvironmentManager {
+  /// {@macro systemEnvironmentManager}
+  SystemEnvironmentManager({
+    SystemEnvironment? environment,
+  }) : _environment = switch (environment) {
+          final env? => env,
+          _ => SystemEnvironment(
+              sdkName: 'stream-chat',
+              sdkIdentifier: 'dart',
+              sdkVersion: PACKAGE_VERSION,
+              osName: CurrentPlatform.name,
+            ),
+        };
+
+  /// Returns the Stream client user agent string based on the current
+  /// [environment] value.
+  String get userAgent => _environment.xStreamClientHeader;
+
+  /// The current [SystemEnvironment].
+  SystemEnvironment get environment => _environment;
+  SystemEnvironment _environment;
+
+  /// Updates the current [SystemEnvironment].
+  void updateEnvironment(SystemEnvironment environment) {
+    _environment = environment;
+  }
+}
+
+/// Extension on [SystemEnvironment] to build a Stream client header string.
+extension XStreamClientHeaderExtension on SystemEnvironment {
+  /// Builds a Stream client header string for API requests.
+  ///
+  /// The header follows the format:
+  /// `{sdk}-{identifier}-v{version}
+  /// |app={appName}
+  /// |app_version={appVersion}
+  /// |os={osName} {osVersion}
+  /// |device_model={deviceModel}`
+  ///
+  /// Only non-null values are included in the header.
+  String get xStreamClientHeader {
+    final clientInfo = '$sdkName-$sdkIdentifier-v$sdkVersion';
+
+    return [
+      clientInfo,
+      if (appName case final name?) 'app=$name',
+      if (appVersion case final version?) 'app_version=$version',
+      switch ((osName, osVersion)) {
+        (final name?, final version?) => 'os=$name $version',
+        (final name?, null) => 'os=$name',
+        _ => null,
+      },
+      if (deviceModel case final model?) 'device_model=$model',
+    ].nonNulls.join('|');
+  }
+}

packages/stream_chat/lib/src/core/platform_detector/platform_detector.dart

@@ -56,22 +56,15 @@ class CurrentPlatform {
 
   /// Returns a string version of the platform
   static String get name {
-    switch (type) {
-      case PlatformType.android:
-        return 'android';
-      case PlatformType.ios:
-        return 'ios';
-      case PlatformType.web:
-        return 'web';
-      case PlatformType.macOS:
-        return 'macos';
-      case PlatformType.windows:
-        return 'windows';
-      case PlatformType.linux:
-        return 'linux';
-      case PlatformType.fuchsia:
-        return 'fuchsia';
-    }
+    return switch (type) {
+      PlatformType.android => 'android',
+      PlatformType.ios => 'ios',
+      PlatformType.web => 'web',
+      PlatformType.macOS => 'macos',
+      PlatformType.windows => 'windows',
+      PlatformType.linux => 'linux',
+      PlatformType.fuchsia => 'fuchsia',
+    };
   }
 
   /// Get current platform type

packages/stream_chat/lib/src/system_environment.dart

@@ -0,0 +1,57 @@
+/// {@template streamChatSystemEnvironment}
+/// A class that represents the environment in which the Stream Chat SDK is
+/// running.
+///
+/// This class provides information about the SDK, application, and device
+/// used for tracking and debugging purposes.
+/// {@endtemplate}
+class SystemEnvironment {
+  /// {@macro streamChatSystemEnvironment}
+  const SystemEnvironment({
+    required this.sdkName,
+    required this.sdkIdentifier,
+    required this.sdkVersion,
+    this.appName,
+    this.appVersion,
+    this.osName,
+    this.osVersion,
+    this.deviceModel,
+  });
+
+  /// The name of the SDK.
+  final String sdkName;
+
+  /// The identifier of the SDK platform.
+  ///
+  /// This is used to distinguish between different implementations
+  /// (e.g., 'dart', 'flutter', etc.).
+  final String sdkIdentifier;
+
+  /// The version of the SDK.
+  final String sdkVersion;
+
+  /// The name of the application.
+  ///
+  /// This is null by default and could be set by the application.
+  final String? appName;
+
+  /// The version of the application.
+  ///
+  /// This is null by default and could be set by the application.
+  final String? appVersion;
+
+  /// The name of the operating system.
+  ///
+  /// This is null by default and could be set by the application.
+  final String? osName;
+
+  /// The version of the operating system.
+  ///
+  /// This is null by default and could be set by the application.
+  final String? osVersion;
+
+  /// The device model information.
+  ///
+  /// This is null by default and could be set by the application.
+  final String? deviceModel;
+}

packages/stream_chat/lib/src/ws/websocket.dart

@@ -6,6 +6,7 @@ import 'package:logging/logging.dart';
 import 'package:meta/meta.dart';
 import 'package:rxdart/rxdart.dart';
 import 'package:stream_chat/src/core/error/error.dart';
+import 'package:stream_chat/src/core/http/system_environment_manager.dart';
 import 'package:stream_chat/src/core/http/token_manager.dart';
 import 'package:stream_chat/src/core/models/event.dart';
 import 'package:stream_chat/src/core/models/user.dart';
@@ -34,6 +35,7 @@ class WebSocket with TimerHelper {
     required this.apiKey,
     required this.baseUrl,
     required this.tokenManager,
+    this.systemEnvironmentManager,
     this.handler,
     Logger? logger,
     this.webSocketChannelProvider,
@@ -52,9 +54,18 @@ class WebSocket with TimerHelper {
   /// WS base url
   final String baseUrl;
 
+  /// Manager responsible for handling authentication tokens.
   ///
+  /// Used to retrieve tokens for websocket connections and refreshing expired
+  /// tokens.
   final TokenManager tokenManager;
 
+  /// Manager that provides system environment information like SDK version and
+  /// platform details.
+  ///
+  /// Used to send client identification in websocket connection requests.
+  final SystemEnvironmentManager? systemEnvironmentManager;
+
   /// Functions that will be called every time a new event is received from the
   /// connection
   final EventHandler? handler;
@@ -157,11 +168,14 @@ class WebSocket with TimerHelper {
       'user_token': token.rawValue,
       'server_determines_connection_id': true,
     };
+
+    final userAgent = systemEnvironmentManager?.userAgent;
     final qs = {
       'json': jsonEncode(params),
       'api_key': apiKey,
       'authorization': token.rawValue,
       'stream-auth-type': token.authType.name,
+      if (userAgent != null) 'X-Stream-Client': jsonEncode(userAgent),
       ...queryParameters,
     };
 

packages/stream_chat/lib/stream_chat.dart

@@ -57,4 +57,5 @@ export 'src/core/util/extension.dart';
 export 'src/db/chat_persistence_client.dart';
 export 'src/event_type.dart';
 export 'src/permission_type.dart';
+export 'src/system_environment.dart';
 export 'src/ws/connection_status.dart';