@subiz/widget-v4 4.1.203 → 4.1.205

package/api.md

@@ -7,30 +7,24 @@ Tài liệu này hướng dẫn website gửi sự kiện người dùng về Su
 API chính để gửi sự kiện là:
 
 ```js
-subiz('event', {
-	type: 'product_viewed',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		price: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'product_viewed', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	price: 1500000,
+	currency: 'VND',
 })
 ```
 
 `subiz('event', ...)` trả về `Promise`.
 
 ```js
-subiz('event', {
-	type: 'add_to_cart',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		quantity: 1,
-		price: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'add_to_cart', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	quantity: 1,
+	price: 1500000,
+	currency: 'VND',
 }).then(function (result) {
 	console.log('Đã gửi event', result)
 }).catch(function (error) {
@@ -41,32 +35,78 @@ subiz('event', {
 ## Cấu trúc event
 
 ```js
-subiz('event', {
-	type: 'event_name',
-	event_source_id: 'evt_1234',
-	payload: {},
-})
+subiz('event', 'event_name', {}, {event_source_id: 'evt_1234'})
 ```
 
-| Trường | Bắt buộc | Mô tả |
+Chữ ký:
+
+```js
+subiz('event', type, payload, options)
+```
+
+| Tham số | Bắt buộc | Mô tả |
 | --- | --- | --- |
 | `type` | Có | Tên sự kiện. Dùng `snake_case`, chỉ gồm chữ thường, số và `_`, tối đa 64 ký tự. |
 | `payload` | Không | Dữ liệu chi tiết của event. Giá trị là object JSON. |
-| `event_source_id` | Không | ID duy nhất của event ở hệ thống của website, dùng để chống gửi trùng. |
+| `options.event_source_id` | Không | ID duy nhất của event ở hệ thống của website, dùng để chống gửi trùng. |
+| `options.event_time` | Không | Thời điểm event thực sự xảy ra. Dùng ISO 8601 có timezone, ví dụ `2026-05-23T10:30:00+07:00` hoặc `2026-05-23T03:30:00Z`. Nếu không gửi, Subiz dùng thời điểm nhận event. |
 
 Ví dụ chống trùng event:
 
 ```js
