Avada Event Analytics

Thư viện TypeScript để log events vào BigQuery một cách dễ dàng và tái sử dụng.

Cài đặt

npm install avada-event-analytics

Hướng dẫn sử dụng

Bước 1: Tạo Dataset và Table trong BigQuery

Truy cập vào Google Cloud Console BigQuery và chạy các câu lệnh SQL sau:

Tạo Dataset:

-- Create dataset
CREATE SCHEMA `avada-review-counter.{datasetId}`
OPTIONS (
  description = "Dataset for event analytics"
);

Tạo Event Table:

-- Create event table
CREATE TABLE `{datasetId}.events` (
  shopId STRING NOT NULL,
  createdAt TIMESTAMP NOT NULL,
  type STRING NOT NULL,
  partition_date DATE
)
PARTITION BY partition_date
CLUSTER BY type, shopId
OPTIONS (
  description = "Table for storing application events"
);

Lưu ý: Thay thế {datasetId} bằng tên dataset thực tế của bạn.

Bước 2: Thêm biến môi trường GOOGLE_CLOUD_CREDENTIALS_APP_REVIEWS

Thư viện này cần Google Cloud service account credentials để kết nối với BigQuery.

Tạo file .env trong project của bạn:

GOOGLE_CLOUD_CREDENTIALS_APP_REVIEWS='{"type":"service_account","project_id":"...","private_key_id":"...","private_key":"...","client_email":"...","client_id":"...","auth_uri":"...","token_uri":"...","auth_provider_x509_cert_url":"...","client_x509_cert_url":"..."}'

Lưu ý quan trọng: Thư viện KHÔNG tự động load file .env. Bạn cần đảm bảo environment variable đã được set trước khi sử dụng thư viện.

Bước 3: Sử dụng trong code

Import và khởi tạo service:

import { createEventLogService } from "avada-event-analytics";

const eventLogService = createEventLogService({
  appId, // required - ID của ứng dụng
  datasetId, // required - BigQuery dataset ID
  tableName: "events", // optional, defaults to 'events'
  maxRetries: 3, // optional, defaults to 3
  retryDelay: 1000, // optional, defaults to 1000ms
  isDisabled: false, // optional, set to true to disable logging
});

Log single event:

await eventLogService.logEvent("shop123", "event_type");

Log event với custom data:

await eventLogService.logEvent("shop123", "custom_event", new Date(), {
  customField: "value",
  metadata: { source: "app" },
});

Log multiple events:

await eventLogService.logEvents([
  {
    shopId: "shop123",
    type: "event_type_1",
    createdAt: new Date(),
    customField: "value1",
  },
  {
    shopId: "shop456",
    type: "event_type_2",
    // createdAt defaults to now
  },
]);

Config:

• appId (required): ID của ứng dụng
• datasetId (required): BigQuery dataset ID
• tableName (optional): Table name, defaults to 'events'
• maxRetries (optional): Max retry attempts, defaults to 3
• retryDelay (optional): Initial retry delay in ms, defaults to 1000
• isDisabled (optional): Disable logging, defaults to false

logEvent(shopId, type, createdAt?, additionalData?): Promise<boolean>

Log một event đơn lẻ.

Parameters:

• shopId: Shop identifier (string | number)
• type: Event type (string)
• createdAt: Event timestamp (Date, optional, defaults to now)
• additionalData: Custom fields (Record<string, unknown>, optional)

Returns: Promise<boolean> - true if successful, false otherwise

logEvents(events: EventData[]): Promise<boolean>

Log nhiều events cùng lúc.

Parameters:

• events: Array of event objects với các field: shopId, type, createdAt?, và các custom fields

Returns: Promise<boolean> - true if successful, false otherwise