Tài liệu kỹ thuậtSDK 1.1.0

Hướng dẫn outsource chuẩn · SDK 1.0

Tích hợp game với Game Platform

Chỉ dùng một facade GamePortal độc lập provider. Portal sở hữu context production về game, build, player và authentication; game chỉ sở hữu gameplay và gọi các capability đã công bố.

Hỗ trợ:HTML / JavaScriptCocos CreatorUnity WebGL

Tích hợp dành cho developer

01

Lấy SDK chính thức

Tải artifact bất biến có version trực tiếp từ Portal này. Đơn vị outsource không cần source repository của Portal và không tự build hoặc đổi tên một SDK không chính thức.

Tải Integration Kit 1.1.0 Tải gameportal-sdk.js SHA-256 bộ kit SHA-256 SDK

Đặt file standalone tại gameportal/gameportal-sdk.js trong static build. Bộ kit đầy đủ đã chứa file này, type, bridge Cocos/Unity, ví dụ và hướng dẫn bàn giao.

02

Chọn chế độ khởi chạy

Chế độ	Khởi tạo	Dùng khi
Chế độ	Khởi tạo	Dùng khi
Production được host	`GamePortal.init()`	Launch từ Public Play hoặc Kiểm thử production. Portal truyền context dùng một lần.
Preview build cô lập	`GamePortal.init()`	Portal truyền context PREVIEW dùng một lần. Chỉ player và storage cô lập theo build khả dụng.
Mock local	`GamePortal.init({ mode: 'mock', gameId? })`	Phát triển offline. ID tùy chọn chỉ tách dữ liệu local.
Legacy 0.8 preview	`Đã loại bỏ trong SDK 1.0`	Chỉ tham chiếu migration; không phát hành client-selected identity như production SDK 1.0.

Security boundary

Không đọc production game ID từ query string, import Nakama, gọi thẳng Portal API hay nhúng session, launch code, device ID, HTTP key hoặc database credential.

03

Quick start trong 5 phút

1

Tải Integration Kit chính thức hoặc gameportal-sdk.js standalone ở trên.

2

Đặt tại gameportal/gameportal-sdk.js và load trước game code.

3

Dùng init() khi hosted hoặc mock local tường minh—không tự fallback.

4

Kiểm tra capability rồi gọi ready → start → gameplay → end.

Hosted / preview

Mock local

index.html

<script src="/gameportal/gameportal-sdk.js"></script>
<script>
  await GamePortal.init();
  await GamePortal.game.ready({ build: "1.0.0" });
  await GamePortal.game.start();
</script>

04

Xác minh trước khi bàn giao

Chạy preflight có sẵn trên ZIP cuối. Công cụ chỉ chạy local, không upload, không cần credential và luôn trả mã ổn định kèm cách sửa.

Terminal

node tools/gameportal-preflight.mjs ./dist/my-game.zip

Sau init, chỉ lấy trạng thái SDK đã redacted. Gửi trạng thái này cùng normalized error code cho operator Portal—không gửi token, session, launch code, device ID hay provider response.

integration-status.js

try {
  await GamePortal.init(isLocal ? { mode: "mock" } : undefined);
  console.info("[GamePortal status]", GamePortal.debug.getStatus());
} catch (error) {
  console.error("[GamePortal error]", { code: error?.code ?? "UNKNOWN_ERROR" });
}

Giai đoạn	Chứng minh được	Không chứng minh được
Giai đoạn	Chứng minh được	Không chứng minh được
Mock local	Hình dạng lời gọi SDK, thứ tự lifecycle và gameplay local	Kết nối Portal, identity hoặc dữ liệu production bền vững
Preflight local	Cấu trúc ZIP, manifest, SDK, path và các luật compliance đã biết	Hosted runtime hoặc dữ liệu đã đến production
Portal Preview	Bootstrap cô lập thật, Player ID và storage riêng theo build	Leaderboard hoặc analytics production
Kiểm thử production	Save, score, lifecycle và analytics đã đến đúng game active	Gameplay hoặc điểm từ browser là trung thực

05

Lifecycle bắt buộc

1

init

2

ready

3

start

4

track / gameplay

5

end

lifecycle.js

