BaronCyrus/ship-wechat-minigame

WeChat Mini Game: From Registration to Review

Goal: Convert the user's Unity game into a WeChat Mini Game, complete the required qualifications and two filings, and submit a version for review until "Version Management → Review Version" shows "Under Review".

Prerequisite: Confirm that steps 1-4 of ship-my-game are complete (progress archive, channel, health check, browser). If not, read that first.

Source Markers

• [实测]: Successfully executed on a real personal account.
• [官方]: Organized according to official documentation, with links provided.
• "已核对后台": Verified the page and fields in the real backend on 2026-11-02, but not submitted.

Tested Coverage (as of 2026-11-08)

• Tested: Registration, enabling Quick Adaptation, running a Unity 6 build on a real device, qualification review (passed), WeChat verification (completed), Mini Game filing (passed by the approving authority), Mini Program filing (preliminary platform review passed), uploading via developer tools, trial version, submitting for review (first submission rejected due to black screen on first open; after patch B7 was fixed, re-submitted and passed in about 1 hour), publishing a stand-alone game before receiving the Mini Program filing number, and submitting operational materials (game description, promotional text, general cover image, vertical and horizontal promotional images, vertical promotional video with actual gameplay) for review.
• Only [官方] basis: Stages after the Mini Program filing's preliminary platform review, command-line upload, phased release, publishing conditions for online games, review results for operational materials, general-type promotional videos, ad space, and payouts.

Personal Checklist

Phase	Item
P1	Register Account: Fill in email activation code, real-name verification, admin WeChat scan. Takes about 20 minutes [实测]
All	Scan to login to mp.weixin.qq.com. Session expires in less than a day; re-scan required after expiration [实测]
P2	Scan to login to WeChat DevTools; decide whether to enable the tool's "Service Port" (a security setting) [实测]
P3	Use phone WeChat to scan the preview code for a test run. Preview code expires in about 25 minutes [实测]
P4	Sign documents and submit materials for qualification review; WeChat Verification: agree to terms, identity verification, payment [实测]
P5	Mini Game Filing Step 1: Use phone to scan QR code to sign three documents; take screenshots of the filing process in WeChat; click the final "Submit" [实测]
P6	Mini Program Filing: Photos of both sides of ID card, street-level mailing address, two personal phone numbers (primary and emergency contact) and an email, facial recognition, agree to terms [实测]; if the filing province is Guangdong or Xinjiang, handwrite a commitment letter; complete SMS verification from MIIT within 24 hours after preliminary platform approval [官方] (Filing Guide, Material Examples)
P7	When uploading via command line, generate a "Mini Program Code Upload Key", usually requires admin scan (not tested)
P8	Click "Submit" in the review gate; after approval, the user decides to publish and confirms by scanning with the admin WeChat [实测]
Post-launch	When enabling ad space, agree to the advertising agreement; after activation, supplement financial info: account holder name, ID number, bank account [官方] (Ads, payouts.md)

Engineering Requirements (Cross-reference with Main Entry Step 3)

Engine Version

• Official statement [官方]:
  • Supports Unity 2018–2022 and Tuya Engine, recommends 2022.3 or Tuya Engine (Recommended Engine Versions).
  • SDK changelog says: "Supports Unity6, preview version not recommended for production use" (CHANGELOG).
• This repo's test [实测]: Unity 6000.6 with 12 patches ran on a real device; patches are incorporated into scripts. The previous "occasional Android black screen" was caused by the engine not waiting for asset bundles, resulting in the first review rejection. This is fixed by patch B7 (see build.md section 10).
• How to choose:
  • New projects: Use 2022.3 LTS or Tuya Engine.
  • Existing Unity 6 projects: Can use this repo's patching route. First inform the user that "official support is still preview", then log it in the progress archive.

Platform Module: WebGL Build Support.

SDK

• Use scripts/fetch_wxsdk.sh to pull, version fixed at v0.1.34.
• Do not use v0.1.35 preview: it swaps the plugin for WX-WASM-SDK-V3, potentially breaking existing patches.

AppID

• Must use the official Mini Game's AppID with "Quick Adaptation" enabled. Test accounts cannot run Unity packages [实测].

Package Size

