[Flutter] Databuckets Event Tracker SDK - Hướng dẫn sử dụng #

Hướng Dẫn Tích Hợp Flutter Databuckets Event Tracker SDK

1. Thiết lập & Cài đặt #

a. Thêm dependency #

Trong dự án Flutter của bạn, mở file pubspec.yaml, thêm dòng sau:

dependencies:
  flutter:
    sdk: flutter
  databuckets_event_tracker: 1.2.2

Sau đó, chạy lệnh:

flutter pub get

b. Cấu hình Firebase #

Vì SDK có hỗ trợ Firebase nên yêu cầu file your_app/android/app/google-services.json trong quá trình build.

(Nếu không muốn hoặc chưa có Firebase thì SDK vẫn hoạt động bình thường, nhưng vẫn yêu cầu file google-services.json)

Có thể sử dụng sample google-services.json sau nếu chưa có Firebase:

{
  "project_info": {
    "project_number": "123456789012",
    "project_id": "your-project-id",
    "storage_bucket": "your-project-id.appspot.com"
  },
  "client": [
    {
      "client_info": {
        "mobilesdk_app_id": "1:123456789012:android:abcdef123456",
        "android_client_info": {
          "package_name": "com.example.your_app"
        }
      },
      "oauth_client": [
        {
          "client_id": "123456789012-abcdefg.apps.googleusercontent.com",
          "client_type": 3
        }
      ],
      "api_key": [
        {
          "current_key": "AIzaSyD-EXAMPLEKEY1234567890"
        }
      ],
      "services": {
        "appinvite_service": {
          "other_platform_oauth_client": []
        }
      }
    }
  ],
  "configuration_version": "1"
}

c. Cấu hình Android #

your_app/android/app/build.gradle.kts:

plugins {
    id("com.google.gms.google-services")
}

your_app/android/build.gradle.kts:

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.2.2")
        classpath("com.google.gms:google-services:4.4.1")
    }
}

2. Khởi tạo SDK #

Trong hàm bắt đầu vòng đời của ứng dụng, hãy khởi tạo SDK:

final config = DatabucketsEventTrackerConfigBuilder(
  apiKey: api_key,
  baseUrl: base_url,
)
  .setFlushThreshold(100) // Flush when 100 events are queued
  .setMaxEventsStored(1000) // Store max 1000 events locally
  .setFlushInterval(10000) // Flush every 10 seconds
  .setMaxFlushSizeMB(1) // Max flush payload size 1MB
  .setUserPseudoId('test-user-pseudo-id') // Tùy chọn, nếu không set sẽ tự động set user-pseudo-id theo Firebase
  .build();

DatabucketsEventTracker.initialize(config);

Các Tham số khởi tạo #

3. Class Event #

3.1. Constructor #

static Future<Event> create(String eventName) async {}

Ví dụ:

Event event = await Event.create("btn1-click-$count");

3.2. Default Params/Information #

Khi khởi tạo đối tượng Event, mặc định sẽ có các field sau:

3.3. Public methods #

• void setEventParams(Map<String, dynamic> params)
• void addEventParams(Map<String, dynamic> params)
• void addUserProperties(Map<String, dynamic> props)
• static Future<void> setCommonProperties(Map<String, dynamic> props)
• static Future<void> setFirstOpenTime(int firstOpenTimeMillis)

Ví dụ:

final installDay = DateTime.utc(2025,4,15,13,5,45).millisecondsSinceEpoch;
final firstOpenTime = DateTime.utc(2025,4,17,20,31,3).millisecondsSinceEpoch;

await Event.setFirstOpenTime(firstOpenTime);

await Event.setCommonProperties({
  'level': 1,
  'progress': 0.99,
});

Thêm params:

Event event = await Event.create("purchase_button_click");

event.setEventParams({"first_time_purchase": true, "first_time_login": false});

event.addEventParams({
  "product_id": "sku_5678",
  "price": 49.99,
  "currency": "USD",
});

event.addUserProperties({
  "membership_status": "premium",
  "last_login_days": 2,
});

// Send event
DatabucketsEventTracker.addEvent(event);

4. Dừng & Khởi động SDK #

DatabucketsEventTracker.stop();   // Tạm dừng gửi dữ liệu
DatabucketsEventTracker.resume(); // Tiếp tục gửi dữ liệu

• Khi stop: event vẫn được lưu local, chỉ chưa gửi.
• Nên gọi stop() khi app sắp terminate.

5. Các sự kiện tự động #

5.1. first_open #

• Gửi khi app lần đầu được mở sau cài đặt.

5.2. session_start #

• Gửi khi session mới bắt đầu.

5.3. app_focus_end #

• Gửi khi user thoát và chạy app ở background

5.4. session_end #

• Session kết thúc sau 30 phút kể từ event last_event_timestamp

6. Một số lưu ý khác #

Khi clear SharedPreferences, cần sao lưu & set lại các giá trị:

• first_open_time
• is_sent_first_open
• install_day
• session_number
• user_pseudo_id
• current_session_start
• last_event_timestamp
• install_time_millis
• session_duration