-subiz('event', {
-	type: 'content_viewed',
-	event_source_id: 'evt_1234',
-	payload: {
-		url: 'https://example.com/products/pd2345',
-		title: 'Bàn phím cơ không dây',
-	},
+subiz('event', 'content_viewed', {
+	url: 'https://example.com/products/pd2345',
+	title: 'Bàn phím cơ không dây',
+}, {event_source_id: 'evt_1234'})
+```
+
+Ví dụ gửi event xảy ra trước thời điểm gửi:
+
+```js
+subiz('event', 'order_completed', {
+	order_id: 'ord_99482',
+	total: 3000000,
+	currency: 'VND',
+}, {
+	event_source_id: 'order_completed_ord_99482',
+	event_time: '2026-05-23T10:30:00+07:00',
 })
 ```
 
+## Chuẩn dữ liệu payload
+
+`payload` phải là object JSON và chỉ nên chứa dữ liệu cần thiết để phân tích, chăm sóc khách hàng hoặc cá nhân hóa trải nghiệm.
+
+Quy ước kiểu dữ liệu:
+
+| Kiểu dữ liệu | Quy ước |
+| --- | --- |
+| String | Dùng UTF-8. Tránh gửi string quá dài; với nội dung tự do như message/comment, chỉ gửi khi thực sự cần cho nghiệp vụ. |
+| Number | Dùng number JSON, không gửi số dưới dạng string nếu cần tính toán hoặc lọc theo khoảng. |
+| Boolean | Dùng `true` hoặc `false`. |
+| Date | Dùng chuỗi ngày ISO 8601 dạng `YYYY-MM-DD`, ví dụ `2026-05-23`. |
+| Date-time | Dùng ISO 8601 có timezone, ví dụ `2026-05-23T10:30:00+07:00` hoặc `2026-05-23T03:30:00Z`. Nên ưu tiên UTC (`Z`) nếu hệ thống nguồn có thể xuất UTC. |
+| Currency | Dùng mã tiền tệ ISO 4217 viết hoa, ví dụ `VND`, `USD`, `EUR`, `JPY`. |
+| Amount | Dùng số theo đơn vị tiền thực tế, không dùng minor unit. Ví dụ `1500000` cho 1.500.000 VND và `19.99` cho 19.99 USD. |
+| Object | Có thể lồng object, nhưng nên giữ cấu trúc nông và ổn định. Không gửi DOM node, class instance, function hoặc object có vòng lặp tham chiếu. |
+| Array | Dùng cho danh sách cùng kiểu dữ liệu, ví dụ `items`. Mỗi item nên có schema ổn định giữa các lần gửi. |
+| `null` | Chỉ dùng khi muốn thể hiện field có chủ đích nhưng chưa có giá trị. Nếu field không liên quan hoặc không có dữ liệu, nên bỏ field đó khỏi `payload`. |
+
+Giới hạn khuyến nghị:
+
+- `payload` nên nhỏ hơn 32 KB sau khi JSON stringify.
+- Một event không nên gửi quá 100 item trong array. Với đơn hàng lớn, gửi các field tổng hợp trên event chính và đồng bộ chi tiết bằng luồng backend riêng nếu cần.
+- Object lồng nhau không nên sâu quá 5 cấp.
+- Tên field nên dùng `snake_case`, chỉ gồm chữ thường, số và `_`.
+- Không dùng field có kiểu dữ liệu thay đổi giữa các event cùng loại, ví dụ lúc là string, lúc là object.
+
+Xử lý dữ liệu cá nhân:
+
+- Không gửi mật khẩu, OTP, token đăng nhập, refresh token, cookie, số thẻ thanh toán, CVV hoặc dữ liệu nhạy cảm không cần thiết.
+- Nếu cần gửi email hoặc số điện thoại để định danh, chỉ gửi khi website đã có quyền sử dụng dữ liệu đó.
+- Nếu chỉ cần phân tích mà không cần định danh trực tiếp, nên hash hoặc mask dữ liệu trước khi gửi. Ví dụ gửi `email_hash` thay vì `email`, hoặc `phone_masked: '******8935'` thay vì số điện thoại đầy đủ.
+- Không gửi toàn bộ địa chỉ nếu chỉ cần phân tích theo vùng; ưu tiên các field ít nhạy cảm hơn như `province`, `city`, `country`.
+
 ## Quy ước đặt tên
 
 Tên event nên mô tả hành động đã xảy ra, ở dạng quá khứ hoặc trạng thái hoàn tất.
@@ -112,14 +152,11 @@ Các field thường dùng:
 Ví dụ:
 
 ```js
-subiz('event', {
-	type: 'product_viewed',
-	payload: {
-		id: 'pd2345',
-		name: 'Bàn phím cơ không dây',
-		url: 'https://example.com/products/pd2345',
-		utm_campaign: 'summer_2026',
-	},
+subiz('event', 'product_viewed', {
+	product_id: 'pd2345',
+	name: 'Bàn phím cơ không dây',
+	url: 'https://example.com/products/pd2345',
+	utm_campaign: 'summer_2026',
 })
 ```
 
@@ -160,530 +197,478 @@ function onRouteChange(route) {
 ## Cập nhật thông tin khách hàng
 
 ```js
-subiz('event', {
-	type: 'user_updated',
-	payload: {
-		email: 'alice@example.com',
-		phone: '85345345535',
-		fullname: 'Thanh',
-	},
+subiz('event', 'user_updated', {
+	email: 'alice@example.com',
+	phone: '85345345535',
+	fullname: 'Thanh',
 })
 ```
 
 ## Thương mại điện tử
 
-Các event bên dưới là ví dụ khuyến nghị. Website có thể gửi thêm custom event bằng cùng cấu trúc `subiz('event', { type, payload })`.
+Các event bên dưới là ví dụ khuyến nghị. Website có thể gửi thêm custom event bằng cùng cấu trúc `subiz('event', type, payload)`.
 
 Các field trong ví dụ không bắt buộc toàn bộ. Website nên gửi những field mình có và giữ tên field ổn định giữa các lần gửi. Giá trị tiền tệ dùng số theo đơn vị tiền thực tế, ví dụ `{price: 1500000, currency: 'VND'}`.
 
+Quy ước ID:
+
+| Trường | Mô tả |
+| --- | --- |
+| `product_id` | ID sản phẩm. Dùng cho event xảy ra trực tiếp trên một sản phẩm và trong từng item của giỏ hàng/đơn hàng. |
+| `sku` | Mã SKU/biến thể sản phẩm nếu có. |
+| `category_id` | ID danh mục sản phẩm. Không dùng `id` để đại diện cho danh mục. |
+| `category_name` | Tên hiển thị của danh mục sản phẩm. |
+| `cart_id` | ID giỏ hàng. Không dùng `id` để đại diện cho giỏ hàng. |
+| `checkout_id` | ID phiên checkout. |
+| `order_id` | ID đơn hàng. Không dùng `id` để đại diện cho đơn hàng. |
+| `return_id` | ID yêu cầu đổi trả. |
+| `refund_id` | ID giao dịch hoàn tiền. |
+
+Quy ước tiền tệ:
+
+| Trường | Mô tả |
+| --- | --- |
+| `price` | Đơn giá của một sản phẩm hoặc item. |
+| `current_price` | Giá hiện tại của sản phẩm tại thời điểm event xảy ra. |
+| `target_price` | Giá mong muốn khi user đăng ký nhận thông báo giảm giá. |
+| `total` | Tổng tiền của giỏ hàng, checkout, đơn hàng, thanh toán hoặc hóa đơn. |
+| `discount_amount` | Số tiền giảm giá. |
+| `shipping_fee` | Phí vận chuyển. |
+| `refund_amount` | Số tiền hoàn lại. |
+| `estimated_value` | Giá trị ước tính của deal/cơ hội bán hàng. |
+| `renewal_value` | Giá trị hợp đồng khi gia hạn. |
+| `mrr_delta` | Chênh lệch doanh thu định kỳ hàng tháng sau khi nâng/hạ cấp hoặc thêm seat. |
+
 Nên ưu tiên các event có thể dùng trực tiếp cho marketing segmentation, funnel và recommendation:
 
 | Câu hỏi marketing | Event nên dùng |
 | --- | --- |
 | Sản phẩm nào đang hot trend? | `product_viewed`, `product_searched`, `add_to_wishlist`, `add_to_cart`, `order_completed` |
 | User quan tâm sản phẩm nào nhưng chưa mua? | `product_viewed`, `add_to_wishlist`, `add_to_cart`, `checkout_started`, `order_completed` |
-| User bỏ giỏ hàng? | `add_to_cart`, `checkout_started`, `payment_completed`, `order_completed` |
+| User bỏ giỏ hàng? | `add_to_cart`, `checkout_started`; loại trừ user đã có `payment_completed` hoặc `order_completed` cùng `cart_id`/`checkout_id` |
 | Sản phẩm nào có nhu cầu cao nhưng chuyển đổi thấp? | `product_viewed`, `product_inquired`, `add_to_cart`, `order_completed` |
 | Sản phẩm nào đang thiếu hàng nhưng vẫn có nhu cầu? | `back_in_stock_subscribed`, `product_inquired`, `product_viewed` |
 | User nào nhạy cảm với giá? | `price_drop_subscribed`, `coupon_applied`, `add_to_wishlist` |
 | Campaign/coupon nào tạo doanh thu? | `coupon_applied`, `order_completed` |
 | Sản phẩm nào hay bị trả/hủy? | `order_cancelled`, `order_refunded`, `return_requested` |
 
-Để query marketing dễ hơn, các event liên quan đến một sản phẩm nên gửi ổn định các field `id`, `sku`, `name`, `category`, `brand` trong `payload`. Với `order_completed`, luôn gửi danh sách `items` và mỗi item nên có `id`, `sku`, `name`, `category`, `quantity`, `price`.
+Để query marketing dễ hơn, các event liên quan đến một sản phẩm nên gửi ổn định các field `product_id`, `sku`, `name`, `category`, `brand` trong `payload`. Với `order_completed`, luôn gửi danh sách `items` và mỗi item nên có `product_id`, `sku`, `name`, `category`, `quantity`, `price`.
 
 ### Xem sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_viewed',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		category: 'electronics',
-		brand: 'Keychron',
-		price: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'product_viewed', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	price: 1500000,
+	currency: 'VND',
 })
 ```
 
 ### Xem danh mục sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_category_viewed',
-	payload: {
-		id: 'cat_electronics',
-		name: 'Electronics',
-		url: 'https://example.com/categories/electronics',
-	},
+subiz('event', 'product_category_viewed', {
+	category_id: 'cat_electronics',
+	category_name: 'Electronics',
+	url: 'https://example.com/categories/electronics',
 })
 ```
 
 ### Xem danh sách sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_list_viewed',
-	payload: {
-		list_id: 'homepage_featured',
-		list_name: 'Sản phẩm nổi bật',
-		category: 'electronics',
-		items: [
-			{id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', position: 1, price: 1500000},
-			{id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', position: 2, price: 450000},
-		],
-		currency: 'VND',
-	},
+subiz('event', 'product_list_viewed', {
+	list_id: 'homepage_featured',
+	list_name: 'Sản phẩm nổi bật',
+	category: 'electronics',
+	items: [
+		{product_id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', position: 1, price: 1500000},
+		{product_id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', position: 2, price: 450000},
+	],
+	currency: 'VND',
 })
 ```
 
 ### Tìm kiếm sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_searched',
-	payload: {
-		keyword: 'bàn phím cơ không dây',
-		category_filter: 'electronics',
-		sort_by: 'price_asc',
-	},
+subiz('event', 'product_searched', {
+	keyword: 'bàn phím cơ không dây',
+	category_filter: 'electronics',
+	sort_by: 'price_asc',
 })
 ```
 
 ### Lọc hoặc sắp xếp sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_list_filtered',
-	payload: {
-		category: 'electronics',
-		filters: {
-			brand: ['logitech', 'keychron'],
-			price_min: 500000,
-			price_max: 2000000,
-		},
-		sort_by: 'price_asc',
-		result_count: 24,
+subiz('event', 'product_list_filtered', {
+	category: 'electronics',
+	filters: {
+		brand: ['logitech', 'keychron'],
+		price_min: 500000,
+		price_max: 2000000,
 	},
+	sort_by: 'price_asc',
+	result_count: 24,
 })
 ```
 
 ### Hỏi về sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_inquired',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		channel: 'zalo_oa',
-		inquiry_type: 'stock_check',
-		message: 'Bàn phím này còn sẵn hàng ở kho không shop?',
-		has_agent_replied: false,
-		agent_id: null,
-	},
+subiz('event', 'product_inquired', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	channel: 'zalo_oa',
+	inquiry_type: 'stock_check',
+	message: 'Bàn phím này còn sẵn hàng ở kho không shop?',
+	has_agent_replied: false,
+	agent_id: null,
 })
 ```
 
 ### Đăng ký nhận thông báo còn hàng
 
 ```js
-subiz('event', {
-	type: 'back_in_stock_subscribed',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		category: 'electronics',
-		brand: 'Keychron',
-		price: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'back_in_stock_subscribed', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	price: 1500000,
+	currency: 'VND',
 })
 ```
 
 ### Đăng ký nhận thông báo giảm giá
 
 ```js
-subiz('event', {
-	type: 'price_drop_subscribed',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		category: 'electronics',
-		brand: 'Keychron',
-		current_price: 1500000,
-		target_price: 1200000,
-		currency: 'VND',
-	},
+subiz('event', 'price_drop_subscribed', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	current_price: 1500000,
+	target_price: 1200000,
+	currency: 'VND',
 })
 ```
 
 ### Thêm vào giỏ hàng
 
 ```js
-subiz('event', {
-	type: 'add_to_cart',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		price: 1500000,
-		currency: 'VND',
-		quantity: 1,
-		category: 'electronics',
-		brand: 'Keychron',
-	},
+subiz('event', 'add_to_cart', {
+	cart_id: 'cart_12345',
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	price: 1500000,
+	currency: 'VND',
+	quantity: 1,
+	category: 'electronics',
+	brand: 'Keychron',
 })
 ```
 
 ### Xem giỏ hàng
 
 ```js
-subiz('event', {
-	type: 'cart_viewed',
-	payload: {
-		id: 'cart_12345',
-		total: 3000000,
-		currency: 'VND',
-		cart_size: 2,
-		items: [
-			{id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
-			{id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', quantity: 1, price: 1500000},
-		],
-	},
+subiz('event', 'cart_viewed', {
+	cart_id: 'cart_12345',
+	total: 3000000,
+	currency: 'VND',
+	cart_size: 2,
+	items: [
+		{product_id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
+		{product_id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', quantity: 1, price: 1500000},
+	],
 })
 ```
 
 ### Xóa khỏi giỏ hàng
 
 ```js
-subiz('event', {
-	type: 'remove_from_cart',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		price: 1500000,
-		currency: 'VND',
-		quantity: 1,
-		category: 'electronics',
-	},
+subiz('event', 'remove_from_cart', {
+	cart_id: 'cart_12345',
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	price: 1500000,
+	currency: 'VND',
+	quantity: 1,
+	category: 'electronics',
+	brand: 'Keychron',
 })
 ```
 
 ### Thêm vào danh sách yêu thích
 
 ```js
-subiz('event', {
-	type: 'add_to_wishlist',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		price: 1500000,
-		currency: 'VND',
-		quantity: 1,
-		category: 'electronics',
-		brand: 'Keychron',
-	},
+subiz('event', 'add_to_wishlist', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	price: 1500000,
+	currency: 'VND',
+	category: 'electronics',
+	brand: 'Keychron',
 })
 ```
 
 ### Xóa khỏi danh sách yêu thích
 
 ```js
-subiz('event', {
-	type: 'remove_from_wishlist',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		price: 1500000,
-		currency: 'VND',
-		category: 'electronics',
-	},
+subiz('event', 'remove_from_wishlist', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	price: 1500000,
+	currency: 'VND',
+	category: 'electronics',
+	brand: 'Keychron',
 })
 ```
 
 ### Áp dụng mã giảm giá
 
 ```js
-subiz('event', {
-	type: 'coupon_applied',
-	payload: {
-		coupon_code: 'SUMMER2026',
-		discount_amount: 150000,
-		currency: 'VND',
-		cart_id: 'cart_12345',
-	},
+subiz('event', 'coupon_applied', {
+	coupon_code: 'SUMMER2026',
+	discount_amount: 150000,
+	currency: 'VND',
+	cart_id: 'cart_12345',
 })
 ```
 
 ### Xóa mã giảm giá
 
 ```js
-subiz('event', {
-	type: 'coupon_removed',
-	payload: {
-		coupon_code: 'SUMMER2026',
-		cart_id: 'cart_12345',
-	},
+subiz('event', 'coupon_removed', {
+	coupon_code: 'SUMMER2026',
+	cart_id: 'cart_12345',
 })
 ```
 
 ### Bắt đầu thanh toán
 
 ```js
-subiz('event', {
-	type: 'checkout_started',
-	payload: {
-		checkout_id: 'chk_556677',
-		total_value: 3000000,
-		currency: 'VND',
-		cart_size: 2,
-	},
+subiz('event', 'checkout_started', {
+	checkout_id: 'chk_556677',
+	cart_id: 'cart_12345',
+	total: 3000000,
+	currency: 'VND',
+	cart_size: 2,
 })
 ```
 
 ### Thêm thông tin giao hàng
 
 ```js
-subiz('event', {
-	type: 'shipping_info_added',
-	payload: {
-		checkout_id: 'chk_556677',
-		shipping_method: 'standard',
-		shipping_fee: 30000,
-		currency: 'VND',
-	},
+subiz('event', 'shipping_info_added', {
+	checkout_id: 'chk_556677',
+	shipping_method: 'standard',
+	shipping_fee: 30000,
+	currency: 'VND',
 })
 ```
 
 ### Thêm thông tin thanh toán
 
 ```js
-subiz('event', {
-	type: 'payment_info_added',
-	payload: {
-		checkout_id: 'chk_556677',
-		payment_method: 'credit_card',
-		total_value: 3000000,
-		currency: 'VND',
-	},
+subiz('event', 'payment_info_added', {
+	checkout_id: 'chk_556677',
+	payment_method: 'credit_card',
+	total: 3000000,
+	currency: 'VND',
 })
 ```
 
 ### Khởi tạo thanh toán
 
 ```js
-subiz('event', {
-	type: 'payment_initiated',
-	payload: {
-		transaction_id: 'txn_12345',
-		order_id: 'ord_99482',
-		amount: 3000000,
-		currency: 'VND',
-	},
+subiz('event', 'payment_initiated', {
+	transaction_id: 'txn_12345',
+	checkout_id: 'chk_556677',
+	cart_id: 'cart_12345',
+	total: 3000000,
+	currency: 'VND',
 })
 ```
 
+Nếu hệ thống đã tạo đơn trước bước thanh toán, có thể gửi thêm `order_id`. Nếu hệ thống chỉ tạo đơn sau khi thanh toán thành công, gửi `checkout_id` và `cart_id` trước, sau đó bổ sung `order_id` ở `payment_completed` hoặc `order_completed`.
+
 ### Thanh toán thất bại
 
 ```js
-subiz('event', {
-	type: 'payment_failed',
-	payload: {
-		transaction_id: 'txn_12345',
-		order_id: 'ord_99482',
-		amount: 3000000,
-		currency: 'VND',
-		error_code: 'card_declined',
-		error_message: 'Thẻ bị từ chối',
-	},
+subiz('event', 'payment_failed', {
+	transaction_id: 'txn_12345',
+	checkout_id: 'chk_556677',
+	cart_id: 'cart_12345',
+	order_id: 'ord_99482',
+	total: 3000000,
+	currency: 'VND',
+	error_code: 'card_declined',
+	error_message: 'Thẻ bị từ chối',
 })
 ```
 
 ### Hoàn tất thanh toán
 
 ```js
-subiz('event', {
-	type: 'payment_completed',
-	payload: {
-		transaction_id: 'txn_12345',
-		order_id: 'ord_99482',
-		amount: 3000000,
-		currency: 'VND',
-		status: 'success',
-	},
+subiz('event', 'payment_completed', {
+	transaction_id: 'txn_12345',
+	checkout_id: 'chk_556677',
+	cart_id: 'cart_12345',
+	order_id: 'ord_99482',
+	total: 3000000,
+	currency: 'VND',
+	status: 'success',
 })
 ```
 
 ### Hoàn tất đơn hàng
 
 ```js
-subiz('event', {
-	type: 'order_completed',
-	event_source_id: 'order_completed_ord_99482',
-	payload: {
-		id: 'ord_99482',
-		total: 3000000,
-		shipping_fee: 30000,
-		discount_amount: 0,
-		currency: 'VND',
-		payment_method: 'credit_card',
-		items: [
-			{id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
-			{id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', quantity: 1, price: 1500000},
-		],
-	},
-})
+subiz('event', 'order_completed', {
+	order_id: 'ord_99482',
+	checkout_id: 'chk_556677',
+	cart_id: 'cart_12345',
+	total: 3000000,
+	shipping_fee: 30000,
+	discount_amount: 0,
+	currency: 'VND',
+	payment_method: 'credit_card',
+	items: [
+		{product_id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
+		{product_id: 'pd9876', sku: 's1234', name: 'Chuột không dây', category: 'electronics', quantity: 1, price: 1500000},
+	],
+}, {event_source_id: 'order_completed_ord_99482'})
 ```
 
 ### Đặt hàng thất bại
 
 ```js
-subiz('event', {
-	type: 'order_failed',
-	payload: {
-		checkout_id: 'chk_556677',
-		error_code: 'out_of_stock',
-		error_message: 'Một sản phẩm trong giỏ hàng đã hết hàng',
-		total_value: 3000000,
-		currency: 'VND',
-	},
+subiz('event', 'order_failed', {
+	checkout_id: 'chk_556677',
+	error_code: 'out_of_stock',
+	error_message: 'Một sản phẩm trong giỏ hàng đã hết hàng',
+	total: 3000000,
+	currency: 'VND',
 })
 ```
 
 ### Xác nhận đơn hàng
 
 ```js
-subiz('event', {
-	type: 'order_confirmed',
-	payload: {
-		id: 'ord_99482',
-		expected_delivery_date: '2026-05-15',
-		status: 'confirmed',
-	},
+subiz('event', 'order_confirmed', {
+	order_id: 'ord_99482',
+	expected_delivery_date: '2026-05-15',
+	status: 'confirmed',
 })
 ```
 
 ### Hủy đơn hàng
 
 ```js
-subiz('event', {
-	type: 'order_cancelled',
-	payload: {
-		id: 'ord_99482',
-		cancel_reason: 'customer_changed_mind',
-	},
+subiz('event', 'order_cancelled', {
+	order_id: 'ord_99482',
+	cancel_reason: 'customer_changed_mind',
 })
 ```
 
 ### Hoàn tiền đơn hàng
 
 ```js
-subiz('event', {
-	type: 'order_refunded',
-	event_source_id: 'order_refunded_ord_99482',
-	payload: {
-		id: 'ord_99482',
-		refund_id: 'rf_12345',
-		refund_amount: 3000000,
-		reason: 'customer_returned_items',
-		currency: 'VND',
-	},
-})
+subiz('event', 'order_refunded', {
+	order_id: 'ord_99482',
+	refund_id: 'rf_12345',
+	refund_amount: 3000000,
+	reason: 'customer_returned_items',
+	currency: 'VND',
+}, {event_source_id: 'order_refunded_rf_12345'})
 ```
 
 ### Yêu cầu đổi trả
 
 ```js
-subiz('event', {
-	type: 'return_requested',
-	payload: {
-		id: 'ord_99482',
-		return_id: 'ret_12345',
-		reason: 'wrong_size',
-		items: [
-			{id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
-		],
-		currency: 'VND',
-	},
+subiz('event', 'return_requested', {
+	order_id: 'ord_99482',
+	return_id: 'ret_12345',
+	reason: 'wrong_size',
+	items: [
+		{product_id: 'pd2345', sku: 's5345', name: 'Bàn phím cơ không dây', category: 'electronics', quantity: 1, price: 1500000},
+	],
+	currency: 'VND',
 })
 ```
 
 ### Hoàn tất đổi trả
 
 ```js
-subiz('event', {
-	type: 'return_completed',
-	payload: {
-		id: 'ord_99482',
-		return_id: 'ret_12345',
-		refund_amount: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'return_completed', {
+	order_id: 'ord_99482',
+	return_id: 'ret_12345',
+	refund_amount: 1500000,
+	currency: 'VND',
 })
 ```
 
 ### Bắt đầu giao hàng
 
 ```js
-subiz('event', {
-	type: 'order_shipped',
-	payload: {
-		id: 'ord_99482',
-		shipping_method: 'standard',
-		tracking_code: 'VNPOST_88374',
-		estimated_delivery_date: '2026-05-15',
-	},
+subiz('event', 'order_shipped', {
+	order_id: 'ord_99482',
+	shipping_method: 'standard',
+	tracking_code: 'VNPOST_88374',
+	estimated_delivery_date: '2026-05-15',
 })
 ```
 
 ### Giao hàng thành công
 
 ```js
-subiz('event', {
-	type: 'order_delivered',
-	payload: {
-		id: 'ord_99482',
-		tracking_code: 'VNPOST_88374',
-	},
+subiz('event', 'order_delivered', {
+	order_id: 'ord_99482',
+	tracking_code: 'VNPOST_88374',
 })
 ```
 
 ### Đánh giá sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_reviewed',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		rating: 5,
-		review_id: 'rv_12345',
-		has_comment: true,
-	},
+subiz('event', 'product_reviewed', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	rating: 5,
+	review_id: 'rv_12345',
+	has_comment: true,
 })
 ```
 
 ### Chia sẻ sản phẩm
 
 ```js
-subiz('event', {
-	type: 'product_shared',
-	payload: {
-		id: 'pd2345',
-		sku: 's5345',
-		name: 'Bàn phím cơ không dây',
-		channel: 'facebook',
-		url: 'https://example.com/products/pd2345',
-	},
+subiz('event', 'product_shared', {
+	product_id: 'pd2345',
+	sku: 's5345',
+	name: 'Bàn phím cơ không dây',
+	category: 'electronics',
+	brand: 'Keychron',
+	channel: 'facebook',
+	url: 'https://example.com/products/pd2345',
 })
 ```
 
@@ -692,78 +677,121 @@ subiz('event', {
 ### Đặt lịch dịch vụ
 
 ```js
-subiz('event', {
-	type: 'service_booked',
-	payload: {
-		booking_id: 'bk_77362',
-		service_id: 'srv_massage_01',
-		scheduled_time: '2026-05-20T14:00:00Z',
-	},
+subiz('event', 'service_booked', {
+	booking_id: 'bk_77362',
+	service_id: 'srv_massage_01',
+	scheduled_time: '2026-05-20T14:00:00Z',
 })
 ```
 
 ### Hoàn thành dịch vụ
 
 ```js
-subiz('event', {
-	type: 'service_completed',
-	payload: {
-		booking_id: 'bk_77362',
-		service_id: 'srv_massage_01',
-		actual_duration_minutes: 65,
-	},
+subiz('event', 'service_completed', {
+	booking_id: 'bk_77362',
+	service_id: 'srv_massage_01',
+	actual_duration_minutes: 65,
 })
 ```
 
 ## Tương tác
 
-### Gửi form
+### Reaction
+
+Dùng `reacted` khi người dùng thả hoặc gỡ reaction trên bất kỳ đối tượng nào: sản phẩm trên website, bài post, comment, tin nhắn, video, reel, story hoặc nội dung khác trên các kênh như Facebook, Instagram, WhatsApp, TikTok, Telegram.
+
+| Trường | Bắt buộc | Mô tả |
+| --- | --- | --- |
+| `target_type` | Có | Loại đối tượng được reaction, ví dụ `product`, `post`, `comment`, `message`, `video`, `reel`, `story`. |
+| `reaction` | Có | Loại reaction: `like`, `love`, `wow`, `haha`, `sorry`, `angry`, emoji như `👍`, `❤️`, hoặc giá trị reaction khác tùy nền tảng. |
+| `action` | Không | Hành động với reaction: `add` (default) khi thả reaction, `remove` khi gỡ reaction. Nên dùng `action: 'remove'` thay vì `reaction: 'unlike'` nếu biết reaction cũ là gì. |
+| `channel` | Không | Kênh xảy ra reaction, ví dụ `website`, `facebook`, `instagram`, `whatsapp`, `tiktok`, `telegram`. |
+
+Ví dụ khách like sản phẩm trên website:
 
 ```js
-subiz('event', {
-	type: 'form_submitted',
-	payload: {
-		form_id: 'frm_newsletter_01',
-		form_name: 'Đăng ký nhận bản tin',
-		campaign_id: 'camp_summer_2026',
-	},
+subiz('event', 'reacted', {
+	target_type: 'product',
+	reaction: 'like',
+	action: 'add',
+	channel: 'website',
+	product_id: 'pd2345',
+	sku: 's5345',
 })
 ```
 
-### Đăng nhập và đăng xuất
+Ví dụ khách gỡ like sản phẩm:
+
+```js
+subiz('event', 'reacted', {
+	target_type: 'product',
+	reaction: 'like',
+	action: 'remove',
+	channel: 'website',
+	product_id: 'pd2345',
+	sku: 's5345',
+})
+```
+
+Ví dụ reaction trên post Facebook:
+
+```js
+subiz('event', 'reacted', {
+	target_type: 'facebook_post',
+	reaction: 'love',
+	action: 'add',
+	channel: 'facebook',
+	post_id: '102345678901234',
+	page_id: '987654321012345',
+})
+```
+
+Ví dụ reaction trên tin nhắn Telegram:
 
 ```js
-subiz('event', {
-	type: 'login',
+subiz('event', 'reacted', {
+	target_type: 'message',
+	reaction: 'like',
+	action: 'add',
+	channel: 'telegram',
+	message_id: 'msg_778899',
 })
+```
 
-subiz('event', {
-	type: 'logout',
+### Gửi form
+
+```js
+subiz('event', 'form_submitted', {
+	form_id: 'frm_newsletter_01',
+	form_name: 'Đăng ký nhận bản tin',
+	campaign_id: 'camp_summer_2026',
 })
 ```
 
+### Đăng nhập và đăng xuất
+
+```js
+subiz('event', 'login')
+
+subiz('event', 'logout')
+```
+
 ### Giới thiệu khách hàng mới
 
 ```js
-subiz('event', {
-	type: 'customer_referred',
-	payload: {
-		referral_code: 'THANH2026',
-		referred_user_id: 'usr_new_999',
-	},
+subiz('event', 'customer_referred', {
+	referral_code: 'THANH2026',
+	referred_user_id: 'usr_new_999',
 })
 ```
 
 ### Cập nhật khách hàng thân thiết
 
 ```js
-subiz('event', {
-	type: 'customer_loyalty_updated',
-	payload: {
-		action: 'earn',
-		points: 500,
-		current_tier: 'platinum',
-	},
+subiz('event', 'customer_loyalty_updated', {
+	action: 'earn',
+	points: 500,
+	current_tier: 'platinum',
 })
 ```
 
@@ -787,441 +815,363 @@ Nên giữ ổn định các field định danh như `company_id`, `company_name
 ### Tạo lead
 
 ```js
-subiz('event', {
-	type: 'lead_created',
-	payload: {
-		lead_id: 'lead_10293',
-		contact_id: 'ct_10293',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		email: 'alice@techcorp.vn',
-		phone: '0987654321',
-		source: 'landing_page_summer',
-		campaign_id: 'camp_summer_2026',
-		industry: 'software',
-		company_size: '51-200',
-	},
+subiz('event', 'lead_created', {
+	lead_id: 'lead_10293',
+	contact_id: 'ct_10293',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	email: 'alice@techcorp.vn',
+	phone: '0987654321',
+	source: 'landing_page_summer',
+	campaign_id: 'camp_summer_2026',
+	industry: 'software',
+	company_size: '51-200',
 })
 ```
 
 ### Đăng ký tài khoản
 
 ```js
-subiz('event', {
-	type: 'customer_registered',
-	payload: {
-		customer_id: 'usr_new_10293',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		registration_method: 'google',
-		source: 'landing_page_summer',
-		is_verified: false,
-	},
+subiz('event', 'customer_registered', {
+	customer_id: 'usr_new_10293',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	registration_method: 'google',
+	source: 'landing_page_summer',
+	is_verified: false,
 })
 ```
 
 ### Xem trang giá
 
 ```js
-subiz('event', {
-	type: 'pricing_viewed',
-	payload: {
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		plan: 'business',
-		billing_cycle: 'annual',
-		url: 'https://example.com/pricing',
-	},
+subiz('event', 'pricing_viewed', {
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	plan: 'business',
+	billing_cycle: 'annual',
+	url: 'https://example.com/pricing',
 })
 ```
 
 ### Bắt đầu dùng thử
 
 ```js
-subiz('event', {
-	type: 'trial_started',
-	payload: {
-		trial_id: 'trial_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		plan: 'business',
-		start_date: '2026-05-12',
-		end_date: '2026-05-26',
-		source: 'pricing_page',
-	},
+subiz('event', 'trial_started', {
+	trial_id: 'trial_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	plan: 'business',
+	start_date: '2026-05-12',
+	end_date: '2026-05-26',
+	source: 'pricing_page',
 })
 ```
 
 ### Yêu cầu demo
 
 ```js
-subiz('event', {
-	type: 'demo_requested',
-	payload: {
-		demo_id: 'demo_12345',
-		contact_id: 'ct_10293',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		plan_interest: 'business',
-		estimated_users: 50,
-		preferred_time: '2026-05-20T14:00:00Z',
-	},
+subiz('event', 'demo_requested', {
+	demo_id: 'demo_12345',
+	contact_id: 'ct_10293',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	plan_interest: 'business',
+	estimated_users: 50,
+	preferred_time: '2026-05-20T14:00:00Z',
 })
 ```
 
 ### Đặt lịch họp
 
 ```js
-subiz('event', {
-	type: 'meeting_booked',
-	payload: {
-		meeting_id: 'mt_12345',
-		contact_id: 'ct_10293',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		meeting_type: 'sales_demo',
-		scheduled_time: '2026-05-20T14:00:00Z',
-		owner_id: 'sale_001',
-	},
+subiz('event', 'meeting_booked', {
+	meeting_id: 'mt_12345',
+	contact_id: 'ct_10293',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	meeting_type: 'sales_demo',
+	scheduled_time: '2026-05-20T14:00:00Z',
+	owner_id: 'sale_001',
 })
 ```
 
 ### Hoàn thành cuộc họp
 
 ```js
-subiz('event', {
-	type: 'meeting_completed',
-	payload: {
-		meeting_id: 'mt_12345',
-		contact_id: 'ct_10293',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		meeting_type: 'sales_demo',
-		outcome: 'qualified',
-		next_step: 'send_proposal',
-	},
+subiz('event', 'meeting_completed', {
+	meeting_id: 'mt_12345',
+	contact_id: 'ct_10293',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	meeting_type: 'sales_demo',
+	outcome: 'qualified',
+	next_step: 'send_proposal',
 })
 ```
 
 ### Tạo deal
 
 ```js
-subiz('event', {
-	type: 'deal_created',
-	payload: {
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		stage: 'qualified',
-		estimated_value: 50000000,
-		currency: 'VND',
-		owner_id: 'sale_001',
-		source: 'demo_requested',
-	},
+subiz('event', 'deal_created', {
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	stage: 'qualified',
+	estimated_value: 50000000,
+	currency: 'VND',
+	owner_id: 'sale_001',
+	source: 'demo_requested',
 })
 ```
 
 ### Đổi trạng thái deal
 
 ```js
-subiz('event', {
-	type: 'deal_stage_changed',
-	payload: {
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		from_stage: 'qualified',
-		to_stage: 'proposal_sent',
-		estimated_value: 50000000,
-		currency: 'VND',
-		owner_id: 'sale_001',
-	},
+subiz('event', 'deal_stage_changed', {
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	from_stage: 'qualified',
+	to_stage: 'proposal_sent',
+	estimated_value: 50000000,
+	currency: 'VND',
+	owner_id: 'sale_001',
 })
 ```
 
 ### Gửi proposal
 
 ```js
-subiz('event', {
-	type: 'proposal_sent',
-	payload: {
-		proposal_id: 'pr_2026_05_01',
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		total_value: 48000000,
-		currency: 'VND',
-		valid_until: '2026-06-01',
-	},
+subiz('event', 'proposal_sent', {
+	proposal_id: 'pr_2026_05_01',
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	total: 48000000,
+	currency: 'VND',
+	valid_until: '2026-06-01',
 })
 ```
 
 ### Yêu cầu báo giá
 
 ```js
-subiz('event', {
-	type: 'quote_requested',
-	payload: {
-		quote_id: 'qt_2026_05_01',
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		estimated_budget: 50000000,
-		currency: 'VND',
-	},
+subiz('event', 'quote_requested', {
+	quote_id: 'qt_2026_05_01',
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	estimated_budget: 50000000,
+	currency: 'VND',
 })
 ```
 
 ### Chấp nhận báo giá
 
 ```js
-subiz('event', {
-	type: 'quote_accepted',
-	payload: {
-		quote_id: 'qt_2026_05_01',
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		total_value: 48000000,
-		currency: 'VND',
-	},
+subiz('event', 'quote_accepted', {
+	quote_id: 'qt_2026_05_01',
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	total: 48000000,
+	currency: 'VND',
 })
 ```
 
 ### Từ chối báo giá
 
 ```js
-subiz('event', {
-	type: 'quote_rejected',
-	payload: {
-		quote_id: 'qt_2026_05_01',
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		reason: 'price_too_high',
-		total_value: 48000000,
-		currency: 'VND',
-	},
+subiz('event', 'quote_rejected', {
+	quote_id: 'qt_2026_05_01',
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	reason: 'price_too_high',
+	total: 48000000,
+	currency: 'VND',
 })
 ```
 
 ### Ký hợp đồng
 
 ```js
-subiz('event', {
-	type: 'contract_signed',
-	event_source_id: 'contract_signed_ctr_09876',
-	payload: {
-		contract_id: 'ctr_09876',
-		deal_id: 'deal_556677',
-		quote_id: 'qt_2026_05_01',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		total_value: 48000000,
-		plan: 'business',
-		billing_cycle: 'annual',
-		start_date: '2026-06-01',
-		end_date: '2027-05-31',
-		currency: 'VND',
-	},
-})
+subiz('event', 'contract_signed', {
+	contract_id: 'ctr_09876',
+	deal_id: 'deal_556677',
+	quote_id: 'qt_2026_05_01',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	total: 48000000,
+	plan: 'business',
+	billing_cycle: 'annual',
+	start_date: '2026-06-01',
+	end_date: '2027-05-31',
+	currency: 'VND',
+}, {event_source_id: 'contract_signed_ctr_09876'})
 ```
 
 ### Hủy hợp đồng
 
 ```js
-subiz('event', {
-	type: 'contract_cancelled',
-	payload: {
-		contract_id: 'ctr_09876',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		cancel_reason: 'budget_cut',
-		cancelled_at: '2026-10-01',
-		remaining_value: 24000000,
-		currency: 'VND',
-	},
+subiz('event', 'contract_cancelled', {
+	contract_id: 'ctr_09876',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	cancel_reason: 'budget_cut',
+	cancelled_at: '2026-10-01',
+	remaining_value: 24000000,
+	currency: 'VND',
 })
 ```
 
 ### Mất deal
 
 ```js
-subiz('event', {
-	type: 'deal_lost',
-	payload: {
-		deal_id: 'deal_556677',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		lost_reason: 'chose_competitor',
-		estimated_value: 50000000,
-		currency: 'VND',
-	},
+subiz('event', 'deal_lost', {
+	deal_id: 'deal_556677',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	lost_reason: 'chose_competitor',
+	estimated_value: 50000000,
+	currency: 'VND',
 })
 ```
 
 ### Hoàn thành onboarding
 
 ```js
-subiz('event', {
-	type: 'onboarding_completed',
-	payload: {
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		plan: 'business',
-		onboarding_duration_days: 14,
-		owner_id: 'cs_001',
-	},
+subiz('event', 'onboarding_completed', {
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	plan: 'business',
+	onboarding_duration_days: 14,
+	owner_id: 'cs_001',
 })
 ```
 
 ### Kích hoạt tính năng quan trọng
 
 ```js
-subiz('event', {
-	type: 'feature_activated',
-	payload: {
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		feature_key: 'automation_workflow',
-		plan: 'business',
-		activated_by: 'usr_10293',
-	},
+subiz('event', 'feature_activated', {
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	feature_key: 'automation_workflow',
+	plan: 'business',
+	activated_by: 'usr_10293',
 })
 ```
 
 ### Nâng cấp gói
 
 ```js
-subiz('event', {
-	type: 'subscription_upgraded',
-	payload: {
-		subscription_id: 'sub_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		from_plan: 'starter',
-		to_plan: 'business',
-		mrr_delta: 3000000,
-		currency: 'VND',
-	},
+subiz('event', 'subscription_upgraded', {
+	subscription_id: 'sub_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	from_plan: 'starter',
+	to_plan: 'business',
+	mrr_delta: 3000000,
+	currency: 'VND',
 })
 ```
 
 ### Hạ cấp gói
 
 ```js
-subiz('event', {
-	type: 'subscription_downgraded',
-	payload: {
-		subscription_id: 'sub_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		from_plan: 'business',
-		to_plan: 'starter',
-		mrr_delta: -3000000,
-		reason: 'budget_cut',
-		currency: 'VND',
-	},
+subiz('event', 'subscription_downgraded', {
+	subscription_id: 'sub_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	from_plan: 'business',
+	to_plan: 'starter',
+	mrr_delta: -3000000,
+	reason: 'budget_cut',
+	currency: 'VND',
 })
 ```
 
 ### Thêm người dùng vào tài khoản
 
 ```js
-subiz('event', {
-	type: 'seat_added',
-	payload: {
-		subscription_id: 'sub_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		seat_count: 5,
-		mrr_delta: 1500000,
-		currency: 'VND',
-	},
+subiz('event', 'seat_added', {
+	subscription_id: 'sub_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	seat_delta: 5,
+	total_seats: 25,
+	mrr_delta: 1500000,
+	currency: 'VND',
 })
 ```
 
+Trong đó `seat_delta` là số seat được thêm ở lần thay đổi này, còn `total_seats` là tổng số seat sau thay đổi.
+
 ### Bắt đầu gia hạn
 
 ```js
-subiz('event', {
-	type: 'renewal_started',
-	payload: {
-		contract_id: 'ctr_09876',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		renewal_date: '2027-05-31',
-		current_value: 48000000,
-		currency: 'VND',
-	},
+subiz('event', 'renewal_started', {
+	contract_id: 'ctr_09876',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	renewal_date: '2027-05-31',
+	current_value: 48000000,
+	currency: 'VND',
 })
 ```
 
 ### Gia hạn thành công
 
 ```js
-subiz('event', {
-	type: 'renewal_completed',
-	event_source_id: 'renewal_completed_ctr_09876_2027',
-	payload: {
-		contract_id: 'ctr_09876',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		renewal_value: 60000000,
-		start_date: '2027-06-01',
-		end_date: '2028-05-31',
-		currency: 'VND',
-	},
-})
+subiz('event', 'renewal_completed', {
+	contract_id: 'ctr_09876',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	renewal_value: 60000000,
+	start_date: '2027-06-01',
+	end_date: '2028-05-31',
+	currency: 'VND',
+}, {event_source_id: 'renewal_completed_ctr_09876_2027'})
 ```
 
 ### Thanh toán hóa đơn thành công
 
 ```js
-subiz('event', {
-	type: 'invoice_paid',
-	event_source_id: 'invoice_paid_inv_12345',
-	payload: {
-		invoice_id: 'inv_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		amount: 48000000,
-		billing_cycle: 'annual',
-		currency: 'VND',
-	},
-})
+subiz('event', 'invoice_paid', {
+	invoice_id: 'inv_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	total: 48000000,
+	billing_cycle: 'annual',
+	currency: 'VND',
+}, {event_source_id: 'invoice_paid_inv_12345'})
 ```
 
 ### Thanh toán hóa đơn thất bại
 
 ```js
-subiz('event', {
-	type: 'invoice_failed',
-	payload: {
-		invoice_id: 'inv_12345',
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		amount: 48000000,
-		error_code: 'card_declined',
-		currency: 'VND',
-	},
+subiz('event', 'invoice_failed', {
+	invoice_id: 'inv_12345',
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	total: 48000000,
+	error_code: 'card_declined',
+	currency: 'VND',
 })
 ```
 
 ### Rời bỏ dịch vụ
 
 ```js
-subiz('event', {
-	type: 'customer_churned',
-	payload: {
-		company_id: 'com_9981',
-		company_name: 'Tech Corp VN',
-		churn_type: 'voluntary',
-		reason: 'switched_to_competitor',
-		lifetime_days: 345,
-		lifetime_value: 25000000,
-		currency: 'VND',
-	},
+subiz('event', 'customer_churned', {
+	company_id: 'com_9981',
+	company_name: 'Tech Corp VN',
+	churn_type: 'voluntary',
+	reason: 'switched_to_competitor',
+	lifetime_days: 345,
+	lifetime_value: 25000000,
+	currency: 'VND',
 })
 ```
 
@@ -1230,13 +1180,10 @@ subiz('event', {
 Website có thể gửi event riêng ngoài các ví dụ phía trên.
 
 ```js
-subiz('event', {
-	type: 'coupon_copied',
-	payload: {
-		coupon_code: 'SUMMER2026',
-		campaign_id: 'camp_summer_2026',
-		location: 'product_detail',
-	},
+subiz('event', 'coupon_copied', {
+	coupon_code: 'SUMMER2026',
+	campaign_id: 'camp_summer_2026',
+	location: 'product_detail',
 })
 ```
 
@@ -1255,16 +1202,12 @@ Vì `subiz('event', ...)` trả về `Promise`, website có thể dùng `await`
 ```js
 async function sendOrderCompleted(order) {
 	try {
-		await subiz('event', {
-			type: 'order_completed',
-			event_source_id: 'order_completed_' + order.id,
-			payload: {
-				id: order.id,
-				total: order.total,
-				currency: order.currency,
-				items: order.items,
-			},
-		})
+		await subiz('event', 'order_completed', {
+			order_id: order.id,
+			total: order.total,
+			currency: order.currency,
+			items: order.items,
+		}, {event_source_id: 'order_completed_' + order.id})
 	} catch (error) {
 		console.error('Không gửi được order_completed', error)
 	}
@@ -1274,11 +1217,8 @@ async function sendOrderCompleted(order) {
 Với event không quan trọng, website có thể gửi theo kiểu fire-and-forget:
 
 ```js
-subiz('event', {
-	type: 'product_viewed',
-	payload: {
-		id: 'pd2345',
-		name: 'Bàn phím cơ không dây',
-	},
+subiz('event', 'product_viewed', {
+	product_id: 'pd2345',
+	name: 'Bàn phím cơ không dây',
 })
 ```