• Official limits: Main package ≤ 4MB, total package ≤ 30MB [官方] (Code Package).
• When the initial package resources are inside the package, Unity documentation calculates based on 20MB (UsingLoader), so plan for 20MB.
• Tested package size: 13～14MB [实测].

Necessary Code Changes (all [实测], details in build.md and capabilities.md):

• Create a Chinese font subset and set it as fallback.
• Change save/load to use WX.StorageSetStringSync, saving immediately after each critical action.
• Calculate collision avoidance for the safe area and the upper-right navigation capsule button using WX.GetWindowInfo and WX.GetMenuButtonBoundingClientRect.
• Remove external links, app store ratings, Google Services entry; wrap Android-only code in #if UNITY_ANDROID.
• Main menu title must display the registered Chinese game name; it's needed for filing screenshots.
• When the ad unit ID is empty, ad buttons degrade safely without errors or blocking the flow.
• Start the game within the WX.InitSDK callback.

Network Type: Decide between "stand-alone" and "online" before the Mini Game filing.

• The privacy protection guide for stand-alone games can only select "No user information processed" (verified in backend).
• Therefore, stand-alone games cannot use privacy-related APIs like friend leaderboards, clipboard, user info (inferred, based on console.md).

Phases

P1 Account & Backend Initialization

1. If the user already has a Mini Game account, skip to step 2. Otherwise, follow onboarding.md to open the registration page, guide the user to register a personal account, and select the primary category "Mini Game" [实测].
2. Finalize the game name: Use pure Chinese to avoid triggering copyright material requirements. The name is locked after qualifications and filing are submitted and cannot be changed until the Mini Program filing is complete. When selecting categories, personal accounts should avoid cultural interaction, role-playing, and card games [官方] (Category Settings). Rules are in listing.md.
3. Enable Quick Adaptation: Go to "Game Capability Map → Development Capability → Production Efficiency Pack → Quick Adaptation", click "Apply Now", effective immediately [实测].
4. In "Development Management → Development Settings → Developer ID", read the AppID, write it to the progress archive and publish/wechat/build.json [实测].
5. In "Account Settings → Basic Settings", confirm the operation region is "Mainland China" (verified in backend).
6. Install the Stable version of WeChat DevTools, not the Minigame Build version, and ask the user to scan to log in [实测].

Completion Criteria:

• Progress archive contains the AppID.
• "Quick Adaptation" on the "Production Efficiency Pack" page shows "Enabled".
• Name and service categories in Basic Settings are filled.
• DevTools is logged in.

P2 Build & Export

1. Install the WebGL module, then run scripts/fetch_wxsdk.sh <project> to embed the SDK into Packages/ and apply patches [实测].
2. Copy scripts/ShipWeChatBuild.cs to <project>/Assets/Editor/. Then write <project>/publish/wechat/build.json according to templates/build.json [实测].
3. Use ../ship-my-game/scripts/make_cjk_font.py to generate a Chinese font subset, and fill in cjkFont and latinFonts in build.json [实测].
4. Modify the code as per "Engineering Requirements" [实测].
5. Export: Run ../ship-my-game/scripts/unity_build.sh <project> WebGL ShipWeChatBuild.Export wechat [实测].
6. In DevTools, "Project → Import Project", select <project>/Builds/wechat/minigame, click "Trust and Run", and run through the main flow in the simulator [实测].
7. Use scripts/wx_cold_start.py to simulate a first launch in the simulator: clear cache, delay asset bundle by 12 seconds, compile, check the result, restore. This is how a reviewer sees the first launch; you can't see it on your own phone. Steps are in build.md [实测].

Completion Criteria:

• Log contains [Ship] wechat export=SUCCEED. Unity 6 projects must also have [Ship] framework patched and a line starting with [Ship] B7.
• First launch replication: Simulator shows loading page then main page; wx_cold_start.py log reports OK; finally release.
• Simulator can enter the main page, touch responds, console has no red errors (except ignorable logs).
• Preview panel shows code package size is within limits.

Details and patch comparison table are in build.md.

P3 Real Device Verification