await GamePortal.game.ready({ build: "1.0.0" });
await GamePortal.game.start();
await GamePortal.analytics.track("level_open", { level: 4 });
// SDK 1.1.0: an integer score >= 0 is also shown in the Portal's score popup (display only)
await GamePortal.game.end({ score: 1250 });

Await mọi bước. analytics.track cần ready; start cần ready; end cần session đang chạy và chỉ best-effort khi unload.

06

Các capability SDK

player

storage

leaderboard

game lifecycle

analytics

capabilities

Ví dụ

const player = GamePortal.player.get();
console.log(player.id, player.isAnonymous);

Kết quả mong đợi	Public player ID ổn định và cờ isAnonymous sau init.
Giới hạn / độ tin cậy	Identity SERVER_VALIDATED; không coi đây là login hay lộ provider identity.
Khi lỗi	SDK_NOT_READY: await init. Launch lại sau lỗi authentication/bootstrap.

Kết quả mong đợi	get trả null hoặc { key, value, version }; set trả entry đã lưu.
Giới hạn / độ tin cậy	Key 1–64; JSON ≤65.536 UTF-8 bytes; dữ liệu CLIENT_ASSERTED.
Khi lỗi	STORAGE_CONFLICT: đọc bản mới, merge có chủ đích, retry bằng opaque version đó.

Kết quả mong đợi	submit/top/rank trả public record có rank và score.
Giới hạn / độ tin cậy	Key chữ thường 1–64; score safe integer; top 1–100. Luôn CLIENT_ASSERTED và rewardEligible: false.
Khi lỗi	Kiểm tra isAvailable; sửa input _INVALID_; retry *_UNAVAILABLE sau, không bypass SDK.

Kết quả mong đợi	Một session ready/start/end có thứ tự và custom event dùng chung session ID.
Giới hạn / độ tin cậy	Properties: ≤32 scalar key và ≤8.192 bytes. end dùng fetch keepalive best-effort.
Khi lỗi	GAME_LIFECYCLE_INVALID là sai thứ tự; tạo page/game session mới sau end.

Kết quả mong đợi	track('level_open') được lưu thành custom:level_open cho Portal metrics.
Giới hạn / độ tin cậy	Tên chữ thường/số/gạch dưới, 1–48; properties CLIENT_ASSERTED và rate-limited.
Khi lỗi	Sửa ANALYTICS_INVALID_EVENT; retry ANALYTICS_UNAVAILABLE sau. Không gọi ingestion trực tiếp.

Kết quả mong đợi	Danh sách capability bật và metadata authority/reward ổn định.
Giới hạn / độ tin cậy	Trước init danh sách rỗng. Capability lạ/tắt phải degrade an toàn.
Khi lỗi	Guard module bằng isAvailable; CAPABILITY_UNAVAILABLE không phải lý do import provider SDK.

07

Bridge theo engine

HTML / JavaScript

Cocos Creator

Unity WebGL

examples/html

Load IIFE bundle và gọi window.GamePortal.

Bridge chỉ chuyển callback/type sang cùng browser facade; không nhận production identity hay tạo SDK thứ hai.

08

Boundary authority và anti-cheat

Server xác thực scope launch/session/game/build/player và hình dạng input, nhưng không thể chứng minh gameplay trong browser thực sự xảy ra. Player identity là SERVER_VALIDATED; storage, lifecycle, analytics và casual score là CLIENT_ASSERTED. Phase 2 chưa có capability SERVER_AUTHORITATIVE.

authority.js

const metadata = GamePortal.getCapabilityMetadata();
console.log(metadata.player.authority); // SERVER_VALIDATED
console.log(metadata.leaderboard.authority); // CLIENT_ASSERTED
console.log(metadata.leaderboard.rewardEligible); // false

Anti-cheat boundary

Không cấp currency, prize, entitlement hay giá trị payment từ CLIENT_ASSERTED data. Leaderboard record luôn trả rewardEligible: false.

09

Lỗi và cách khôi phục

