databuckets_event_tracker 2.0.0

Event Tracker SDK

CHANGELOG

2.0.0

🔥 Breaking Changes

• Loại bỏ Firebase: Xóa hoàn toàn firebase_core, firebase_analytics, firebase_app_installations. SDK không còn phụ thuộc vào Firebase.
• Loại bỏ setUserPseudoId() trong config: user_pseudo_id được tự động tạo dưới dạng "db-" + UUID v4 và lưu trữ trong SharedPreferences. Không còn cần cấu hình giá trị này trong init config; nếu cần override thủ công, API Event.setUserPseudoId() vẫn còn được export.
• Loại bỏ session_end event: Chỉ còn session_start. Session duration được tính bằng engagement time.
• Loại bỏ app_instance_id: Không còn thuộc default user properties.
• Loại bỏ codegen (json_serializable): event.g.dart bị xóa, event model dùng toJson() thủ công.
• Đổi setMaxFlushSizeMB() thành setMaxFlushSizeKB(): Đơn vị cấu hình flush size đổi từ MB sang KB.
• Thay đổi giá trị mặc định config:
  • maxEventsStored: 5,000 → 50,000
  • maxFlushSize: 5 MB → 256 KB
• Thay đổi format gửi event: Từ JSON array sang NDJSON (newline-delimited JSON) với header Content-Type: application/x-ndjson và X-TIMESTAMP-MILLIS.
• Platform string viết thường: "android" / "ios" thay vì "ANDROID" / "IOS".

📦 Tính năng mới

Durable Storage (SQLite)

• Thêm dependency sqflite ^2.4.2 và path ^1.9.1.
• Event được lưu trữ trong SQLite database với WAL mode, synchronous=NORMAL, busy_timeout=3000.
• Tự động migration từ SharedPreferences (legacy) sang SQLite khi init.
• Corruption recovery: nếu DB bị lỗi, tự động xóa và tạo lại.
• Enforce DB caps: tối đa 50,000 events và 50 MB, WAL checkpoint mỗi 10 lần flush.

Memory Fallback Queue

• Khi SQLite không khả dụng, event được giữ trong memory queue (tối đa 500 events thường, 5,000 priority).
• Priority-aware eviction: evict event không ưu tiên trước.
• Auto-retry drain từ memory về SQLite (tối đa 5 lần).

Event Model v2

• SDK version: sdk_ver='2.0.0', sdk_ver_num=200.
• Thêm fields: engagement_time_msec, retention_hour, retention_minute.
• toCompactStringEvent() cho NDJSON serialization.
• createWithTimestamp() factory method.
• Reserved key protection: _filterReservedKeys() lọc 19 reserved keys khỏi user params.

JSON Sanitizer

• sanitize(): xử lý NaN → null, Infinity → null, DateTime → ISO8601, depth limit.
• validatePayload(): kiểm tra payload hợp lệ trước khi lưu.

Scheduler v2 (NDJSON + Priority Flush)

• HTTP format: NDJSON với headers Content-Type: application/x-ndjson, X-TIMESTAMP-MILLIS: <min_ts>.
• Flush loop: tối đa 5 batches, 200 events/batch, 256 KB/batch.
• Priority flush: immediate + 350ms follow-up, 1s cooldown.
• Delivery callbacks: FirstOpenTracker.markFirstOpenDelivered(), SessionHelper.markSessionStartDelivered().
• Poison event removal và sdk_events_dropped diagnostic event.
• Stuck flush guard: timeout 120s.

Session Helper v2

• Pending session start queue trong SharedPreferences (tối đa 512, format ts,number,durable;...).
• markSessionStartDelivered(tsMillis) callback khi HTTP 200.
• markAllPendingSessionStartsNonDurable() khi flush thất bại.
• Timestamp normalization, dependency injection qua onRecordEvent callback.

First Open Tracker v2

