reportAnalytics

reportAnalytics là API dùng để ghi nhận dữ liệu của một số sự kiện tuỳ chỉnh. Khi khách hàng truy xuất MiniApp sẽ có những system events được gửi lên hệ thống như page_view, tuy nhiên với những tác vụ đặc biệt thì developer có thể gửi những analytics tùy biến của mình lên, để từ đó có thể tổng hợp ra những phân tích hỗ trợ phát triển kinh doanh của MiniApp.

Các sự kiện hỗ trợ

Auto-tracked events

Đây là các event mà SDK tự động bắn, developer không cần code gì

miniapp_open

Trigger khi User mở Mini App thành công (first page loaded)

{
  "event_name": "miniapp_open",
  "properties": {
    "page_path": "/home", //
    "page_title": "Trang chủ", // Chưa có
    "referrer": "home_screen", // home_screen | notification | deeplink | qr_code
    "is_first_open": false, // Chưa có
    "app_query": "...", // Mini app params/query
    "utm_source": "home", // Attribution
    "utm_medium": "quicklink",
    "utm_campaign": "HPNY"
  }
}

miniapp_close

Trigger khi User đóng Mini App

{
  "event_name": "miniapp_close",
  "properties": {
    "page_path": "/home", // Trang khi mini app đóng - Chưa có
    "page_title": "Trang chủ" // Chưa có
  }
}

page_view

Trigger khi User navigate đến một page mới (kể cả first page)

{
  "event_name": "page_view",
  "properties": {
    "page_path": "/category/bike",
    "page_title": "Xe máy điện",
    "referrer_page": "/home", // Page trước đó
    "is_first_page_in_session": false, // có phải trang đầu tiên
    "app_query": "id=12345"
  }
}

permission_request

Trigger khi User trả lời permission prompt (accept/reject)

{
  "event_name": "permission_request",
  "properties": {
    "permission_type": "location",
    "permission_result": "accept", // accept | reject
    "trigger_page": "/store-locator" // Page nơi request xảy ra - tạm thời chưa có
  }
}

permission_grant / permission_revoke

Trigger khi User thay đổi permission trong Quản lý riêng tư

{
  "event_name": "permission_revoke",
  "properties": {
    "permission_type": "location",
    "previous_state": "enabled",
    "trigger_source": "privacy_page" // privacy_page
  }
}

Custom events

Đây là các event mà developer phải gắn. Nếu developer muốn bắn custom event ngoài những event phía dưới thì có thể sử dụng structure dưới đây, sau đó liên hệ team PTNT để được whiltelist.

import apis from '@v-miniapp/apis'

apis.reportAnalytics("event_name", {
  payload...
})

view_item

Trigger: User xem chi tiết danh sách sản phẩm/nội dung

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Ví dụ	Mô tả
currency	string	VND	Đơn vị tiền tệ
value	number	115000	Tổng giá trị của các sản phẩm vừa xem
items	Item[]		Danh sách các sản phẩm vừa xem

Item Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
item_id	string	✓	SKU_12345	Mã định danh sản phẩm.
item_name	string	✓	Stan and Friends Tee	Tên của sản phẩm.
item_price	number		10000	Giá sản phẩm.
item_variant	string		green	Phẩn bản của sản phẩm.
item_brand	string		Google	Thương hiệu của sản phẩm.
item_category	string		Apparel	Danh mục của sản phẩm.
item_category2	string		Adult	Danh mục của sản phẩm.
item_category3	string		Shirts	Danh mục của sản phẩm.
item_category4	string		Crew	Danh mục của sản phẩm.
item_category5	string		Short sleeve	Danh mục của sản phẩm.
quantity	number		1	số lượng của sản phẩm đó.

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics('view_item', {
  currency: 'VND',
  value: 150000,
  items: [
    {
      item_id: 'SKU_12345',
      item_name: 'Stan and Friends Tee',
      item_price: 50000,
      item_variant: 'green',
      item_brand: 'Google',
      item_category: 'Apparel',
      item_category2: 'Adult',
      item_category3: 'Shirts',
      item_category4: 'Crew',
      item_category5: 'Short sleeve',
      quantity: 3,
    },
  ],
})

---oOo---

add_to_cart