Normalized code	Khi lỗi
Normalized code	Khi lỗi
`BOOTSTRAP_MISSING / BOOTSTRAP_TIMEOUT`	Mở/reload từ Portal để có launch mới; không tái dùng code có kết quả chưa rõ.
`BOOTSTRAP_INVALID / AUTHENTICATION_REJECTED`	Dừng và báo normalized code; không log launch/session data.
`SDK_NOT_READY / CAPABILITY_UNAVAILABLE`	Await init hoặc guard module bằng isAvailable.
`STORAGE_CONFLICT`	Đọc bản mới nhất, merge rồi retry bằng version trả về.
`_INVALID_`	Sửa input theo tài liệu trước khi retry.
`*_UNAVAILABLE`	Retry sau với backoff; không gọi thẳng provider/Portal endpoint.

10

Checklist trước khi bàn giao build

Source hosted gọi init() không có production identity input.

Mock mode tường minh và không tự chuyển thành hosted mode.

Source/build không có provider import, credential, launch code hay gọi thẳng Portal API.

Player, save qua reload, casual score, custom event và lifecycle đúng thứ tự hoạt động.

Static build dùng relative asset, HTTPS, responsive iframe và không phụ thuộc Portal DOM/cookie.

Bàn giao source, reproducible build, engine version, SDK version và run instructions.

Bàn giao cho operator

11

Xuất bản game: quy trình cho người mới

Quy trình bắt đầu sau khi developer outsource bàn giao source và static build. Mọi thay đổi production được thực hiện tại trang chi tiết game, phần Vận hành phát hành.

Tạo game → Tải ZIP → Kiểm định → Preview → Duyệt → Phát hành → Chạy → Xác minh → v2 → Rollback / Thu hồi

Bàn giao từ developer

Operator / admin

Bàn giao source và một static ZIP có thể build lại. Developer tích hợp SDK 1.0 và sửa lỗi compliance; không tự chọn production identity hay gọi API để publish.

Build game HTML, Cocos Creator hoặc Unity WebGL.

Mở index.html local và xác nhận mọi asset dùng đường dẫn tương đối.

Nén nội dung bên trong thư mục build, không nén bọc cả thư mục.

Bàn giao source, ZIP, engine/SDK version, lệnh build và ghi chú kiểm thử.

Cấu trúc ZIP đạt chuẩn

game-build.zip

game-build.zip
├── index.html                 # bắt buộc ở ZIP root
├── assets/                    # static asset dùng relative path
├── gameportal/
│   └── gameportal-sdk.js      # canonical SDK 1.0 bundle
└── gameportal-manifest.json   # metadata engine và SDK

Manifest HTML tối thiểu (dùng engine: cocos hoặc unity cho build tương ứng)

{
  "schemaVersion": 1,
  "engine": "html",
  "entrypoint": "index.html",
  "sdkVersion": "1.1.0"
}

ZIP root

ZIP root phải có index.html và gameportal-manifest.json, không bọc thêm một thư mục. Không chứa credential, source map lộ secret, server binary, symlink, absolute path hay provider SDK.

1

1. Tạo game

Danh sách game → Tạo game. Lưu public Game ID để hỗ trợ và tra audit.

Trạng thái game: INTEGRATION.

2

2. Tải build

Mở game → Vận hành phát hành → Build → Tải ZIP. Chờ row được refresh.

UPLOADING → VALIDATING. Không upload lặp khi build đang xử lý.

3

3. Kiểm định

Chọn Kiểm tra và đọc từng finding. PASS tạo immutable artifact; lỗi sẽ từ chối build.

PASS: READY. Lỗi: REJECTED; sửa source, build lại và upload thành version mới.

4

4. Preview

Với READY, mở shell Xem trước của Portal. Portal cấp launch PREVIEW dùng một lần trên game origin cô lập; test load, layout, input, gameplay, asset, save cô lập và console/network.

Preview chỉ có Player ID cô lập và Cloud Save theo build. Lifecycle, analytics và leaderboard production không khả dụng, chỉ được kiểm chứng tại Kiểm thử production sau publish.

5

5. Duyệt độc lập

Một user nội bộ khác xem report và preview, sau đó Duyệt hoặc Từ chối kèm lý do.

READY → APPROVED hoặc REJECTED. Bắt buộc duyệt độc lập; production self-approval trả SELF_APPROVAL_FORBIDDEN.

6

6. Phát hành

Tại build APPROVED, chọn Phát hành và xác nhận. Portal tạo immutable release và chuyển con trỏ PRODUCTION.

Build không thay đổi; game thành PUBLISHED. RELEASE_CONFLICT: refresh rồi mới thử lại.

