@subiz/widget-v4 4.1.201 → 4.1.203

package/api.md

@@ -0,0 +1,1284 @@
+# 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', {
+	type: 'product_viewed',
+	payload: {
+		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',
+	},
+}).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', {
+	type: 'event_name',
+	event_source_id: 'evt_1234',
+	payload: {},
+})
+```
+
+| Trường | 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. |
+
+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',
+	},
+})
+```
+
+## 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', {
+	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',
+	},
+})
+```
+
+## 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', {
+	type: 'user_updated',
+	payload: {
+		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'}`.
+
+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` |
+| 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`.
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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,
+	},
+})
+```
+
+### 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,
+	},
+})
+```
+
+### Đă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',
+	},
+})
+```
+
+### Đă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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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},
+		],
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### Á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',
+	},
+})
+```
+
+### Xóa mã giảm giá
+
+```js
+subiz('event', {
+	type: 'coupon_removed',
+	payload: {
+		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,
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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},
+		],
+	},
+})
+```
+
+### Đặ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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### Hủy đơn hàng
+
+```js
+subiz('event', {
+	type: 'order_cancelled',
+	payload: {
+		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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### Giao hàng thành công
+
+```js
+subiz('event', {
+	type: 'order_delivered',
+	payload: {
+		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,
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+## Dịch vụ
+
+### Đặ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',
+	},
+})
+```
+
+### 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,
+	},
+})
+```
+
+## Tương tác
+
+### Gửi form
+
+```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',
+	},
+})
+```
+
+### Đăng nhập và đăng xuất
+
+```js
+subiz('event', {
+	type: 'login',
+})
+
+subiz('event', {
+	type: '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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+## 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', {
+	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',
+	},
+})
+```
+
+### Đă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,
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### Đặ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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### Đổ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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+### 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',
+	},
+})
+```
+
+## Custom 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',
+	},
+})
+```
+
+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', {
+			type: 'order_completed',
+			event_source_id: 'order_completed_' + order.id,
+			payload: {
+				id: order.id,
+				total: order.total,
+				currency: order.currency,
+				items: order.items,
+			},
+		})
+	} 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', {
+	type: 'product_viewed',
+	payload: {
+		id: 'pd2345',
+		name: 'Bàn phím cơ không dây',
+	},
+})
+```