Trigger khi User thêm sản phẩm vào giỏ

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Ví dụ	Mô tả
currency	string	VND	Đơn vị tiền tệ
value	number	115000	Tổng giá trị các sản phẩm vừa thêm vào giỏ
items	Item[]		Danh sách các sản phẩm vừa xem

Item Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
item_id	string	✓	SKU_12345	Mã định danh sản phẩm.
item_name	string	✓	Stan and Friends Tee	Tên của sản phẩm.
item_price	number		50000	Giá sản phẩm.
item_variant	string		green	Phẩn bản của sản phẩm.
item_brand	string		Google	Thương hiệu của sản phẩm.
item_category	string		Apparel	Danh mục của sản phẩm.
item_category2	string		Adult	Danh mục của sản phẩm.
item_category3	string		Shirts	Danh mục của sản phẩm.
item_category4	string		Crew	Danh mục của sản phẩm.
item_category5	string		Short sleeve	Danh mục của sản phẩm.
quantity	number		1	số lượng của sản phẩm đó.

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics('add_to_cart', {
  currency: 'VND',
  value: 150000,
  items: [
    {
      item_id: 'SKU_12345',
      item_name: 'Stan and Friends Tee',
      item_price: 50000,
      item_variant: 'green',
      item_brand: 'Google',
      item_category: 'Apparel',
      item_category2: 'Adult',
      item_category3: 'Shirts',
      item_category4: 'Crew',
      item_category5: 'Short sleeve',
      quantity: 3,
    },
  ],
})

---oOo---

remove_from_cart

Trigger khi user xóa 1 mặt hàng khỏi giỏ hàng

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Ví dụ	Mô tả
currency	string	VND	Đơn vị tiền tệ
value	number	115000	Tổng giá các sản phẩm vừa xóa khỏi giỏ
items	Item[]		Danh sách các sản phẩm vừa xem

Item Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
item_id	string	✓	SKU_12345	Mã định danh sản phẩm.
item_name	string	✓	Stan and Friends Tee	Tên của sản phẩm.
item_price	number		50000	Giá sản phẩm.
item_variant	string		green	Phẩn bản của sản phẩm.
item_brand	string		Google	Thương hiệu của sản phẩm.
item_category	string		Apparel	Danh mục của sản phẩm.
item_category2	string		Adult	Danh mục của sản phẩm.
item_category3	string		Shirts	Danh mục của sản phẩm.
item_category4	string		Crew	Danh mục của sản phẩm.
item_category5	string		Short sleeve	Danh mục của sản phẩm.
quantity	number		1	số lượng của sản phẩm đó.

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics('remove_from_cart', {
  currency: 'VND',
  value: 150000,
  items: [
    {
      item_id: 'SKU_12345',
      item_name: 'Stan and Friends Tee',
      item_price: 50000,
      item_variant: 'green',
      item_brand: 'Google',
      item_category: 'Apparel',
      item_category2: 'Adult',
      item_category3: 'Shirts',
      item_category4: 'Crew',
      item_category5: 'Short sleeve',
      quantity: 3,
    },
  ],
})

---oOo---

begin_checkout

Trigger khi User bắt đầu checkout

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Ví dụ	Mô tả
currency	string	VND	Đơn vị tiền tệ
value	number	115000	Tổng giá trị đơn hàng.
items	Item[]		Danh sách các sản phẩm vừa xem

Item Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
item_id	string	✓	SKU_12345	Mã định danh sản phẩm.
item_name	string	✓	Stan and Friends Tee	Tên của sản phẩm.
item_price	number		50000	Giá sản phẩm.
item_variant	string		green	Phẩn bản của sản phẩm.
item_brand	string		Google	Thương hiệu của sản phẩm.
item_category	string		Apparel	Danh mục của sản phẩm.
item_category2	string		Adult	Danh mục của sản phẩm.
item_category3	string		Shirts	Danh mục của sản phẩm.
item_category4	string		Crew	Danh mục của sản phẩm.
item_category5	string		Short sleeve	Danh mục của sản phẩm.
quantity	number		1	số lượng của sản phẩm đó.

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics('begin_checkout', {
  currency: 'VND',
  value: 150000,
  items: [
    {
      item_id: 'SKU_12345',
      item_name: 'Stan and Friends Tee',
      item_price: 50000,
      item_variant: 'green',
      item_brand: 'Google',
      item_category: 'Apparel',
      item_category2: 'Adult',
      item_category3: 'Shirts',
      item_category4: 'Crew',
      item_category5: 'Short sleeve',
      quantity: 3,
    },
  ],
})

