@subiz/widget-v4 4.1.202 → 4.1.204

package/api.md

@@ -0,0 +1,1224 @@
+# Subiz CDP Event API
+
+Tài liệu này hướng dẫn website gửi sự kiện người dùng về Subiz CDP bằng client library đã được cài trên website.
+
+## Tổng quan
+
+API chính để gửi sự kiện là:
+
+```js
+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', '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) {
+	console.error('Không gửi được event', error)
+})
+```
+
+## Cấu trúc event
+
+```js
+subiz('event', 'event_name', {}, {event_source_id: 'evt_1234'})
+```
+
+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. |
+| `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', '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.
+
+Nên dùng:
+
+```txt
+product_viewed
+product_searched
+add_to_cart
+checkout_started
+order_completed
+form_submitted
+```
+
+Không nên dùng:
+
+```txt
+ProductViewed
+productViewed
+product-viewed
+view product
+```
+
+## Common fields
+
+Subiz tự thu thập một số thông tin ngữ cảnh như URL hiện tại, referrer, thiết bị, trình duyệt, session và nguồn truy cập nếu có thể. Website vẫn có thể gửi các trường này trong `payload` khi muốn override hoặc bổ sung dữ liệu chính xác hơn.
+
+Các field thường dùng:
+
+| Trường | Mô tả |
+| --- | --- |
+| `url` | URL nơi event xảy ra. |
+| `title` | Tiêu đề trang hoặc tên nội dung. |
+| `referrer` | Trang giới thiệu người dùng tới URL hiện tại. |
+| `utm_source` | UTM source nếu website muốn gửi chủ động. |
+| `utm_medium` | UTM medium. |
+| `utm_campaign` | UTM campaign. |
+| `utm_content` | UTM content. |
+| `utm_term` | UTM term. |
+| `source` | Nguồn nội bộ của website, ví dụ `homepage`, `landing_page`, `email_campaign`. |
+
+Ví dụ:
+
+```js
+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',
+})
+```
+
+## Dữ liệu cá nhân
+
+Chỉ gửi các thông tin cần thiết cho mục đích chăm sóc khách hàng, phân tích hành vi và cá nhân hóa trải nghiệm. Không gửi mật khẩu, mã OTP, thông tin thẻ thanh toán, token đăng nhập hoặc dữ liệu nhạy cảm không cần thiết vào `payload`.
+
+Các field như `email`, `phone`, `fullname`, `customer_id`, `user_id` có thể được gửi khi website đã có quyền sử dụng dữ liệu đó trong hệ thống của mình.
+
+## Định danh khách hàng
+
+## Pageview
+
+Dùng `pageview` khi website muốn ghi nhận lượt xem trang thủ công, đặc biệt trong Single Page App khi URL thay đổi nhưng browser không reload trang.
+
+```js
+subiz('pageview', {
+	url: 'https://example.com/blog/cdp-architecture',
+	title: 'CDP Architecture',
+	referrer: 'https://google.com',
+})
+```
+
+`pageview` là wrapper của event `content_viewed`. Website nên dùng `subiz('pageview', ...)` thay vì tự gửi `content_viewed` cho các lượt xem trang thông thường.
+
+Ví dụ cho Single Page App:
+
+```js
+function onRouteChange(route) {
+	subiz('pageview', {
+		url: window.location.href,
+		title: document.title,
+		referrer: document.referrer,
+	})
+}
+```
+
+## Cập nhật thông tin khách hàng
+
+```js
+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 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`; 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 `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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', 'coupon_applied', {
+	coupon_code: 'SUMMER2026',
+	discount_amount: 150000,
+	currency: 'VND',
+	cart_id: 'cart_12345',
+})
+```
+
+### Xóa mã giảm giá
+
+```js
+subiz('event', 'coupon_removed', {
+	coupon_code: 'SUMMER2026',
+	cart_id: 'cart_12345',
+})
+```
+
+### Bắt đầu thanh toán
+
+```js
+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', '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', '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', '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', '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', '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', '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', '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', 'order_confirmed', {
+	order_id: 'ord_99482',
+	expected_delivery_date: '2026-05-15',
+	status: 'confirmed',
+})
+```
+
+### Hủy đơn hàng
+
+```js
+subiz('event', 'order_cancelled', {
+	order_id: 'ord_99482',
+	cancel_reason: 'customer_changed_mind',
+})
+```
+
+### Hoàn tiền đơn hàng
+
+```js
+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', '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', 'return_completed', {
+	order_id: 'ord_99482',
+	return_id: 'ret_12345',
+	refund_amount: 1500000,
+	currency: 'VND',
+})
+```
+
+### Bắt đầu giao hàng
+
+```js
+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', 'order_delivered', {
+	order_id: 'ord_99482',
+	tracking_code: 'VNPOST_88374',
+})
+```
+
+### Đánh giá sản phẩm
+
+```js
+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', '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',
+})
+```
+
+## Dịch vụ
+
+### Đặt lịch dịch vụ
+
+```js
+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', 'service_completed', {
+	booking_id: 'bk_77362',
+	service_id: 'srv_massage_01',
+	actual_duration_minutes: 65,
+})
+```
+
+## Tương tác
+
+### 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', 'reacted', {
+	target_type: 'product',
+	reaction: 'like',
+	action: 'add',
+	channel: 'website',
+	product_id: 'pd2345',
+	sku: 's5345',
+})
+```
+
+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', 'reacted', {
+	target_type: 'message',
+	reaction: 'like',
+	action: 'add',
+	channel: 'telegram',
+	message_id: 'msg_778899',
+})
+```
+
+### 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', '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', 'customer_loyalty_updated', {
+	action: 'earn',
+	points: 500,
+	current_tier: 'platinum',
+})
+```
+
+## B2B và hợp đồng
+
+Các event B2B nên giúp marketing và sales trả lời các câu hỏi như: lead nào có intent cao, công ty nào đang active, deal nào có khả năng close, chiến dịch nào tạo pipeline, khách hàng nào sắp renew hoặc có nguy cơ churn.
+
+Nên giữ ổn định các field định danh như `company_id`, `company_name`, `contact_id`, `deal_id`, `contract_id`, `plan`, `industry`, `company_size`, `estimated_value`, `currency`.
+
+| Câu hỏi marketing/sales | Event nên dùng |
+| --- | --- |
+| Lead nào vừa phát sinh? | `lead_created`, `form_submitted`, `customer_registered` |
+| Lead nào có intent cao? | `demo_requested`, `meeting_booked`, `quote_requested`, `pricing_viewed` |
+| Campaign nào tạo pipeline? | `lead_created`, `demo_requested`, `quote_requested`, `deal_created` |
+| Deal nào đang tiến triển? | `deal_created`, `deal_stage_changed`, `proposal_sent`, `quote_requested` |
+| Deal nào bị mất? | `deal_lost`, `contract_cancelled` |
+| Khách hàng nào có khả năng mở rộng? | `subscription_upgraded`, `seat_added`, `feature_activated` |
+| Khách hàng nào sắp renew? | `renewal_started`, `invoice_paid`, `contract_signed` |
+| Khách hàng nào có nguy cơ churn? | `subscription_downgraded`, `invoice_failed`, `customer_churned` |
+
+### Tạo lead
+
+```js
+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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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', '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',
+})
+```
+
+## Custom event
+
+Website có thể gửi event riêng ngoài các ví dụ phía trên.
+
+```js
+subiz('event', 'coupon_copied', {
+	coupon_code: 'SUMMER2026',
+	campaign_id: 'camp_summer_2026',
+	location: 'product_detail',
+})
+```
+
+Quy tắc:
+
+- `type` phải dùng `snake_case`.
+- `type` chỉ gồm chữ thường, số và `_`.
+- `type` tối đa 64 ký tự.
+- `payload` nên là object JSON, không gửi function, DOM node hoặc object có vòng lặp tham chiếu.
+- Dùng `event_source_id` cho các event quan trọng như `order_completed`, `payment_completed`, `form_submitted` để tránh ghi nhận trùng.
+
+## Xử lý lỗi
+
+Vì `subiz('event', ...)` trả về `Promise`, website có thể dùng `await` hoặc `.then/.catch`.
+
+```js
+async function sendOrderCompleted(order) {
+	try {
+		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)
+	}
+}
+```
+
+Với event không quan trọng, website có thể gửi theo kiểu fire-and-forget:
+
+```js
+subiz('event', 'product_viewed', {
+	product_id: 'pd2345',
+	name: 'Bàn phím cơ không dây',
+})
+```