|
4 | 4 |
|
5 | 5 | import 'dart:convert'; |
6 | 6 |
|
| 7 | +import 'package:meta/meta.dart'; |
| 8 | + |
7 | 9 | import 'enums.dart'; |
8 | 10 |
|
9 | 11 | final class Event { |
@@ -458,16 +460,44 @@ final class Event { |
458 | 460 | /// |
459 | 461 | /// * [exitCode] - the process exit code set as a result of running the |
460 | 462 | /// command. |
| 463 | + /// |
| 464 | + /// * [pubspecHasFlutterSdk] - whether the project's pubspec explicitly |
| 465 | + /// declares a dependency on the Flutter SDK (e.g. `sdk: flutter` or |
| 466 | + /// `environment.flutter`). |
| 467 | + /// |
| 468 | + /// * [pubspecDependencies] - a set of public package names depended upon by |
| 469 | + /// the project. Callers MUST verify packages against |
| 470 | + /// `.dart_tool/package_config.json` to ensure only public hosted packages |
| 471 | + /// (published to pub.dev or public registries) are passed. Non-hosted |
| 472 | + /// packages (path, git, un-versioned workspace members) must be excluded |
| 473 | + /// to prevent leaking proprietary or internal package names. |
| 474 | + /// |
| 475 | + /// * [pubspecEnvironmentSdk] - the Dart SDK version constraint declared in |
| 476 | + /// the project's pubspec (e.g. `^3.5.0` from `environment.sdk:`). |
| 477 | + /// |
| 478 | + /// NOTE FOR MAINTAINERS: Google Analytics 4 limits each event to at most 25 |
| 479 | + /// custom parameters. With standard metadata fields taking up 4–5 slots and |
| 480 | + /// dependency chunking consuming up to 20 parameters (`pubspec_dep_0` through |
| 481 | + /// `pubspec_dep_19`), adding any new parameters to this constructor requires |
| 482 | + /// decreasing `maxChunks` in [chunkDependencies] to prevent dropping event |
| 483 | + /// parameters. |
461 | 484 | Event.dartCliCommandExecuted({ |
462 | 485 | required String name, |
463 | 486 | required String enabledExperiments, |
464 | 487 | int? exitCode, |
| 488 | + bool? pubspecHasFlutterSdk, |
| 489 | + Set<String>? pubspecDependencies, |
| 490 | + String? pubspecEnvironmentSdk, |
465 | 491 | }) : this._( |
466 | 492 | eventName: DashEvent.dartCliCommandExecuted, |
467 | 493 | eventData: { |
468 | 494 | 'name': name, |
469 | 495 | 'enabledExperiments': enabledExperiments, |
470 | 496 | 'exitCode': ?exitCode, |
| 497 | + 'pubspec_has_flutter_sdk': ?pubspecHasFlutterSdk, |
| 498 | + 'pubspec_environment_sdk': ?pubspecEnvironmentSdk, |
| 499 | + if (pubspecDependencies != null) |
| 500 | + ...chunkDependencies(pubspecDependencies), |
471 | 501 | }, |
472 | 502 | ); |
473 | 503 |
|
@@ -1209,3 +1239,106 @@ abstract base class CustomMetrics { |
1209 | 1239 | /// This must be a JSON-encodable [Map]. |
1210 | 1240 | Map<String, Object> toMap(); |
1211 | 1241 | } |
| 1242 | + |
| 1243 | +/// Public helper in unified_analytics to sort and chunk dependencies. |
| 1244 | +/// |
| 1245 | +/// Respects GA4's 100-character limit per parameter and 25-parameter limit |
| 1246 | +/// per event. |
| 1247 | +/// |
| 1248 | +/// To eliminate alphabetical bias (e.g., always omitting packages starting |
| 1249 | +/// with 'z' when exceeding the 20-chunk cap) while preventing ecosystem-wide |
| 1250 | +/// starvation of specific package names across projects, dependencies are |
| 1251 | +/// sorted deterministically using a 32-bit FNV-1a hash salted with the |
| 1252 | +/// project's canonical dependency set. |
| 1253 | +/// |
| 1254 | +/// This ensures: |
| 1255 | +/// 1. **Cross-Machine Stability**: Identical dependency sets always produce the |
| 1256 | +/// exact same deterministic chunk payload across developers and CI runs. |
| 1257 | +/// 2. **Cross-Project Diversity**: Different projects produce different hash |
| 1258 | +/// permutations, ensuring no package is globally starved across the |
| 1259 | +/// ecosystem under truncation. |
| 1260 | +/// 3. **Zero PII**: Salt is derived strictly from public package names without |
| 1261 | +/// relying on local paths, usernames, or private project identifiers. |
| 1262 | +@visibleForTesting |
| 1263 | +Map<String, String> chunkDependencies(Set<String> deps) { |
| 1264 | + if (deps.isEmpty) return const {}; |
| 1265 | + |
| 1266 | + // Compute a deterministic project-level salt from the canonical |
| 1267 | + // (alphabetically sorted) dependency set. |
| 1268 | + final sortedBase = deps.toList()..sort(); |
| 1269 | + var setSalt = 2166136261; |
| 1270 | + for (final dep in sortedBase) { |
| 1271 | + setSalt = _fnv1a(dep, setSalt); |
| 1272 | + } |
| 1273 | + |
| 1274 | + // Sort deterministically by salted FNV-1a hash value. Fall back to |
| 1275 | + // alphabetical comparison if there is a hash collision to guarantee absolute |
| 1276 | + // determinism. |
| 1277 | + final sortedDeps = deps.toList() |
| 1278 | + ..sort((a, b) { |
| 1279 | + final hashA = _fnv1a(a, setSalt); |
| 1280 | + final hashB = _fnv1a(b, setSalt); |
| 1281 | + if (hashA != hashB) { |
| 1282 | + return hashA.compareTo(hashB); |
| 1283 | + } |
| 1284 | + return a.compareTo(b); |
| 1285 | + }); |
| 1286 | + |
| 1287 | + final chunks = <String, String>{}; |
| 1288 | + var currentChunk = <String>[]; |
| 1289 | + var currentLength = 0; |
| 1290 | + var chunkIndex = 0; |
| 1291 | + |
| 1292 | + // We have a maximum of 25 parameters per event in GA4. Standard event |
| 1293 | + // parameters (name, enabledExperiments, exitCode, pubspec_has_flutter_sdk) |
| 1294 | + // take up to 4 slots, leaving 21 slots. Capping at 20 chunks guarantees |
| 1295 | + // safety. |
| 1296 | + const maxChunks = 20; |
| 1297 | + |
| 1298 | + for (final dep in sortedDeps) { |
| 1299 | + // Guard: Skip package names that are somehow longer than 100 characters |
| 1300 | + // to prevent violating GA4's value length limit. |
| 1301 | + if (dep.length > 100) continue; |
| 1302 | + |
| 1303 | + final lengthToAdd = dep.length + (currentChunk.isEmpty ? 0 : 1); |
| 1304 | + if (currentLength + lengthToAdd > 100) { |
| 1305 | + chunks['pubspec_dep_$chunkIndex'] = currentChunk.join(','); |
| 1306 | + chunkIndex++; |
| 1307 | + |
| 1308 | + // Stop adding chunks if we reach the GA4 parameter count safety limit |
| 1309 | + if (chunkIndex >= maxChunks) { |
| 1310 | + currentChunk = const []; |
| 1311 | + break; |
| 1312 | + } |
| 1313 | + |
| 1314 | + currentChunk = [dep]; |
| 1315 | + currentLength = dep.length; |
| 1316 | + } else { |
| 1317 | + currentChunk.add(dep); |
| 1318 | + currentLength += lengthToAdd; |
| 1319 | + } |
| 1320 | + } |
| 1321 | + |
| 1322 | + if (currentChunk.isNotEmpty && chunkIndex < maxChunks) { |
| 1323 | + chunks['pubspec_dep_$chunkIndex'] = currentChunk.join(','); |
| 1324 | + } |
| 1325 | + |
| 1326 | + return chunks; |
| 1327 | +} |
| 1328 | + |
| 1329 | +/// Computes a deterministic 32-bit FNV-1a hash of a string with an optional |
| 1330 | +/// seed. |
| 1331 | +/// |
| 1332 | +/// This is used to shuffle dependency names in a stable, pseudo-random |
| 1333 | +/// way to eliminate alphabetical and global package bias when sampling packages |
| 1334 | +/// for telemetry while maintaining 100% determinism across runs. |
| 1335 | +int _fnv1a(String s, [int seed = 2166136261]) { |
| 1336 | + var hash = seed; |
| 1337 | + for (var i = 0; i < s.length; i++) { |
| 1338 | + hash ^= s.codeUnitAt(i); |
| 1339 | + // Split the multiplication to prevent exceeding the 53-bit safe integer |
| 1340 | + // limit on the web. |
| 1341 | + hash = (((hash & 0xff) << 24) + (hash * 403)) & 0xffffffff; |
| 1342 | + } |
| 1343 | + return hash; |
| 1344 | +} |
0 commit comments