Riot Games Developer Portal Ready
Riot Production API Key & RSO Application Guide
Copy-paste English submission templates & Vietnamese compliance checklist for developer.riotgames.com.
Monetization Compliance
Enforces ≥70% of entry fees into Prize Pool, ≥20 participants, and Free Tier access.
VALORANT RSO Opt-In
Players must explicitly grant OAuth RSO consent before their VAL match stats are displayed.
Game Integrity Guardrails
No hidden MMR/ELO replacement calculator, no pre-game scouting of non-opted-in players.
docs/RIOT_API_APPLICATION.md
# Riot Games Developer Portal Application Package & Submission Manual
**Document Version:** 1.0.0 (Production Release)
**Target Platform:** Riot Developer Portal (`https://developer.riotgames.com/`)
**Application Tier:** Production API Key & Tournament API v5 (`tournament-v5`) + VALORANT RSO / Match Access (`val-match-v1`)
**Project Title:** Grassroots & Semi-Pro Esports Tournament Platform (Vietnam & SEA)
**Applicable Regions:** Vietnam (`VN2`), Southeast Asia (`SEA`), Asia-Pacific (`AP`)
**Repository Working Directory:** `C:\riot_tournament_platform`
---
## Executive Overview & Compliance Mandates
This document serves as the authoritative, end-to-end application package and operations manual for securing a **Production API Key**, **League of Legends Tournament API (`tournament-v5`)**, and **VALORANT RSO & Match Access (`val-match-v1`)** from Riot Games.
It is organized into three distinct sections:
1. **Section 1: Step-by-Step Portal Registration Workflow**: Technical instructions for registering the application, hosting the domain verification file (`riot.txt`), and initiating the submission pipeline.
2. **Section 2: Exact English Submission Application Text (Copy-Paste Ready)**: Standardized, review-optimized answers tailored to Riot Games Developer Relations (DevRel) review criteria, strictly adhering to Riot General Policies, Community Competition Guidelines, and VALORANT Game Policies.
3. **Section 3: Vietnamese Practical Guide (Hướng Dẫn Nộp Đơn Dành Cho Chủ Dự Án / Admin)**: Exhaustive Vietnamese translations, explanatory rationales, interview defense strategies (RFI handling), and key lifecycle maintenance instructions for project administrators.
---
# Section 1: Step-by-Step Portal Registration & Domain Verification Workflow
Follow these chronological steps to submit the platform application to the Riot Games Developer Portal.
### Step 1.1: Prerequisite Checklist
Before initiating the application, ensure the following infrastructure components are deployed and publicly accessible:
1. **Official Registered Domain**: An active domain or subdomain (e.g., `https://aegis-tournaments.vn` or `https://tournament.yourdomain.com`). Riot rejects applications using raw IP addresses, localhost, or unauthenticated HTTP URLs.
2. **Valid SSL/TLS Certificate**: HTTPS must be active and valid on the domain (e.g., via Let's Encrypt or Cloudflare SSL).
3. **Domain Ownership Verification File**: Deploy `public/riot.txt` to the web server root so that it is publicly reachable via HTTP GET at:
```http
GET https://<your-domain>/riot.txt
```
- Must return HTTP 200 OK.
- Header `Content-Type: text/plain; charset=utf-8`.
- File content must contain your assigned or generated verification token (see Step 1.3).
4. **Interactive Prototype / Live Web Showcase**:
- The standalone interactive HTML prototype (`prototype/index.html`) or live Next.js web application must be reachable so that Riot reviewers can immediately test user flows without installing software.
5. **Public Webhook Callback Endpoint**:
- For `tournament-v5` callbacks, an HTTPS endpoint must be configured (e.g., `https://<your-domain>/api/riot/tournament/callback`) ready to receive Riot server POST requests with HTTP 200 responses.
---
### Step 1.2: Portal Login & Product Registration
1. Navigate to the official Riot Developer Portal: [https://developer.riotgames.com/](https://developer.riotgames.com/).
2. Log in using the dedicated **Riot Account** belonging to the organizing entity or technical lead. (Ensure this account has an active email address and Two-Factor Authentication enabled).
3. Click on your profile icon in the top right corner and navigate to **My Products** (`https://developer.riotgames.com/app/my-products`).
4. Click the **Register Product** button.
5. In the product type selection screen, choose:
- **Production API Key** (Do *not* choose "Personal API Key" which expires every 24 hours and lacks Tournament API access).
6. Enter the **Product Name**:
```
Grassroots & Semi-Pro Esports Tournament Platform (Vietnam & SEA)
```
*(Or your production platform name, e.g., "Aegis Esports Tournament Platform")*.
---
### Step 1.3: Domain Verification (`riot.txt`)
Riot Games requires cryptographic proof of domain ownership to prevent unauthorized API impersonation:
1. When prompted in the portal for **Product URL**, enter your fully qualified domain name:
```
https://aegis-tournaments.vn
```
2. The portal will generate or request a verification token string in the format:
```
riot:app:9c2b8e4f-71a0-4d5e-b83c-62e91d0f8a34
```
3. Update `C:\riot_tournament_platform\public\riot.txt` with the exact token displayed by Riot.
4. Verify local and remote accessibility:
```bash
# Test using cURL:
curl -I https://aegis-tournaments.vn/riot.txt
curl https://aegis-tournaments.vn/riot.txt
```
5. Click **Verify Domain** inside the Riot Developer Portal. Upon successful HTTP GET verification, a green checkmark will appear next to your domain.
---
### Step 1.4: Selecting Requested APIs & Scope Escalation
Select the required game titles and endpoint groups. For this tournament engine, request:
1. **Core Identity & Summoner APIs**:
- `account-v1`: To resolve Riot IDs (`gameName#tagLine`) to immutable PUUIDs.
- `summoner-v4`: To verify LoL account levels and summoner icons.
- `league-v4`: To verify ranked tiers and LP for rank-capped brackets (e.g., Gold-only or Emerald-capped tournaments).
2. **Match & History APIs**:
- `match-v5`: To audit completed match metadata and verify roster participant PUUIDs.
3. **Tournament API Licensing**:
- `tournament-v5`: Required for generating official LoL custom game tournament codes and receiving automated game completion callbacks.
- `tournament-stub-v5`: Development sandbox for testing lobby generation and callbacks locally without consuming production server resources.
4. **VALORANT APIs & RSO Scope**:
- `val-content-v1`: To fetch active competitive map lists and game asset metadata for the Map Veto system.
- `val-match-v1`: To fetch round outcomes and player combat statistics for opted-in participants.
- **Riot Sign-On (RSO)**: Request RSO Client ID and Secret with scopes `openid` and `offline_access` for explicit player privacy consent.
---
### Step 1.5: Submitting Application & Review Timeline
1. Copy and paste the corresponding English fields from **Section 2** below into each designated textarea in the portal form.
2. Review all fields to ensure no placeholder text remains.
3. Submit the application.
4. Review lifecycle:
- **Status: In Review**: Typical turnaround is **5 to 15 business days**.
- **Status: Request for Information (RFI)**: Riot DevRel may reply with clarifying questions via email or portal notification. Refer to **Section 3.4** for prepared responses.
- **Status: Approved**: Production API Key is generated with rate limits assigned (`500:10, 30000:600`), and your provider ID is provisioned for `tournament-v5`.
---
# Section 2: Exact English Submission Application Text (Copy-Paste Ready)
The following subsections contain the verbatim English text optimized for direct copy-pasting into each field of the Riot Games Developer Portal application form.
---
### 2.1 General Application Metadata
#### Product Name:
```text
Grassroots & Semi-Pro Esports Tournament Platform (Vietnam & SEA)
```
#### Public Product URL:
```text
https://aegis-tournaments.vn
```
#### Standalone Prototype / Interactive Demo URL:
```text
https://aegis-tournaments.vn/prototype
```
#### GitHub / Technical Architecture Repository (Optional / If Requested):
```text
https://github.com/aegis-esports/riot-tournament-platform
```
---
### 2.2 Product Description
*Paste this text into the **"Product Description"** field:*
```text
The Grassroots & Semi-Pro Esports Tournament Platform is an automated, web-based tournament management platform engineered specifically for collegiate gaming clubs, university esports societies, and cyber-cafe organizers across Vietnam and Southeast Asia (SEA).
The platform automates the end-to-end competition lifecycle for League of Legends (PC) and VALORANT:
1. Tournament Administration: Streamlines bracket generation (Single and Double Elimination), participant check-ins, seed placement, and dynamic prize pool governance.
2. Riot Games LoL Tournament Integration: Integrates directly with the Riot Games Tournament API (tournament-v5) to automatically provision official custom game tournament codes, pre-configure match settings (Summoner's Rift, Tournament Draft, 5v5), and ingest authoritative post-game server callbacks to advance brackets without manual referee intervention.
3. Competitive VALORANT Map Veto: Features an interactive 7-map Ban/Pick and Side Selection (Attack/Defense) engine with synchronized countdown timers, audio cues, and audit logging for BO1 and BO3 series.
4. Competitive Integrity & Anti-Smurf Suite: Protects amateur, collegiate, and rank-capped brackets through a heuristic risk scoring engine (evaluating winrate spikes, tier discrepancies between queues, and account level freshness) and enforces strict Post-Match PUUID Roster Lock audits to detect unregistered ringers and account sharing.
5. Grassroots Broadcast & Media Engine: Delivers a dedicated, transparent OBS broadcast overlay route for amateur student livestreams, as well as an automatic HTML5 Canvas MVP graphic card generator celebrating player achievements.
The platform operates under a strict non-commercial, community-first ethos: it provides full free access for community organizers, adheres to the >=70% prize pool allocation rule, enforces player privacy through mandatory Riot Sign-On (RSO) opt-in, and displays Riot Games' required legal non-endorsement disclaimers across all user interfaces.
```
---
### 2.3 Target Audience
*Paste this text into the **"Target Audience"** field:*
```text
The primary target audience comprises three key grassroots esports segments across Vietnam and Southeast Asia:
1. University & Collegiate Esports Societies: Student gaming clubs (e.g., Hanoi University of Science & Technology Gaming Club, RMIT Cyber Tigers, Bach Khoa Gaming, Da Nang University of Science and Technology Esports) that organize inter-university leagues, campus cups, and freshers' tournaments on limited budgets.
2. Grassroots Cyber-Cafe & LAN Center Operators: Community internet cafe chains and local LAN centers (e.g., Vikings Gaming, CyberCore, Star Gaming Arena) hosting amateur weekend showdowns and community leagues to foster local gaming culture.
3. Amateur & Semi-Pro Players: Competitive players looking for verified, fair-play tournaments with enforced rank ceilings (e.g., Gold-only or Emerald-capped tournaments) free from high-ELO smurfs, ringers, and bracket fraud.
```
---
### 2.4 Approved Use Cases & Functional Matrix
*Paste this text into the **"Approved Use Cases / How will your product use the Riot API?"** field:*
```text
The platform utilizes Riot Games APIs strictly for competitive administration, match verification, and fair-play tournament operation across the following approved use cases:
1. Player Registration & Verification:
- Uses account-v1 to resolve player Riot IDs (gameName#tagLine) to permanent, immutable PUUIDs during team roster creation.
- Uses summoner-v4 and league-v4 to verify account level (confirming minimum level requirements) and current ranked tier/division (Solo/Duo and Flex) to enforce tournament eligibility criteria and rank ceilings.
2. Official LoL Custom Lobby Automation (Tournament API v5):
- Uses tournament-v5 to register tournament providers and tournaments.
- Automatically generates unique tournament codes with custom game parameters (Summoner's Rift, Tournament Draft, team size 5, all spectators permitted).
- Ingests Riot server HTTP POST callbacks upon game completion, automatically verifying match outcome (winning team, match ID, duration) and advancing tournament brackets.
3. Post-Match PUUID Roster Lock Auditing:
- Uses match-v5 (LoL) and val-match-v1 (VALORANT) to extract actual participant PUUIDs from completed game records.
- Compares match participants against pre-locked tournament rosters using a strict set-difference algorithm:
If any participant PUUID does not match the registered team roster or registered substitute, the match is flagged as a ROSTER_LOCK_VIOLATION, automatic bracket advancement is halted, and tournament administrators are alerted to take disciplinary action.
4. Fair Play & Anti-Smurf Risk Analysis:
- Calculates a multi-factor Smurf Risk Score (0–100) prior to tournament seeding based on public match history anomalies (recent winrate spikes >75%, Solo vs. Flex tier discrepancies >=3 tiers, account level <=50, and abrupt champion pool role shifts).
- Flags suspicious accounts for human organizer review to safeguard rank-restricted amateur brackets.
5. VALORANT Competitive Map Veto:
- Uses val-content-v1 to fetch the active competitive map rotation.
- Provides a real-time, turn-based Map Veto room (Ban/Pick/Side Selection) for BO1 and BO3 tournament matches.
6. Broadcast & Media Production:
- Renders live match scores, team names, map veto results, and player stats on a transparent OBS browser source overlay route for community student broadcasts.
```
---
### 2.5 Monetization Policy Compliance
*Paste this text into the **"How is your product monetized? / Commercialization Policy"** field:*
```text
The platform is designed and built in strict compliance with the Riot Games Community Competition Guidelines, General Developer Policies, and Intellectual Property Policies:
1. Free Tier for Community Organizers:
- The core tournament platform, bracket engine, registration portal, veto room, and broadcast overlays are 100% free for student clubs and community organizers. There are no mandatory paywalls, subscription fees, or locked features.
2. Programmatic Enforcement of the >=70% Prize Pool Rule:
- In accordance with Riot's Community Tournament Guidelines, if an organizer chooses to collect an entry fee, the platform programmatically enforces that at least 70% of all gross entry fees collected MUST be allocated directly into the player prize pool.
- Enforcement Formula:
Gross Entry Fees = Entry Fee × Expected Teams × Team Size
Minimum Allowed Prize Pool = Gross Entry Fees × 0.70
- If an organizer inputs a prize pool lower than 70% of collected entry fees, the tournament creation wizard programmatically disables submission, returns an HTTP 422 error, and displays the exact prize pool deficit required to achieve compliance.
3. Compliance with Riot Community Prize Pool Caps:
- Total prize pools for any single community tournament are capped at $10,000 USD (approx. 250,000,000 VND).
- Organizers are tracked to ensure cumulative annual prize pools remain well below the $50,000 USD limit for community licenses. Organizers exceeding these limits are instructed to obtain an official Riot Games Custom License.
4. Participant Minimum Threshold Guardrail:
- Tournaments with entry fees must have at least 20 individual participants (e.g., minimum 4 teams of 5v5). The system rejects entry fees for events under 20 participants.
5. Prohibited Tournament Naming Filter:
- The platform automatically validates tournament titles against a blacklist of restricted Riot esports trademarks: "Championship", "League", "Season", "Pro", "Masters", "VCS", "VCT", "LCS", "LEC", "LCK", "Worlds", and "Olympic".
- Organizers using prohibited keywords are blocked and prompted with approved alternatives ("Cup", "Clash", "Open", "Showdown", "Series", "Invitational").
6. Strict Prohibition of Data Resale:
- The platform does not sell Riot Games API data, player statistics, match history, or leaderboard information to third parties under any circumstances.
7. Prohibited Sponsorship Categories:
- The built-in B2B sponsorship directory explicitly blocks prohibited sponsor categories: gambling, sports betting, alcohol, tobacco, vaping, firearms, cryptocurrency, NFTs, adult entertainment, and unauthorized account boosting/selling services. Only compliant partners (gaming peripherals, energy drinks, snacks, cafes, student unions) are permitted.
```
---
### 2.6 Game Integrity & Fair Play Compliance
*Paste this text into the **"Game Integrity & Player Privacy Compliance"** field:*
```text
The platform is committed to upholding competitive integrity and fair play, adhering strictly to Riot Games Game Policies:
1. No In-Game Scouting or Real-Time Overlays:
- The platform does not provide any downloadable in-game client overlays, real-time memory reading tools, or pre-game scouting tools that reveal opponent habits or champion selections during live matchmaking or Champion Select.
- All data display is strictly confined to external tournament administrative web pages and post-match tournament recaps.
2. No Custom MMR or ELO Replacement:
- The platform does not invent, calculate, or display any proprietary "True MMR", "Hidden ELO", or replacement skill ratings intended to supersede or undermine Riot's official ranked tiers.
- Player ranks are displayed verbatim as reported by league-v4 (e.g., "Emerald II", "Diamond IV").
3. Anti-Smurf Heuristics as Administrative Advisory:
- The platform's Anti-Smurf Risk Score is an internal advisory heuristic used solely by tournament organizers to identify potential smurf accounts in rank-capped amateur tournaments (e.g., a Level 32 account with a 95% winrate entering a Silver/Gold tournament).
- The score does not alter official player MMR and does not ban players from Riot services; it simply alerts tournament administrators to conduct manual eligibility reviews (such as verifying student identity).
4. Zero Tolerance for Account Sharing and Boosting:
- The platform's Post-Match PUUID Roster Lock automatically compares match participant PUUIDs against pre-registered roster PUUIDs to prevent account ringing, ghosting, or unauthorized substitutions.
5. Mandatory Visible Legal Disclaimer:
- Every public-facing page, broadcast overlay, and exported MVP graphic card displays the verbatim legal boilerplate mandated by Riot Games:
"[Platform Name] isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. Riot Games, and all associated properties are trademarks or registered trademarks of Riot Games, Inc."
```
---
### 2.7 Riot Sign-On (RSO) Opt-In & Player Privacy Workflow
*Paste this text into the **"Riot Sign-On (RSO) & Player Privacy"** field:*
```text
In strict adherence to Riot Games' VALORANT Game Policy and global privacy standards (GDPR / PDPA), the platform implements an explicit, voluntary Riot Sign-On (RSO) opt-in mechanism before capturing, processing, or publicly displaying any player statistics or match histories:
1. Default Privacy Barrier:
- By default, all VALORANT player stats, combat scores, and match histories are hidden.
- If a player has not explicitly opted in, public tournament leaderboards and profile pages display a privacy badge: "Player stats hidden - Pending player RSO consent (Riot Privacy Policy)."
2. The 4-Step Player Opt-In Sequence:
- Step 1 (User Action): The player clicks "Connect Riot ID & Sign In" on their profile or tournament check-in page.
- Step 2 (Explicit Consent Modal): Before being redirected to Riot's OAuth2 login, a dedicated Privacy Consent Modal clearly explains the exact scope of data collected:
"By opting in with Riot Sign-On (RSO), you grant permission to access your Riot ID, Match History, and Ranked Statistics solely for tournament bracket placement, seeding, anti-smurf verification, and live match broadcasts. You can revoke this permission at any time in your profile settings."
- Step 3 (RSO OAuth2 Flow): The player is redirected to Riot's official authentication page (https://auth.riotgames.com/authorize). Upon authenticating, Riot returns an authorization code exchanged server-side for access and refresh tokens.
- Step 4 (Audit Trail Persistence): The platform securely stores the consent metadata:
- rsoOptedIn: true
- consentGivenAt: ISO 8601 UTC timestamp
- consentVersion: "v1.2"
- puuid: Player's encrypted immutable identifier
3. User Revocation & Right to Be Forgotten:
- Players can revoke consent at any time with a single click in their Account Settings ("Revoke Riot Access").
- Upon revocation, the stored OAuth tokens are purged, rsoOptedIn is flipped to false, and all public match statistics are immediately suppressed from tournament views.
```
---
### 2.8 Requested API Endpoints & Detailed Justification Table
*Paste this table and justification into the **"Requested Endpoints & Technical Justification"** field:*
| Endpoint Group | Specific HTTP Methods & Routes | Primary Technical Justification |
| :--- | :--- | :--- |
| **`account-v1`** | `GET /riot/account/v1/accounts/by-riot-id/{gameName}/{tagLine}`<br>`GET /riot/account/v1/accounts/by-puuid/{puuid}` | Resolves user-submitted Riot IDs to permanent, immutable PUUIDs during player registration and team roster formation. PUUIDs are required for all subsequent League and VALORANT API queries. |
| **`summoner-v4`** | `GET /lol/summoner/v4/summoners/by-puuid/{encryptedPUUID}` | Retrieves summoner profile icon ID and summoner level for League of Legends. Used to verify that players meet minimum account level criteria (e.g., Level 30+ for competitive play) and display verified profile icons. |
| **`league-v4`** | `GET /lol/league/v4/entries/by-summoner/{encryptedSummonerId}` | Retrieves official ranked tiers, divisions, and League Points (LP) for Solo/Duo and Flex queues. Essential for verifying player eligibility in rank-restricted community tournaments (e.g., "Iron to Gold Cup" or "Emerald Cap"). |
| **`match-v5`** | `GET /lol/match/v5/matches/by-puuid/{puuid}/ids`<br>`GET /lol/match/v5/matches/{matchId}` | Fetches match history and detailed participant statistics for completed tournament games. Used to verify participant PUUIDs against locked rosters (anti-ringer check) and compute tournament MVP statistics. |
| **`tournament-v5`** | `POST /lol/tournament/v5/providers`<br>`POST /lol/tournament/v5/tournaments`<br>`POST /lol/tournament/v5/codes`<br>`GET /lol/tournament/v5/codes/{tournamentCode}` | Registers the platform as an official tournament provider, provisions tournament instances, and generates custom game tournament codes with locked game settings (Tournament Draft, Summoner's Rift). Ingests asynchronous game completion webhooks. |
| **`val-content-v1`** | `GET /val/content/v1/contents` | Retrieves the authoritative, up-to-date list of active competitive maps, agents, and game modes for VALORANT, ensuring the Map Veto room always reflects the current competitive map pool. |
| **`val-match-v1`** | `GET /val/match/v1/matches/{matchId}` | Retrieves comprehensive match outcome details, round-by-round results, team scores, and individual combat statistics for consented players in collegiate VALORANT tournaments. |
---
### 2.9 Rate Limit Modeling & Mathematical Traffic Projections
*Paste this text into the **"Rate Limit Requirements & Architecture Scalability"** field:*
```text
1. Requested Rate Limit Tier:
- App Rate Limits: 500 requests per 10 seconds and 30,000 requests per 10 minutes (Standard Production Key Tier).
2. Architectural Traffic Modeling:
- Baseline Tournament Scale: The platform models peak weekend activity supporting up to 32 concurrent community and collegiate tournaments across Vietnam and SEA.
- Each tournament features an average of 8 to 16 teams (5v5 rosters = 40 to 80 players per tournament).
- Peak concurrent live matches across all tournaments: 32 concurrent matches (320 active players simultaneously in lobbies).
3. Mathematical API Consumption Breakdown:
a) Player Registration & Check-in (Pre-Tournament Phase):
- 320 players register over a 2-hour window.
- Per player API calls: 1x account-v1 + 1x summoner-v4 + 1x league-v4 = 3 calls per player.
- Total calls = 320 × 3 = 960 calls spread across 120 minutes = 8 requests per minute (0.13 req/sec).
b) Tournament Lobby Code Provisioning:
- 32 concurrent matches require 32 tournament codes generated in batches of 1 per match.
- Batch API calls: 1 call per match = 32 calls total, executed asynchronously over 15 minutes.
c) Post-Match Ingestion & Webhook Architecture:
- The platform utilizes Riot's asynchronous HTTP POST webhooks for tournament-v5 callbacks.
- When a LoL tournament game finishes, Riot servers push the match completion payload directly to our webhook endpoint.
- Zero polling overhead: The platform NEVER polls match status in a loop.
- Upon webhook receipt, exactly 1x match-v5 query is executed to retrieve participant details for roster lock auditing.
- Peak match conclusions: 32 matches concluding over a 60-minute window = 32 calls / 60 min = ~0.5 requests per minute.
d) Anti-Smurf Advisory Analysis:
- Executed once per registered player at check-in (fetching 20 recent match IDs and summary data).
- Queued via background worker with rate-pacing throttled to a maximum of 10 requests per second.
4. Caching & Request Minimization Strategies:
- Redis / In-Memory Tier Caching:
* Summoner profiles (summoner-v4) and Ranked entries (league-v4) are cached with a 15-minute (900s) TTL. Repeated profile views during a tournament hit 100% cache.
* VALORANT competitive content (val-content-v1) is cached for 24 hours (86,400s).
* Completed match records (match-v5 and val-match-v1) are immutable: once fetched and audited, they are permanently stored in the local PostgreSQL database and NEVER re-queried from Riot servers.
- HTTP 429 Interception & Exponential Backoff:
* The backend HTTP client automatically monitors X-App-Rate-Limit-Count and Retry-After headers, gracefully queuing outgoing requests before limits are breached.
5. Conclusion:
- Even under peak stress (simultaneous check-ins for 32 tournaments), the platform's sustained traffic will not exceed 40 requests per 10 seconds, which represents less than 8% of the requested 500 req/10s limit. The requested tier provides essential headroom for regional scale and prevents dropped tournament lobby codes.
```
---
# Section 3: Vietnamese Practical Guide (Hướng Dẫn Nộp Đơn Dành Cho Chủ Dự Án / Admin)
Phần này cung cấp toàn bộ hướng dẫn thực tế, giải thích cặn kẽ bằng tiếng Việt dành riêng cho ban quản trị và kỹ sư vận hành dự án tại Việt Nam.
---
### 3.1 Chuẩn bị Kỹ thuật & Hạ tầng Trước khi Nộp Đơn
Trước khi bắt đầu bấm nộp đơn trên cổng Riot Games Developer Portal, bạn cần chuẩn bị đầy đủ các điều kiện kỹ thuật bắt buộc dưới đây để tránh bị Riot từ chối ngay từ vòng duyệt tự động:
#### 1. Tên miền và Chứng chỉ SSL/TLS (Bắt buộc)
* Riot Games **tuyệt đối không chấp nhận** IP tĩnh thô (ví dụ: `http://103.x.x.x`) hoặc tên miền miễn phí kém uy tín.
* Bạn cần chuẩn bị tên miền chính thức của dự án (ví dụ: `aegis-tournaments.vn`, `lolvietnam.edu.vn`, v.v.).
* Bắt buộc phải bật **HTTPS** với chứng chỉ SSL hợp lệ (Let's Encrypt hoặc Cloudflare). Khi truy cập `https://<domain>` trình duyệt phải hiển thị ổ khóa xanh an toàn.
#### 2. Đặt file xác thực tên miền `riot.txt`
* Cổng Developer Portal của Riot sử dụng cơ chế kiểm tra tên miền tương tự Google Search Console: họ sẽ gửi HTTP GET request đến `https://<domain-cua-ban>/riot.txt`.
* File này đã được chuẩn bị sẵn tại:
`C:\riot_tournament_platform\public\riot.txt`
* Trong Next.js, bất kỳ file nào nằm trong thư mục `public/` sẽ tự động được phục vụ trực tiếp tại root URL (`/`).
* Khi cấu hình Nginx (xem file `deploy/nginx.conf`), hãy đảm bảo route `/riot.txt` trả về `Content-Type: text/plain` và mã phản hồi là `HTTP 200 OK`.
#### 3. Đường dẫn Webhook cho LoL Tournament Callback
* Khi một trận đấu LoL kết thúc, server game của Riot sẽ chủ động gọi HTTP POST về máy chủ của bạn để thông báo kết quả.
* Endpoint mặc định được cấu hình trong nền tảng là:
`https://<domain-cua-ban>/api/riot/tournament/callback`
* Đảm bảo server mở cổng 443 ra ngoài Internet và không bị chặn bởi tường lửa hoặc Cloudflare WAF/Bot Fight Mode.
#### 4. Bản Demo Hoạt động (Prototype Showcase)
* Riot DevRel **rất chú trọng trải nghiệm thực tế**. Họ muốn thấy giao diện người dùng trông như thế nào trước khi cấp quyền truy cập production.
* Bạn có thể tải file `prototype/index.html` lên hosting (ví dụ: `https://<domain-cua-ban>/prototype`) hoặc dẫn link trực tiếp đến trang web Next.js đang chạy.
---
### 3.2 Hướng Dẫn Điền Đơn Chi Tiết Từng Trường (Field-by-Field)
Khi đăng nhập vào `https://developer.riotgames.com/` và chọn **Register Product** -> **Production API Key**, hãy sao chép các thông tin tương ứng từ **Section 2** vào các ô nhập liệu:
| Tên trường trên cổng Riot | Nội dung cần điền | Mục copy trong Section 2 | Lưu ý quan trọng |
| :--- | :--- | :--- | :--- |
| **Product Name** | `Grassroots & Semi-Pro Esports Tournament Platform (Vietnam & SEA)` | Mục 2.1 | Có thể thay bằng tên thương hiệu của bạn (ví dụ: *Aegis Esports Hub*), nhưng phải thể hiện rõ tính chất cộng đồng/bán chuyên. |
| **Product URL** | `https://<ten-mien-cua-ban>.vn` | Mục 2.1 | Bắt buộc là link HTTPS thực tế, có gắn file `riot.txt`. |
| **Product Description** | Copy toàn bộ văn bản tiếng Anh mô tả sản phẩm | Mục 2.2 | Đoạn này giải thích 5 trụ cột: Quản lý giải, Tích hợp Tournament-v5, Veto VALORANT, Chống Smurf và Overlay livestream. |
| **Target Audience** | Copy đoạn tiếng Anh về đối tượng người dùng | Mục 2.3 | Nhấn mạnh vào 3 nhóm: CLB thể thao điện tử sinh viên/học sinh, chuỗi Cyber Cafe / Cyber Gaming và cộng đồng game thủ phong trào. |
| **How will your product use the Riot API?** | Copy toàn bộ mục Approved Use Cases | Mục 2.4 | Nêu rõ từng chức năng ứng với từng API, chứng minh bạn không scrape dữ liệu bừa bãi. |
| **Monetization / Commercial Policy** | Copy toàn bộ mục Monetization Policy Compliance | Mục 2.5 | **Đây là mục quan trọng nhất!** Phải giữ nguyên cam kết quy tắc 70% tiền thưởng (`>=70% Prize Pool`), miễn phí cho người dùng cơ bản và không bán dữ liệu Riot. |
| **Game Integrity & Player Privacy** | Copy mục Game Integrity Compliance | Mục 2.6 | Cam kết không làm overlay gian lận soi đối thủ trong trận, không tính điểm ELO/MMR thay thế Riot, và luôn có dòng bản quyền Riot ở footer. |
| **RSO & User Privacy Flow** | Copy mục RSO Opt-In & Player Privacy | Mục 2.7 | Trình bày luồng 4 bước người chơi VALORANT phải tự tay bấm xác nhận (Consent Modal) trước khi hiển thị dữ liệu lịch sử đấu. |
| **APIs Requested** | Tích chọn các API và dán bảng giải trình | Mục 2.8 | Chọn đủ: `account-v1`, `summoner-v4`, `league-v4`, `match-v5`, `tournament-v5`, `val-content-v1`, `val-match-v1`. |
| **Rate Limit Justification** | Copy bài toán tính toán chịu tải và caching | Mục 2.9 | Đưa ra con số cụ thể về 32 giải đấu đồng thời, tính năng webhook không cần polling và Redis cache 15 phút. |
---
### 3.3 Chuẩn bị Tài liệu Minh Họa (Prototype & Video Demo)
Riot Developer Support thường ưu tiên duyệt nhanh các đơn có video quay màn hình (Loom, YouTube Unlisted hoặc Google Drive công khai). Bạn nên chuẩn bị một video ngắn từ **2 đến 3 phút** quay các tính năng sau từ bản prototype (`prototype/index.html`) hoặc ứng dụng web:
1. **Luồng RSO Opt-In**: Bấm nút kết nối Riot ID, hiển thị bảng thông báo quyền riêng tư (Consent Modal) với đầy đủ điều khoản và nút chấp thuận.
2. **Tạo giải đấu với quy tắc 70%**:
- Thử nhập Lệ phí: 100.000 VNĐ, 16 đội (80 người chơi) -> Tổng thu 8.000.000 VNĐ.
- Nhập Tiền thưởng: 4.000.000 VNĐ (chỉ 50%) -> Hệ thống báo lỗi đỏ: *"Tiền thưởng phải đạt tối thiểu 70% (5.600.000 VNĐ). Thiếu 1.600.000 VNĐ"*.
- Sửa thành 6.000.000 VNĐ -> Hệ thống báo hợp lệ (Xanh).
3. **Bộ lọc từ khóa cấm**: Thử đặt tên giải là *"Hanoi Cyber Championship 2026"* -> Hệ thống báo vi phạm từ khóa *"Championship"* và gợi ý đổi thành *"Hanoi Cyber Clash"*.
4. **Quét Anti-Smurf & Roster Lock**: Cho thấy bảng tính điểm rủi ro Smurf (0-100) dựa trên tỷ lệ thắng, chênh lệch rank Solo/Flex và cấp độ tài khoản, cùng tính năng khóa danh sách đội hình (Roster Lock) phát hiện nick lạ vào phòng.
5. **Phòng Cấm/Chọn Map VALORANT**: Thao tác cấm/chọn bản đồ BO1/BO3 theo lượt, chọn phe Tấn Công / Phòng Thủ với đồng hồ đếm ngược.
6. **Chân trang Bản quyền (Legal Disclaimer)**: Cuộn xuống chân trang chỉ rõ dòng tuyên bố bản quyền chuẩn của Riot Games.
---
### 3.4 Chiến lược Trả lời Phỏng vấn / Phản hồi Yêu cầu Bổ sung từ Riot DevRel (RFI Handling)
Trong quá trình xét duyệt, chuyên viên Riot DevRel thường gửi email yêu cầu làm rõ một số điểm nhạy cảm. Dưới đây là các câu hỏi thường gặp nhất và câu trả lời chuẩn xác bằng tiếng Anh/Việt để bạn phản hồi ngay lập tức:
#### Tình huống 1: Riot hỏi về việc truy cập và hiển thị dữ liệu VALORANT Match History
* **Câu hỏi của Riot**: *"VALORANT Match data is strictly protected. How do you ensure you are not surfacing player match history without explicit consent?"*
* **Câu trả lời mẫu (Tiếng Anh gửi Riot)**:
> *"Thank you for your inquiry. In strict accordance with the VALORANT Game Policy, our platform enforces an absolute privacy-first architecture. All VALORANT match histories and player statistics are completely masked by default. We do not query or display any player stats until that specific player logs in via Riot Sign-On (RSO) and actively checks an affirmative consent checkbox on our Privacy Modal. If a player has not completed this flow, our platform displays a locked privacy placeholder. Furthermore, players retain the ability to revoke this permission at any moment via their account settings, which immediately deletes stored tokens and suppresses all public match statistics."*
#### Tình huống 2: Riot hỏi về việc thu lệ phí tham gia (Entry Fee) và bảo đảm quy tắc 70%
* **Câu hỏi của Riot**: *"We noticed your platform supports entry fees. How do you guarantee compliance with our Community Competition Guidelines regarding prize pool allocations and prize caps?"*
* **Câu trả lời mẫu (Tiếng Anh gửi Riot)**:
> *"Our platform implements programmatic guardrails at the software level. Organizers cannot bypass the 70% prize pool rule: our tournament creation form calculates the gross entry fees in real-time and hard-blocks tournament publication if the allocated prize pool is under 70% of gross fees (HTTP 422 Unprocessable Entity). Furthermore, our platform hard-caps community prize pools at $10,000 USD per tournament and automatically prohibits entry fees for any competition with fewer than 20 individual participants. Basic tournament creation and bracket tracking remain 100% free for all community organizers."*
#### Tình huống 3: Riot hỏi về thuật toán Anti-Smurf có can thiệp hoặc thay thế hệ thống ELO/MMR của Riot không?
* **Câu hỏi của Riot**: *"Does your Anti-Smurf Risk Engine attempt to calculate an alternative MMR or replace official Riot ranked tiers?"*
* **Câu trả lời mẫu (Tiếng Anh gửi Riot)**:
> *"No. The Anti-Smurf Risk Engine does not compute, suggest, or display any custom ELO or MMR rating. Official player tiers retrieved from league-v4 are displayed verbatim. Our Anti-Smurf score (0-100) is strictly an internal administrative risk indicator designed solely to alert tournament referees when an account exhibits suspicious anomalies (e.g., a Level 32 unranked account dominating high-tier matches) in rank-restricted community cups. It serves only as an advisory prompt for manual student ID verification and does not impact any game systems."*
#### Tình huống 4: Riot hỏi về khả năng tối ưu hóa lưu lượng và bộ nhớ đệm (Caching & Rate Limits)
* **Câu hỏi của Riot**: *"Explain why you need 500 requests per 10 seconds and how your caching infrastructure minimizes unnecessary queries."*
* **Câu trả lời mẫu (Tiếng Anh gửi Riot)**:
> *"Our production deployment utilizes Redis caching with a 15-minute TTL on dynamic summoner/ranked entries and permanent caching for completed match records. Tournament code results are ingested via asynchronous HTTP POST webhooks directly from Riot game servers, completely eliminating polling overhead. The requested tier (500 req / 10s) is strictly required to accommodate concurrent check-ins during weekend multi-school tournaments (up to 32 simultaneous matches) where hundreds of players check in within narrow 15-minute windows, ensuring zero dropped requests or delayed lobby creation."*
---
### 3.5 Quy trình Gia hạn & Duy trì Production API Key (Key Lifecycle Management)
1. **Thời hạn của Production API Key**:
* Khác với Personal Key (hết hạn sau 24 giờ), Production API Key có thời hạn thông thường là **1 năm (12 tháng)**.
2. **Nhắc nhở Gia hạn (Key Renewal)**:
* Trước khi hết hạn 30 ngày, cổng Riot Developer Portal sẽ gửi email thông báo nhắc gia hạn đến tài khoản đăng ký.
* Ban quản trị cần đăng nhập vào portal, kiểm tra xem ứng dụng có thay đổi tính năng gì lớn so với đơn đăng ký ban đầu hay không, sau đó nhấn nút **Request Renewal**.
3. **Cập nhật URL / Domain**:
* Nếu dự án chuyển sang tên miền mới, bạn phải cập nhật lại Product URL, tải file `riot.txt` lên tên miền mới và bấm xác thực lại trước khi đổi DNS chính thức.
4. **Xử lý sự cố khi API Key bị lỗi hoặc thu hồi**:
* Nếu nhận được mã lỗi `HTTP 403 Forbidden`: Kiểm tra xem key có bị hết hạn hoặc bị tạm khóa do vi phạm chính sách không. Hệ thống của chúng tôi đã tích hợp sẵn cơ chế **Tự động chuyển đổi sang Mock Data (`OfflineMockAdapter`)** để đảm bảo giao diện giải đấu của người dùng không bao giờ bị sập trắng trang kể cả khi mất kết nối API Riot.
---
### 3.6 Checklist Tuân thủ Pháp lý & Vận hành Giải đấu Thực tế
Trước khi công bố bất kỳ giải đấu nào ra cộng đồng, ban tổ chức cần kiểm tra danh sách sau:
- [ ] **Tên giải đấu**: Không chứa các từ cấm (*Championship, League, Season, Pro, Masters, VCS, VCT, Worlds*).
- [ ] **Quy mô giải đấu**: Nếu có thu lệ phí, số lượng người chơi đăng ký phải từ **20 người trở lên** (tối thiểu 4 đội 5v5).
- [ ] **Giải thưởng**: Tổng tiền thưởng công bố phải lớn hơn hoặc bằng **70%** tổng lệ phí dự kiến thu được.
- [ ] **Giới hạn tiền thưởng**: Không vượt quá **10.000 USD** (~250.000.000 VNĐ) cho một giải đấu cộng đồng.
- [ ] **Nhà tài trợ**: Tuyệt đối không nhận tài trợ hoặc đặt banner của các nhãn hàng cờ bạc, cá độ, rượu bia, thuốc lá điện tử, tiền mã hóa (crypto/NFT), hoặc dịch vụ cày thuê/bán acc.
- [ ] **Bản quyền Riot**: Mọi hình ảnh ấn phẩm truyền thông, livestream overlay OBS và trang web đều phải in rõ câu khước từ trách nhiệm bản quyền của Riot Games.
- [ ] **Bảo vệ quyền riêng tư**: Không tự ý công khai lịch sử đấu VALORANT của người chơi khi họ chưa bấm xác nhận qua Riot Sign-On (RSO).