---oOo---

apply_promotion

Trigger khi user áp dụng voucher / promotion

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
coupon	string		socksSale	coupon name hoặc id
value	number		20000	Giá trị của coupon

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics("apply_promotion", {
  coupon: "socksSale",
  value: 20000
}

---oOo---

apply_vpoint

Trigger khi user lựa chọn sử dụng v-point để thanh toán

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
amount	number		10000	Giá trị của vpoint

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics('apply_vpoint', {
  amount: 10000,
})

---oOo---

purchase

Trigger khi user hoàn tất thanh toàn và xem màn hình xác nhận đơn hàng thành công

Ecommerce Parameters

Thuộc tính	Kiểu dữ liệu	Ví dụ	Mô tả
order_id	string	0_123456	ID của đơn hàng
transaction_id	string	TXN_20251108_ABC123	ID của giao dịch thanh toán
currency	string	VND	Đơn vị tiền tệ
value	number	115000	Tổng giá trị đơn hàng
payment_method	string	credit_card	Phương thức thanh toán đơn hàng
items	Item[]		Danh sách các sản phẩm thanh toán

Item Parameters

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Ví dụ	Mô tả
item_id	string	✓	SKU_12345	Mã định danh sản phẩm.
item_name	string	✓	Stan and Friends Tee	Tên của sản phẩm.
item_price	number		115000	Giá sản phẩm.
item_variant	string		green	Phẩn bản của sản phẩm.
item_brand	string		Google	Thương hiệu của sản phẩm.
item_category	string		Apparel	Danh mục của sản phẩm.
item_category2	string		Adult	Danh mục của sản phẩm.
item_category3	string		Shirts	Danh mục của sản phẩm.
item_category4	string		Crew	Danh mục của sản phẩm.
item_category5	string		Short sleeve	Danh mục của sản phẩm.
quantity	number		1	số lượng của sản phẩm đó.

Sử dụng

Ví dụ sau dùng để ghi nhận đơn hàng lên hệ thống analytics:

import apis from '@v-miniapp/apis'

apis.reportAnalytics("purchase", {
  order_id: "0_123456",
  transaction_id: "TXN_20251108_ABC123",
  currency: "VND",
  value: 150000,
  payment_method: "credit_card"
   items: [
    {
      item_id: "SKU_12345",
      item_name: "Stan and Friends Tee",
      item_price: 50000,
      item_variant: "green",
      item_brand: "Google",
      item_category: "Apparel",
      item_category2: "Adult",
      item_category3: "Shirts",
      item_category4: "Crew",
      item_category5: "Short sleeve",
      quantity: 3
    }
  ]
})

---oOo---

Các sự kiện hỗ trợ​

Auto-tracked events​

miniapp_open​

miniapp_close​

page_view​

permission_request​

permission_grant / permission_revoke​

Custom events​

view_item​

Ecommerce Parameters​

Item Parameters​

Sử dụng​

add_to_cart​

Ecommerce Parameters​

Item Parameters​

Sử dụng​

remove_from_cart​

Ecommerce Parameters​

Item Parameters​

Sử dụng​

begin_checkout​

Ecommerce Parameters​

Item Parameters​

Sử dụng​

apply_promotion​

Ecommerce Parameters​

Sử dụng​

apply_vpoint​

Ecommerce Parameters​

Sử dụng​

purchase​

Ecommerce Parameters​

Item Parameters​

Sử dụng​

Các sự kiện hỗ trợ

Auto-tracked events

miniapp_open

miniapp_close

page_view

permission_request

permission_grant / permission_revoke

Custom events

view_item

Ecommerce Parameters

Item Parameters

Sử dụng

add_to_cart

Ecommerce Parameters

Item Parameters

Sử dụng

remove_from_cart

Ecommerce Parameters

Item Parameters

Sử dụng

begin_checkout

Ecommerce Parameters

Item Parameters

Sử dụng

apply_promotion

Ecommerce Parameters

Sử dụng

apply_vpoint

Ecommerce Parameters

Sử dụng

purchase

Ecommerce Parameters

Item Parameters

Sử dụng