Zalo Mini App
Người chơi vào game ngay trong Zalo: đăng nhập bằng Zalo, cấp SĐT khi cần nhận quà, chia sẻ để nhận thêm lượt, theo dõi OA và nhận kết quả qua ZNS.
Mục tiêu
| Mục tiêu | Chỉ số đo | Ngưỡng MVP |
|---|
| Vào chơi không cần đăng ký | Thời gian từ mở mini app đến bắt đầu phiên đầu | ≤ 15 giây ở p90 trên 4G |
| Lấy được SĐT để trao quà | Tỉ lệ người trúng đồng ý cấp SĐT | ≥ 80% |
| Lan toả qua Zalo | Người chơi mới đến từ link chia sẻ / tổng người chơi mới | mục tiêu từ FCM |
| Tăng người theo dõi OA FPT Telecom | Số follow OA mới từ mini app | mục tiêu từ FCM |
| Không bị Zalo từ chối khi publish | Số lần bị trả về khi kiểm duyệt | ≤ 1 lần mỗi bản phát hành lớn |
Ngoài phạm vi
- Quy tắc số lượt nhận khi chia sẻ, follow OA — thuộc Khung game (nguồn lượt) và Campaign (cấu hình). Trang này chỉ mô tả Zalo làm được gì.
- Hợp đồng API Zalo, ZNS, mẫu tin, chi phí tin — xem Hệ thống ngoài.
- Thanh toán trong Zalo (ZaloPay), mini app bán hàng.
- Header, safe area, ZaUI — xem Kênh triển khai (UI).
Điểm vào
| Điểm vào | Ví dụ | Mở tới | Gắn nguồn |
|---|
| Menu OA FPT Telecom | Nút "Chơi game nhận quà" trên OA | Trang chủ mini app: danh sách campaign đang chạy | src=oa_menu |
| Tin nhắn / bài viết OA | Broadcast đầu campaign | Landing campaign | src=oa_post + mã campaign |
| Link chia sẻ của người chơi | Bạn bè gửi qua chat Zalo | Landing campaign | src=share + mã người mời |
| QR in tại booth, poster, tờ rơi | Mô hình A, C tại sự kiện | Landing campaign hoặc thẳng phòng chơi | src=qr + mã điểm activation |
| Tin ZNS | "Bạn còn 1 lượt chơi hôm nay" | Landing campaign / Quà của tôi | src=zns + mã mẫu tin |
| Tìm kiếm trong Zalo | Gõ "FPT" | Trang chủ mini app | src=search |
Tham số nguồn đi theo người chơi đến phiên chơi và lead, phục vụ Báo cáo phễu. Đặt tên tham số chung với UTM ở Website & mobile .
Vai trò & quyền
| Vai trò | Việc trên kênh Zalo |
|---|
| Người chơi | Chơi, cấp/từ chối quyền SĐT, chia sẻ, follow OA, xem Quà của tôi |
| Quản lý campaign | Bật kênh Zalo cho campaign, chọn mẫu ZNS đã duyệt, đặt nội dung chia sẻ |
| Quản trị hệ thống | Quản lý tài khoản Zalo Developer, OA, gửi bản build đi kiểm duyệt, publish |
User stories
| Mã | Là… | Tôi muốn… | Để… | Ưu tiên |
|---|
| US-ZMA-01 | Người chơi | chơi thử ngay khi mở mini app, chưa cần cấp SĐT | biết game có đáng chơi không | Must |
| US-ZMA-02 | Người chơi | cấp SĐT bằng một chạm khi nhận quà | không phải gõ số, không chờ OTP | Must |
| US-ZMA-03 | Người chơi | chia sẻ game cho bạn trên Zalo để nhận thêm lượt | chơi thêm | Must |
| US-ZMA-04 | Người chơi | nhận mã quà qua tin Zalo | không mất mã khi đóng mini app | Must |
| US-ZMA-05 | Người chơi | follow OA FPT Telecom ngay trong game | nhận thêm lượt và tin khuyến mãi | Should |
| US-ZMA-06 | Người chơi | mở mini app từ QR tại booth và vào thẳng phòng chơi trên TV | không phải tìm game | Must |
| US-ZMA-07 | Quản lý campaign | chọn mẫu ZNS đã được Zalo duyệt cho từng sự kiện (trúng quà, nhắc lượt) | không phải nhờ IT | Should |
| US-ZMA-08 | Quản trị hệ thống | đưa campaign mới lên mà không phải gửi Zalo duyệt lại | kịp lịch marketing | Must |
Luồng chính
Đăng nhập và quyền SĐT
- Mở mini app → lấy Zalo ID (không cần người chơi xác nhận) → tạo/khớp hồ sơ người chơi ở trạng thái "chỉ có Zalo ID".
- Xin quyền thông tin cơ bản (tên, ảnh) để hiện trên bảng xếp hạng — người chơi từ chối thì dùng biệt danh tự sinh.
- Người chơi chơi được lượt đầu khi chưa có SĐT; kết quả trúng được giữ.
- Trước bước nhận quà (hoặc trước khi chơi nếu campaign bắt định danh): hiện lý do "Cần SĐT để trao quà và gửi mã" → gọi hộp thoại cấp SĐT của Zalo.
- Đồng ý: máy chủ đổi token lấy SĐT qua Zalo (Hệ thống ngoài) → liên kết Zalo ID ↔ SĐT theo Khách hàng. SĐT từ Zalo coi là đã xác thực, không cần OTP.
- Từ chối: cho nhập SĐT tay + OTP ; vẫn từ chối → lượt trúng giữ trong hạn nhận, nhắc lại ở lần mở sau.
Chia sẻ nhận thêm lượt
- Người chơi bấm "Chia sẻ nhận thêm lượt" → mở hộp thoại chia sẻ của Zalo với ảnh, tiêu đề, link có mã người mời.
- Zalo trả kết quả "đã mở hộp chia sẻ" nhưng không xác nhận chắc đã gửi tới ai.
- Hệ thống ghi sự kiện chia sẻ; cộng lượt theo quy tắc nguồn lượt ở Khung game (vd. tính khi bấm, hay khi bạn mở link).
- Bạn mở link → ghi nhận "người được mời" gắn mã người mời — dữ liệu cho Chống gian lận và báo cáo lan toả.
Follow OA
- Hiện nút "Theo dõi FPT Telecom" ở màn kết quả hoặc màn hết lượt (không chặn chơi).
- Gọi API follow OA của Zalo → Zalo trả trạng thái đã follow.
- Cộng lượt (nếu campaign cấu hình) đúng 1 lần cho mỗi Zalo ID trong campaign; unfollow rồi follow lại không cộng thêm.
Gửi ZNS
| Sự kiện | Nội dung | Khi gửi | Bắt buộc |
|---|
| Trúng quà digital | Tên quà, mã, hạn dùng, link Quà của tôi | Khi cấp phát "Đã cấp" | ✓ |
| Trúng quà vật lý | Tên quà, nơi nhận, hạn nhận, link QR nhận quà | Khi cấp phát "Đã cấp" | ✓ |
| Mã gửi sau (nhà cung cấp chậm, trúng offline) | Như trúng quà digital | Khi có mã | ✓ |
| Nhắc lượt / nhắc quà sắp hết hạn | Số lượt còn, hạn | Theo lịch campaign | Tuỳ chọn, cần đồng ý nhận tin |
| OTP (khi người chơi tự nhập SĐT) | Mã OTP theo Website & mobile | Khi yêu cầu | — |
Mẫu ZNS phải được Zalo duyệt trước; ZNS gửi tới SĐT, không cần người chơi follow OA. Gửi lỗi → chuyển SMS theo Hệ thống ngoài.
Quy tắc nghiệp vụ
| Mã | Quy tắc | Ví dụ |
|---|
| BR-ZMA-01 | Xin quyền (SĐT, vị trí, camera) đúng lúc cần, kèm một câu lý do; không xin khi vừa mở app | Xin SĐT ngay trước "Nhận quà" |
| BR-ZMA-02 | Người chơi từ chối quyền: không hỏi lại trong cùng phiên; lần mở sau hỏi lại tối đa 1 lần | |
| BR-ZMA-03 | Một Zalo ID chỉ liên kết một SĐT. Zalo ID mới trùng SĐT đã có → gộp vào hồ sơ có sẵn theo Khách hàng | |
| BR-ZMA-04 | Lượt trúng khi chưa có SĐT giữ trong hạn nhận; chỉ cấp mã sau khi có SĐT | |
| BR-ZMA-05 | Checkbox đồng ý xử lý dữ liệu không tick sẵn, hiện cùng lúc xin SĐT; cấp quyền Zalo không thay cho đồng ý theo NĐ 13/2023 — xem Dữ liệu cá nhân | |
| BR-ZMA-06 | Không đặt nút quan trọng ở góc phải trên (cụm nút "… / ×" của Zalo) | |
| BR-ZMA-07 | Campaign mới chỉ là dữ liệu tải từ máy chủ; game mẫu mới hoặc đổi quyền xin dùng mới cần bản build mới và kiểm duyệt | Thêm campaign "Tết" không cần duyệt lại; thêm game mới thì cần |
| BR-ZMA-08 | Nội dung chia sẻ (ảnh, tiêu đề) cấu hình theo campaign; ảnh 1200×630, không ghi hứa hẹn quà không có trong cơ cấu giải | |
| BR-ZMA-09 | Mã quà trong ZNS là mã đầy đủ (chỉ gửi người trúng); mọi nơi khác theo Kho quà BR-QUA-10 | |
| BR-ZMA-10 | Một Zalo ID chỉ có 1 phiên chơi đang chạy; mở trên máy thứ hai thì phiên cũ "Bỏ dở" theo Khung game | |
Giới hạn kỹ thuật Zalo
| Giới hạn | Ảnh hưởng | Cách xử lý |
|---|
| Dung lượng gói mini app có trần số MB hiện hành theo tài liệu Zalo | Không nhúng được mọi asset của 10 game mẫu | Gói chỉ chứa khung + font subset; asset game, skin campaign tải từ CDN khi vào game, ảnh WebP, không video nền |
| Header Zalo cố định + cụm nút "… / ×" | Mất vùng trên cùng | HUD đặt dưới header; theo Kênh triển khai (UI) |
| Zalo ID có thể khác nhau giữa các mini app / OA | Không dùng Zalo ID để khớp với dữ liệu Zalo ở hệ khác | Khớp người chơi bằng SĐT |
| Lấy SĐT trả token, phải đổi ở máy chủ, token có hạn | Không lấy SĐT được khi mất mạng | Đổi ngay khi nhận; lỗi → cho nhập tay + OTP |
| API chia sẻ không xác nhận người nhận | Dễ bấm chia sẻ "khống" lấy lượt | Quy tắc cộng lượt ở Khung game; giới hạn ở Chống gian lận |
| ZNS chỉ gửi theo mẫu đã duyệt, có phí mỗi tin, có hạn mức gửi | Không gửi nội dung tự do | Duyệt mẫu trước campaign ≥ 5 ngày làm việc |
| iOS có thể chặn micro / camera trong webview Zalo | Game 8 (giọng nói), game có camera | Kiểm thử từng nền tảng trước khi bật game cho kênh Zalo |
| Phiên bản Zalo cũ thiếu API | Lỗi khi gọi chia sẻ / follow | Kiểm tra API có sẵn; không có thì ẩn nút. Bản Zalo tối thiểu IT xác định |
Chi tiết API, mã lỗi, hạn mức: Hệ thống ngoài.
Kiểm duyệt, publish & phiên bản
- Build bản mới → đưa lên môi trường thử của Zalo (bản phát triển / bản thử nghiệm), QA kiểm theo mục Tiêu chí nghiệm thu.
- Kiểm tra trước khi gửi: link thể lệ, điều khoản, chính sách dữ liệu hiện rõ ở trang chủ và màn xin SĐT; mô tả quyền xin dùng khớp tính năng.
- Quản trị hệ thống gửi Zalo kiểm duyệt. Thời gian duyệt 1–3 ngày làm việc — lịch phát hành phải trừ khoảng này.
- Được duyệt → publish. Bị trả về → sửa theo lý do, gửi lại; ghi lý do vào nhật ký phát hành.
- Giữ bản đang chạy cho đến khi bản mới publish; campaign đang chạy không bị gián đoạn.
| Thay đổi | Cần build + duyệt? |
|---|
| Campaign mới, đổi thể lệ, cơ cấu giải, skin, nội dung chia sẻ | Không — dữ liệu từ máy chủ |
| Phiên bản game mới đã có trong gói tải từ CDN | Không , nếu không đổi quyền / API dùng |
| Thêm quyền xin dùng (vị trí, camera, micro), đổi luồng đăng nhập | Có |
| Sửa lỗi khung, đổi giao diện chung | Có |
Tải game từ CDN và kiểm duyệtZalo có thể không chấp nhận mini app tải mã chạy từ ngoài gói. Cần IT xác nhận với chính sách Zalo hiện hành trước khi chốt kiến trúc — xem Q-ZMA-02.
Ngoại lệ & lỗi
| Tình huống | Hệ thống xử lý | Thông báo hiển thị |
|---|
| Từ chối cấp SĐT khi đã trúng | Giữ lượt trúng; cho nhập tay + OTP | "Bạn cần SĐT để nhận quà. Nhập số khác?" |
| Đổi token SĐT lỗi | Thử lại 2 lần; vẫn lỗi → nhập tay + OTP | "Chưa lấy được SĐT từ Zalo, vui lòng nhập" |
| SĐT Zalo đã gắn Zalo ID khác | Không ghép; ghi nhận để xem xét | "SĐT này đã dùng ở tài khoản Zalo khác" |
| Gửi ZNS lỗi / SĐT không dùng Zalo | Chuyển SMS; mã vẫn ở Quà của tôi | — |
| Mở link chia sẻ của campaign đã kết thúc | Mở trang chủ mini app | "Chương trình đã kết thúc. Xem chương trình khác" |
| Phiên bản Zalo không hỗ trợ API | Ẩn nút tương ứng | "Cập nhật Zalo để dùng tính năng này" |
| Asset game tải lỗi | Thử lại; không trừ lượt khi chưa vào phiên | "Mạng yếu, đang tải lại game" |
Tiêu chí nghiệm thu
AC-ZMA-01Cho người chơi mới mở mini app, thì không có hộp thoại xin SĐT nào trước khi bắt đầu lượt chơi đầu.AC-ZMA-02Cho người chơi trúng quà và đồng ý cấp SĐT, thì hồ sơ có Zalo ID và SĐT liên kết, mã quà hiện trong 10 giây và có ZNS trong 60 giây.AC-ZMA-03Cho người chơi từ chối cấp SĐT, khi bấm "Nhận quà" lần nữa trong cùng phiên, thì không gọi lại hộp thoại Zalo mà mở ô nhập SĐT + OTP.AC-ZMA-04Cho người chơi follow OA, unfollow, follow lại trong cùng campaign, thì chỉ được cộng lượt follow 1 lần.AC-ZMA-05Cho link chia sẻ có mã người mời, khi bạn mở link, thì hệ thống ghi người được mời gắn đúng người mời và nguồn src=share.AC-ZMA-06Cho quản lý campaign tạo campaign mới cho kênh Zalo, thì campaign hiện trên mini app đang chạy mà không cần build mới.AC-ZMA-07Cho màn chơi bất kỳ trên Zalo iOS và Android, thì không có nút thao tác nào nằm dưới cụm nút "… / ×" của Zalo.AC-ZMA-08Cho QR booth có mã điểm activation, khi quét bằng Zalo, thì mở thẳng phòng chơi của điểm đó.
Câu hỏi mở
| # | Câu hỏi | Hỏi ai | Hạn | Trả lời |
|---|
| Q-ZMA-01 | Dùng OA nào: OA FPT Telecom chung hay OA riêng cho game? Ai sở hữu tài khoản Zalo Developer? | FCM / Truyền thông | | |
| Q-ZMA-02 | Zalo có cho tải mã game từ CDN ngoài gói không? Nếu không, mỗi game mẫu mới phải qua kiểm duyệt | IT | | |
| Q-ZMA-03 | Cho chơi lượt đầu khi chưa có SĐT, hay bắt cấp SĐT ngay từ đầu? (chạm Khung game) | FCM | | |
| Q-ZMA-04 | Lượt chia sẻ tính khi bấm chia sẻ hay khi bạn mở link? (quyết ở Khung game) | FCM / PM | | |
| Q-ZMA-05 | Ngân sách ZNS mỗi campaign; nhắc lượt có được gửi không? | FCM | | |
| Q-ZMA-06 | Mã người mời có thưởng cho người mời (referral) hay chỉ đo lường? | FCM | | |
Lịch sử thay đổi
| Bản | Ngày | Người sửa | Nội dung |
|---|
| 0.1 | 2026-11-11 | PM | Nháp khởi tạo |