7

7. Chạy và xác minh

Dùng Kiểm thử production cho operator, sau đó copy/mở public URL ổn định /play/{slug}. Xác minh identity, save, lifecycle, analytics, leaderboard và audit.

Player nhận launch context dùng một lần mới; không sao chép/dùng lại. URL public không đổi khi lên v2 hoặc rollback.

8

8. Phát hành v2

Sửa source, tạo ZIP mới rồi lặp upload → validate → preview → duyệt độc lập → publish.

v1 vẫn bất biến và tồn tại trong lịch sử rollback.

9

9. Khôi phục

Rollback đưa PRODUCTION về release cũ đủ điều kiện. Chỉ revoke build/release hoặc tắt game khi có sự cố, luôn kèm lý do.

Rollback tiếp tục phục vụ bản tốt; revoke/disable chủ động chặn launch bị ảnh hưởng.

Trạng thái / lỗi	Ý nghĩa	Cách xử lý
Trạng thái / lỗi	Ý nghĩa	Cách xử lý
`UPLOADING → VALIDATING`	Upload đã nhận; đang kiểm tra an toàn và compliance.	Chờ và refresh. Nếu không chuyển trạng thái, báo build ID; không bypass để publish.
`READY → APPROVED`	Validation PASS; reviewer độc lập chấp nhận đúng artifact.	Preview trước khi duyệt. Nếu bị từ chối, cần upload build mới.
`REJECTED`	Archive safety, compliance hoặc review thất bại.	Đọc finding/lý do, sửa source, build lại và upload version bất biến mới.
`SELF_APPROVAL_FORBIDDEN`	Người upload tự duyệt production build của mình.	Nhờ ADMIN hoặc OPERATOR nội bộ khác review.
`RELEASE_CONFLICT`	Một thao tác khác đã đổi production pointer.	Refresh release, xác minh bản Active rồi chọn lại thao tác mong muốn.
`Unavailable sau revoke`	Security control đang chặn build, release hoặc game.	Điều tra Audit; chỉ publish/rollback bản đủ điều kiện sau phê duyệt sự cố, không khôi phục byte đã revoke.

Checklist trước publish

Report PASS và đúng build đã được user khác APPROVE.

Runtime preview cô lập không có lỗi asset/input/console hay finding credential/provider/direct API.

Sau publish, Kiểm thử production chứng minh Player ID, save qua reload, lifecycle, analytics và casual leaderboard trước khi chia sẻ URL public.

Đã ghi version, changelog, engine/SDK version và rollback target.

Publisher đã xác nhận release đang Active.

Xác minh sau publish

Danh sách game hiển thị PUBLISHED và đúng release là Active.

Play mở đúng immutable build trên game origin.

Session mới chạy init → ready → start → end không có console error.

Operational Audit có evidence upload, review, publish và launch liên quan.

Release tốt trước đó vẫn đủ điều kiện rollback.

Rollback hay thu hồi

Dùng Rollback khi có functional regression và muốn tiếp tục phục vụ release cũ đủ điều kiện. Dùng Thu hồi build/release hoặc Tắt game khi bị compromise, vi phạm policy hoặc có nội dung nguy hiểm; đây là emergency control, không phải cách quản lý version thông thường.

Tham chiếu & hỗ trợ

12

Game mẫu tham chiếu

GamePortal Hello World
Đọc một file từ trên xuống để hiểu tích hợp đầy đủ nhỏ nhất.

examples/hello-world/app.js

Game mẫu Memory Match
Sau đó đọc sample có adapter để đưa cùng contract vào kiến trúc game thực tế.

examples/reference-game

Thứ tự đọc đề xuất

1

game/deck.js → round.js → scoring.js

2

platform/gameportal-platform.js

3

platform/create-platform.js

4

app.js → index.html → styles.css

5

gameportal-manifest.json → build:memory-match

13

Gói thông tin hỗ trợ

Gửi tên/public ID game, SDK version, normalized error code, browser/engine version, mode (hosted preview, production hoặc mock) và bước tái hiện. Không gửi token, launch code, session, device ID hay credential.

integration-kit/QUICKSTART.md · integration-kit/TROUBLESHOOTING.md · docs/SDK_1_0_BOOTSTRAP.md