• Install window: 10 phút + 10 phút clock skew tolerance.
• markFirstOpenDelivered() khi HTTP 200, replay với 15s cooldown.
• Metadata: first_open_install_diff_ms, first_open_install_within_window.

Auto Tracker v2

• app_focus_start event khi app resumed, duration tính bằng milliseconds.
• Immediate flush khi app paused/detached qua onFlushNow callback.

Engagement Tracker

• Tính engagement_time_msec cho mỗi event.
• Returns 0 cho session_start, first_open, app_focus_start.

Exception Tracker

• enable()/disable() hooks FlutterError.onError + PlatformDispatcher.instance.onError.
• Ghi app_exception_log với log_condition (truncated 1024 chars).

Event Timestamp Tracker

• Bounded map (200 entries) cho recordWithTiming, auto-evict oldest.

Geo & Country Detection

• IP Country: Dual provider — ipinfo.io (primary) + api.infoip.io (fallback).
  • _fetchWithRetry(): max 2 retries, 0.4s delay, 5s timeout.
  • Cached result cho các lần gọi sau.
• Locale Country: MethodChannel getLocaleCountry.
  • Android: TelephonyManager SIM → Network → Locale fallback.
  • iOS: Locale.current.region?.identifier (iOS 16+) hoặc Locale.current.regionCode.
  • Dart fallback: parse Platform.localeName (e.g. "en_US" → "US").

App Info & Install Timestamp

• getInstallTimestamp() qua MethodChannel getInstallDay.
• Sanity check: timestamp > 2015-01-01 và < now + 24h.
• install_time_millis lưu trong SharedPreferences cho retention calculation.

🔧 Cải thiện

• CommonPropertiesUtil: Thêm setInternalProperty() cho SDK-managed keys (appid, platform, ip_country_code) — bypass reserved key filter.
• Reserved common keys: {sdk_ver, sdk_ver_num, appid, platform} — setCommonProperties() tự động lọc các key này.
• Default User Properties: Tự động set appid, platform, ip_country_code, và geo.country trong nested geo object khi init.
• Pre-init buffering: Facade buffer tối đa 200 events thường + 1,000 critical events trước khi SDK init xong.
• Event key validator: Thêm reservedKeys set (19 keys) và isReservedKey() method.
• Event size util: Constants mới — maxSingleEventBytes=200KB, maxPayloadBytes=256KB, maxEventsPerBatch=200.
• Retention calculation: calculateRetentionHour() và calculateRetentionMinute() dựa trên install_time_millis.

🗑️ Đã xóa

• sdk/lib/utils/firebase_installation_util.dart
• sdk/lib/model/event.g.dart
• Dependencies: firebase_core, firebase_analytics, firebase_app_installations

---

1.2.2

📝 Thay đổi

• Fix lỗi thiếu deps trên IOS

1.2.0

📝 Thay đổi

• Thêm lại session_end event để track được session_duration và session_end_reason
• Thay đổi cơ chế setUserPseudoId từ method -> config khi initialize
• Thêm cơ chế tự động setUserPseudoId khi không được set thủ công
• Thêm cơ chế tự động fetch và set installDate, loại bỏ việc set thủ công installDate
• Thêm cơ chế tự động tracking app_focus_end event
• Cập nhật cơ chế tự động tracking session_start, session_end event
• Thêm các field mặc định cho event: retention_hour, retention_minute, sdk_ver

1.1.4

📝 Thay đổi

• Bỏ qua việc gửi event session_end để tối ưu hóa hiệu suất
• Thêm session_id vào event session_start để theo dõi session tốt hơn

1.1.3

📦 Tính năng mới

• Tự động gửi các sự kiện người dùng gồm:
  • first_open: gửi khi người dùng mở ứng dụng lần đầu sau khi cài đặt.
  • session_start: gửi khi bắt đầu một phiên mới.

Chi tiết cách hoạt động các sự kiện trên, xem thêm 📄tài liệu hướng dẫn tại đây