Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xanhcard.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Geofencing là gì?

Geofencing cho phép thẻ của bạn xuất hiện đúng thời điểm — khi khách hàng ở gần cửa hàng, địa điểm hoặc điểm kiểm tra của bạn. Thay vì dựa vào email hay SMS, ví điện tử sẽ tự động hiển thị thẻ dựa trên vị trí. Với XanhCard, bạn có thể sử dụng geofence dựa trên GPS cho các khu vực rộng như cửa hàng hoặc địa điểm, hoặc iBeacon cho các tương tác chính xác, phạm vi ngắn như lối vào, quầy hoặc khu vực cụ thể bên trong một địa điểm.

​
Thông báo Geofence

  • Khi người dùng vào khu vực geofence, một thông báo sẽ xuất hiện trên màn hình khóa, hiển thị bản xem trước của thẻ từ ứng dụng ví cùng với tin nhắn geofence đã đặt.
Tin nhắn geofence tùy chỉnh chỉ được hỗ trợ trên Apple Wallet. Trên Google Wallet, thẻ được hiển thị bằng tiêu đề và biểu tượng thông báo chuẩn, không kèm tin nhắn tùy chỉnh.
  • Chạm vào thông báo sẽ mở thẻ trong ứng dụng ví, giúp truy cập nhanh mã vạch hoặc xác thực NFC.
  • Thông báo geofence là thụ động, nghĩa là hệ thống không thông báo cho XanhCard khi người dùng vào geofence. Thiết kế này tôn trọng quyền riêng tư và bảo mật.
  • Thông báo geofence sẽ duy trì hiển thị cho đến khi người dùng rời khỏi geofence.
Khi thiết lập 2 hoặc nhiều geofence ở gần nhau, có thể có độ trễ khi thông báo xuất hiện khi di chuyển giữa các geofence. Thiết bị áp dụng thời gian chờ để đảm bảo người dùng đã rời khỏi geofence trước đó trước khi vào geofence tiếp theo.
Bạn có thể dễ dàng cấu hình geofence trong tab Locations của trình chỉnh sửa mẫu thẻ Apple Wallet. Cấu hình Geofence

​
Vị trí (Locations)

  • Sử dụng tọa độ chính xác (vĩ độ và kinh độ) để xác định khu vực mục tiêu.
  • Bán kính geofence có thể đặt từ 10 đến 1000 mét (tùy loại thẻ). Điều này cho phép bạn tùy chỉnh khu vực geofence cho nhu cầu cụ thể, như bao phủ diện tích một cửa hàng nhỏ hoặc một địa điểm ngoài trời lớn hơn.
Cấu hình bán kính geofence chỉ được hỗ trợ trên thẻ Apple Wallet.
  • Mỗi thẻ có thể bao gồm tối đa 10 vị trí geofence. Để có phạm vi rộng hơn, hãy cân nhắc sử dụng beacon.
  • XanhCard không thể theo dõi vị trí chính xác của người dùng, chúng tôi không có quyền truy cập vào dữ liệu vị trí của người dùng, vì dữ liệu này không bao giờ rời khỏi thiết bị.

​
Bán kính Geofence trên Google Wallet

Bán kính thông báo hiệu quả của Google được xác định bởi Google và có thể nằm trong khoảng từ 50m đến 1000m. Giá trị chính xác dựa trên thuật toán không công khai, do Google thực thi và có thể thay đổi mà không cần thông báo.
Khi cấu hình vị trí geofence cho thẻ Google Wallet, Google áp dụng logic riêng để xác định bán kính hiệu quả, nghĩa là khu vực kích hoạt thông báo thực tế có thể khác một chút so với giá trị bạn đã cấu hình.

​
Beacons

iBeacon chỉ được hỗ trợ trên thẻ Apple Wallet.
iBeacon là chuẩn công nghệ do Apple phát triển, cho phép ứng dụng di động lắng nghe tín hiệu từ beacon trong thế giới thực và phản ứng tương ứng. Công nghệ này dựa trên cảm biến khoảng cách Bluetooth Low Energy (BLE), cho phép thiết bị thực hiện hành động khi ở gần beacon. XanhCard không thể theo dõi vị trí chính xác của người dùng, chúng tôi không có quyền truy cập vào dữ liệu vị trí của người dùng, vì dữ liệu này không bao giờ rời khỏi thiết bị. Tìm hiểu thêm về beacon tại: iBeacon

​
Kiểm tra beacon không cần phần cứng

Bạn không cần mua beacon vật lý để kiểm tra hành vi iBeacon trên thẻ. Các ứng dụng như Beacon Walker (có sẵn cho iOS và macOS) có thể phát tín hiệu iBeacon có thể cấu hình từ một thiết bị, sau đó bạn có thể phát hiện trên thiết bị khác đang giữ thẻ. Để kiểm tra:
  1. Cài đặt Beacon Walker trên một thiết bị iOS hoặc macOS dự phòng.
  2. Cấu hình để phát sóng sử dụng cùng giá trị proximity_uuid, major và minor đã định nghĩa trên thẻ của bạn.
  3. Thêm thẻ vào Apple Wallet trên thiết bị thứ hai và đưa nó vào phạm vi của thiết bị đang phát sóng.

