WeChat Mini Game SDK: Common Issues, Network Request Limits, and Optimization Strategies

Background: As more WeChat mini‑games integrate our SDK, a variety of problems have emerged. This article records the experience and lessons learned.

Reference: The online documentation for WeChat mini‑game development is available at https://developers.weixin.qq.com/minigame/dev/api/base/system/wx.getSystemInfoSync.html.

SDK‑Related WeChat APIs

Network Requests

The JS API provides wx.request for network calls. Important points:

Only HTTPS domains are supported, and the domain must be ICP‑registered and configured in the Mini‑Program backend.

IP addresses (except LAN IP) and localhost are not allowed.

If a port is specified for an HTTPS domain (e.g., https://myserver.com:8080 ), requests must use exactly the same URL; any other URL (different port or no port) will fail. Even the default port 443 cannot be used in the request URL.

For POST requests with header['content-type'] = 'application/x-www-form-urlencoded' , the data is automatically converted to a query string (URL‑encoded key‑value pairs).

Parent domain configuration is not supported; sub‑domain usage is restricted.

Usage limits:

Default timeout is 60 seconds.

The maximum concurrent limit for wx.request , wx.uploadFile , and wx.downloadFile is 10. Excess requests are queued.

When a mini‑game runs in the background, any network request that does not finish within 5 seconds triggers a fail interrupted error, and further network calls are blocked until the game returns to the foreground.

Key Pitfalls Encountered

1. The 10‑request concurrency limit caused a critical issue: during resource loading, about 20 requests were fired simultaneously, each taking a long time. When a user exited the game, the SDK’s “login success” reporting request remained in the queue, leading to data loss. Conversion rate dropped from the normal 95 % to 63.94 %.

2. Unity C# mini‑games cannot use wx.request (JS‑only). They must implement their own HTTPS request logic. Even without wx.request , the WeChat developer tools still throttle HTTPS request concurrency, queuing excess calls.

Launch Parameters

wx.getLaunchOptionsSync() retrieves the query parameters on cold start. The SDK extracts these parameters for data attribution and must ensure:

Data is not truncated (use POST if necessary).

The reported data is correctly encoded and parsable by the backend.

System Information

WeChat is deprecating wx.getSystemInfoSync in favor of multiple granular APIs. The SDK will need compatibility handling for the old method. Example code (not shown) demonstrates how to wrap the call with try‑catch to avoid crashes when the method returns an empty object.

Share Button Display

wx.showShareMenu controls the visibility of the share button in the top‑right menu. A conflict between the Unity‑to‑JS plugin and the SDK caused the share button to appear prematurely, resulting in a black screen while loading the share image.

Solution: Disable sharing until the SDK finishes registering share information (approximately 1 second).

Share Event Listening

wx.onShareAppMessage is triggered when the user taps the top‑right “forward” button. The SDK fetches the game’s share information via a network request and returns a promise to WeChat, allowing operators to edit share content without real‑time SDK updates.

A fallback share image is used if the request exceeds 3 seconds.

Active Sharing

wx.shareAppMessage programmatically opens the contact selection UI for sharing.

The SDK also provides a custom share method for game developers to pass bespoke share parameters, enabling different share graphics for different in‑game buttons.

Confirmation Modal

wx.showModal displays a modal dialog. The SDK uses it mainly for error notifications. In version‑upgrade scenarios, setting showCancel: false forces the player to update.

Toast Messages

wx.showToast is used by the SDK to inform users of payment errors.

Summary

1. Most front‑end issues in the WeChat mini‑game SDK stem from network request blocking, request loss, and URL‑encoding problems.

2. JS‑based mini‑games (e.g., Laya, Cocos) and C#‑based Unity mini‑games have different underlying APIs, so the SDK maintains separate JS‑SDK and C#‑SDK implementations.

3. When anomalies arise, teams should promptly share progress in group chats, as the SDK is only one part of the game launch pipeline that also includes promotion and data attribution. Timely communication is essential to adjust release schedules and ensure smooth publishing.