Hướng Dẫn Tích Hợp Mini Game

Tài liệu này mô tả quy trình tích hợp mini game của TAPTAP vào ứng dụng của khách hàng, sử dụng hệ thống liên kết bảo mật dựa trên token và hiển thị trong WebView.

Tổng Quan

Quy trình tích hợp bao gồm 6 bước chính:

1. Tích hợp dữ liệu từ khách hàng.
2. Người dùng nhấn vào banner game trong ứng dụng.
3. Ứng dụng gửi yêu cầu tới backend của khách hàng để lấy liên kết chơi game.
4. Backend của khách hàng yêu cầu hệ thống của TAPTAP tạo liên kết chơi game.
5. Backend khách hàng nhận liên kết và trả về ứng dụng để mở WebView.
6. WebView lấy verify token và xác thực lại với hệ thống TAPTAP.

Quy Trình Tích Hợp

1. Tích hợp dữ liệu từ khách hàng

Khách hàng có thể tạo lượt chơi/ điểm ban đầu cho người dùng thông qua nhiều phương thức khác nhau, tùy theo chiến dịch triển khai:

1. Quét mã sản phẩm
   Người chơi quét mã từ sản phẩm đã mua để tạo tài khoản (user) và nhận lượt chơi/ điểm tương ứng.

2. Cập nhật giao dịch qua SFTP
   Nhãn hàng hoặc đối tác có thể tải lên file giao dịch (transaction file) của người chơi qua SFTP.
   Hệ thống của TAPTAP sẽ tự động xử lý và chuyển đổi thông tin giao dịch thành lượt chơi/ điểm.

3. Hỗ trợ webhook để đẩy dữ liệu về phía khách hàng

   1. Khách hàng cung cấp endpoint URL cho webhook (HTTPS được yêu cầu).
   2. TAPTAP cấu hình các sự kiện tương ứng để đẩy dữ liệu.
   3. Khi sự kiện xảy ra, hệ thống của TAPTAP sẽ gửi POST đến endpoint.

⚙️ Cả ba hình thức trên đều được đồng bộ hóa vào hệ thống game để đảm bảo tính nhất quán và chống gian lận.

---

2. Người Dùng Bắt Đầu Chơi Game

• Kích hoạt: Người dùng nhấn vào banner game.
• Hành động: Ứng dụng gọi backend để yêu cầu một liên kết game bảo mật.

⚠️ Tại sao không vào thẳng game?
Điều này giúp tránh lộ logic nội bộ và access token ra phía frontend, đồng thời cho phép backend kiểm soát toàn bộ luồng.

---

3. Backend Gửi Yêu Cầu Tạo Liên Kết

• Gọi API tạo liên kết do TAPTAP cung cấp.
• Ví dụ Payload:

  {
    "userId": "123456",
    "sessionId": "abcdef",
    "gameId": "my-mini-game"
  }

• Mục tiêu: Tạo verify token và sinh liên kết một lần chơi, người chơi chỉ có thể mở lại game từ bước click vào banner.

---

4. Hệ Thống Trả Về Liên Kết Game

• Phản hồi ví dụ:

  {
    "gameUrl": "https://game.example.com/play?verify_token=secure_token_string"
  }

• Token chỉ có hiệu lực trong thời gian ngắn, tránh bị lạm dụng hoặc chia sẻ lại.

---

5. Backend Gửi Lại Link Cho App & Mở WebView

• Backend khách hàng gửi liên kết về cho ứng dụng.
• Ứng dụng mở liên kết trong WebView.
• Game bắt đầu tải trong trình WebView.

---

6. WebView Xác Thực Access Token

• Khi trang được tải, WebView:
  • Trích xuất verify token từ query string.
  • Gửi verify token đến hệ thống backend của TAPTAP để xác thực và lấy access token.

❗ Sao phải xác thực lần nữa?

• Đây là lớp bảo mật cuối cùng để đảm bảo token còn hiệu lực, không bị giả mạo hay sử dụng sai mục đích. Nếu token sai, người chơi sẽ không vào được game.
• Access token mới là token sẽ được sử dụng để lưu lại quá trình chơi

Lưu Ý Bảo Mật

• Tất cả kết nối bắt buộc dùng HTTPS.
• Token có hiệu lực ngắn và chỉ dùng một lần.
• Nếu token không hợp lệ, hệ thống sẽ từ chối truy cập game.

Định Nghĩa

• Verify Token: Token được sử dụng để chắc chắn link được sinh ra chỉ sử dụng một lần, không thể chia sẻ, hay tải lại trang, hết hạn trong thời gian ngắn.
• Access Token: Token được lấy sau khi người chơi được verify, dùng để lưu quá trình chơi, có thời gian hết hạn dài hơn.

Sequence Diagram