​
Cấu hình beacon trong trình chỉnh sửa

Trong trình chỉnh sửa mẫu thẻ, tab Beacons (trong tab Apple Wallet) cho phép bạn cấu hình iBeacon. Mỗi beacon gồm:
  • UUID: Định danh duy nhất của beacon (ví dụ: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0)
  • Major: Giá trị major (tùy chọn) — dùng để nhóm beacon theo khu vực
  • Minor: Giá trị minor (tùy chọn) — dùng để phân biệt beacon trong cùng một nhóm
  • Relevant Text: Văn bản hiển thị khi thẻ xuất hiện trên màn hình khóa

​
Ví dụ thực tế

Nếu bạn có số lượng lớn địa điểm muốn kích hoạt geofence, sau đây là một ví dụ: Tình huống: Chuỗi cà phê Xanh
  • Tình huống: Chuỗi cà phê Xanh, với 100 địa điểm trên khắp Hà Nội, Đà Nẵng và TP. Hồ Chí Minh, sử dụng iBeacon để cung cấp khuyến mãi dựa trên vị trí.
  • Mỗi địa điểm được trang bị hai beacon: một ở khu vực bánh và một ở khu vực cà phê.
  • Thẻ thành viên của chuỗi cà phê Xanh tích hợp các chiến dịch khác nhau trên các khu vực, sử dụng cùng UUID cho tất cả beacon nhưng khác giá trị Major và Minor để xác định địa điểm và khu vực.
  • Tổng cộng, chuỗi cà phê Xanh sẽ mua và cấu hình 200 iBeacon (100 địa điểm x 2 khu vực).
Ví dụ cấu hình
  • UUID: Tất cả beacon dùng E2C56DB5-DFFB-48D2-B060-D0F5A71096E0.
  • Major: Đại diện cho thành phố (ví dụ: 1 cho Hà Nội, 2 cho Đà Nẵng, 3 cho TP. Hồ Chí Minh).
  • Minor: Chỉ định khu vực trong một địa điểm (ví dụ: 1 cho khu vực bánh, 2 cho khu vực cà phê).
Trong ví dụ này, Chuỗi cà phê Xanh sẽ cấu hình 200 beacon của họ như sau: 
Hà Nội (50 địa điểm):
Beacon khu vực Bánh:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 1
    minor: 1
    name: 'ha-noi-banh'
Beacon khu vực Cà phê:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 1
    minor: 2
    name: 'ha-noi-cafe'

Đà Nẵng (30 địa điểm):
Beacon khu vực Bánh:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 2
    minor: 1
    name: 'da-nang-banh'
Beacon khu vực Cà phê:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 2
    minor: 2
    name: 'da-nang-cafe'

TP. Hồ Chí Minh (20 địa điểm):
Beacon khu vực Bánh:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 3
    minor: 1
    name: 'hcm-banh'
Beacon khu vực Cà phê:
    uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    major: 3
    minor: 2
    name: 'hcm-cafe'
Khi tạo thẻ qua XanhCard API, cấu trúc JSON sau sẽ được sử dụng để định nghĩa beacon: 
{
  "beacons": [
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 1,
      "minor": 1,
      "message": "Giảm 50k cho bánh ngọt!",
      "name": "ha-noi-banh"
    },
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 1,
      "minor": 2,
      "message": "Mua 1 tặng 1 nước ép!",
      "name": "ha-noi-cafe"
    },
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 2,
      "minor": 1,
      "message": "Giảm 30k cho bánh ngọt!",
      "name": "da-nang-banh"
    },
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 2,
      "minor": 2,
      "message": "Dùng thử cà phê phin mới!",
      "name": "da-nang-cafe"
    },
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 3,
      "minor": 1,
      "message": "Giảm 50k cho bánh mì!",
      "name": "hcm-banh"
    },
    {
      "proximity_uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 3,
      "minor": 2,
      "message": "Mua 1 tặng 1 cà phê sữa đá!",
      "name": "hcm-cafe"
    }
  ]
}

​
Khắc phục sự cố

Nếu thông báo geofence không hiển thị, hãy kiểm tra:
  • Đảm bảo Dịch vụ Vị trí được bật cho Apple Wallet: Cài đặt -> Quyền riêng tư & Bảo mật -> Dịch vụ Vị trí -> Wallet Apple Wallet Location Permissions
  • Đối với Google Wallet, bán kính geofence thực tế có thể khác với giá trị bạn đã đặt (xem Bán kính Geofence trên Google Wallet).
  • Khi di chuyển giữa các geofence gần nhau, thiết bị có thời gian chờ trước khi kích hoạt geofence mới.