1. Switch the preview panel to "QR Code Preview". Do not use "Auto Preview" or "Real Device Debugging" [实测].
2. Generate a preview code, send a screenshot to the user, or let them scan the code directly from DevTools. The code expires in about 25 minutes [实测].
3. Go through the real device checklist in build.md with the user: sound, Chinese text, touch, save/load after restart, no obstruction by notch/capsule buttons, no unopenable entries, main page shows Chinese name.
4. Also perform a first launch on the phone: delete the mini game from "Recently Used" in WeChat, then scan the code. It's unverified whether deleting clears the resource cache, so conclusions should be based on the simulator replication in Phase P2. If black screen occurs, stop and check troubleshooting.md – do not rely on "re-enter mini program" to pass; the reviewer only opens it once, and the first submission was rejected for this reason [实测].

Completion Criteria: The user confirms all checklist items pass on at least one phone. Test on both Android and iOS if available.

P4 Backend Required Items, Qualifications & Verification (Can be Parallel with P2, P3)

1. Age Rating Prompt: "Account Settings → Basic Settings → Age Rating Prompt → Set". Fill according to console.md, user confirms, click "Submit for Review" (verified in backend).
2. User Privacy Protection Guide: "Service Content Declaration → User Privacy Protection Guide → Complete". For stand-alone games, select "Do not process any user information in any way", user confirms, click "Confirm Above Content" (verified in backend).
3. Submit Qualifications: Select "Situation 2: The Mini Game currently and in the future does not require virtual payments". User completes the signing and materials [实测]. See filing.md.
4. WeChat Verification: Completed by user [实测]. See onboarding.md.
5. CPC Real-name Verification: No action needed if virtual payment is not enabled; the page states "No developer action required" (verified in backend).

Completion Criteria:

• Age Rating Prompt shows submitted or passed.
• Privacy Protection Guide no longer shows "Not Updated".
• Qualifications show under review or passed.
• WeChat Verification is completed, or paid and under review.

P5 Mini Game Filing

1. First confirm four things:
   • Name is finalized.
   • Qualifications have been submitted.
   • Age Rating Prompt has been submitted.
   • A preview version exists: Main page shows the Chinese name, and the "Optimization Suggestions" popup is disabled.
2. Open the filing form. Entry point is in filing.md. Step 1 is done by the user: select game type and network type, then scan on their phone to sign three documents [实测].
3. You fill in the text for Step 2. First read the code to verify, then write the scenario, gameplay, and system according to templates/filing-content.md [实测].
4. Give the screenshot list to the user, ask them to take screenshots in WeChat on their phone. You rename them by category, transfer via local relay one category at a time, click "Save" after each transfer, refresh and verify [实测].
5. Go through the review gate: List the content to be submitted to the user; when the user says "Submit", click "Next → Preview Info → Submit", or ask the user to do it themselves [实测].

Completion Criteria: The "Mini Game Filing" on the "Mini Game Filing & Publishing Process Guide" page shows "Platform Review". The progress archive's "Waiting" section notes the estimated time: platform preliminary review 1-2 business days, approving authority review 10-20 business days.

P6 Mini Program Filing (ICP)

References: Mini Program Filing, Filing Guide, Material Examples. Filling the form up to submission has been tested; after preliminary review, follow the official documentation.

1. Wait for the Mini Game Filing to show "Approved by Authority" and for WeChat Verification to be completed. In testing, the process guide page required both to be done before the "Start Filing" button became clickable [实测].
2. Before opening the form, explain to the user what they need to prepare: photos of both sides of their ID card, street-level mailing address, two personal phone numbers and an email, background requirements for facial recognition; if the filing province is Guangdong or Xinjiang, a handwritten commitment letter is also needed. And make it clear that "Submit" must wait for your review. In testing, the user filled in and submitted directly [实测]. The checklist is in filing.md.
3. Enter via "Start Filing" on the process guide page; a new tab will open for "Verify Filing Type". No need to select Situation 1/2 or Filing Type [实测].
   • User: Select region, upload ID, click "Verify"; fill in address, phone number, and email; scan code for facial recognition; sign commitment letter (Guangdong, Xinjiang).
   • You: Draft the "Remarks (Required)" for user confirmation (official docs don't specify requirements, unverified); review the "Material Preview" page.
4. On the "Material Preview" page, go through the review gate: List the service content, remarks, and uploaded materials for the user; ask the user to verify the address and ID info themselves; the user checks the agreement terms at the bottom; click "Submit" when the user says so [实测].
5. After platform preliminary review passes, remind the user: After receiving the SMS from 12381, complete verification on the MIIT filing website within 24 hours, otherwise the application will be returned [官方].

Completion Criteria: The backend shows the filing number has been issued; or the Mini Program filing on the home page "Filing & Verification" shows under review (tested as "Platform Review"), and the progress archive notes the submission time, current review stage, and estimated time.

P7 Upload Development Version & Trial Version [实测]

References: Collaboration and Release, miniprogram-ci.

1. Confirm that the export is the version to be submitted this time: Ad unit IDs can be left empty, the main page name is correct, and the "Optimization Suggestions" popup is disabled.
2. Upload, choose one of two methods:
   • DevTools' "Upload", fill in version number and project notes [实测];
   • Command line scripts/wx_ci.js upload, requires upload key and IP whitelist, see automation.md (untested).
3. Open "Version Management → Development Versions", confirm this version is visible, then select it as the "Trial Version" from the dropdown next to "Submit for Review", ask the user to scan the trial version code for a final check [实测]. Details in review.md.

Completion Criteria: The development version list contains this version number, and the trial version can be opened on the phone.

P8 Review Gate [实测]

Reference: Version Review.

1. Verify prerequisites:
   • Age Rating Prompt and Privacy Protection Guide are both completed.
   • Development version has been uploaded.
   • The name displayed in the game matches the backend name.
2. Click "Submit for Review" on the "Version Management → Development Versions" page, fill in the form according to review.md. The form is in a cross-origin iframe on a new tab; you can only take screenshots and operate by coordinates.
3. Go through the main entry's review gate: List the channel, version number, package size, version notes, privacy and ad declarations, and estimated review time (official: 1 business day; tested: 1-3 hours for a result) for the user; wait for the user to say "Submit".
4. Click "Submit" on the form; click "Continue Submit" on the privacy compliance reminder; then read the "Version Management" page, confirm that the "Review Version" shows "Under Review".

Completion Criteria: "Review Version" shows "Under Review". The progress archive notes the submission time, estimated time, and where to check results ("Version Management" page, in-app messages).

Waiting Period & Post-launch

Durations of Various Waiting Items (write in progress archive "Waiting" section)

• Qualifications: Tested as passed; page says about 1 business day, official says 1-3 calendar days.
• Mini Game Filing: Platform preliminary review 1-2 business days, approving authority 10-20 business days. Tested: submitted 10-24, entered "Approving Authority Review" on 10-31, passed when checked on 11-07.
• Mini Program Filing: Official says about 10-30 business days for Situation 2; the backend also has 3-10 (process guide page) and 2-22 ("Filing Required" popup on version management page) versions; give the longest estimate. Platform preliminary review 1-2 business days, re-review after rejection 7 business days.
• Version Review: Official about 1 calendar day; tested twice, results came the same day, about 3 hours (rejection) and about 1 hour (pass).

Don't Do During Waiting

• Don't change the name or transfer the subject; both filings will be invalidated and need to be restarted.
• Don't click "Plugin Update Available" in DevTools; the plugin version follows the SDK [实测].

Things You Can Do While Waiting: Integrate ad code (leave IDs empty), take screenshots.

Publication: After review passes, click "Publish" on "Version Management → Review Version", select full or staged release, then confirm by scanning with the admin WeChat. Ask the user first, as before [实测]. Stand-alone games have been tested to publish without needing the Mini Program filing number; online games officially require it first. See review.md.

Post-launch

• Operational Materials: Fill in game description, general cover image, vertical and horizontal promotional images, promotional text, and promotional video in "Operational Materials Management". These determine how the game appears in search results and the discovery page. Text and images can be changed only 3 times per month each; promotional videos allow 10 sets per week. First show the users drafts and copy, and only submit after they agree. See listing.md [实测].
  • When the top of the page prompts for a missing "Promotional Video - Actual Gameplay", follow the guide in listing.md to record real gameplay: 1080×1920 vertical, 20-30 seconds, no text or overlays in the video.
• Ad Space (Traffic Monetization): Can be enabled after reaching 100 cumulative unique visitors (or meeting the gaming community conditions). On the day of activation, supplement financial info, create ad units, fill the IDs into the game, and release another version. See capabilities.md, payouts in payouts.md.
• Startup Failure: After going live, check the "Real-Time Logs" in the backend for the logs of the failed startup and record them in the progress archive.

If Rejected or Stuck: See review.md and troubleshooting.md.