Integrating Egret Native with Shopee App to Overcome iOS App Store Review Restrictions

The previous article introduced how the Shopee Games team selected and extended a game engine to improve production efficiency and align the game development process with mature front‑end engineering practices. This article focuses on the iOS App Store review problem and shares the solution of combining Egret Native with the Shopee App.

iOS Review Background

When Shopee Games was first launched, the user base was small and Apple did not raise concerns about the HTML5 version. In early 2021, Apple flagged the embedded HTML5 games in the Shopee App as violating App Store Review Guideline 4.7. The relevant clause states:

4.7.1 Software offered under this rule must:<br/>- be free or purchased using in‑app purchase;<br/>- only use capabilities available in a standard WebKit view (e.g. it must open and run natively in Safari without modifications or additional software); and use WebKit and JavaScript Core to run third‑party software and should not attempt to extend or expose native platform APIs to third‑party software;<br/>- be offered by developers that have joined the Apple Developer Program and signed the Apple Developer Program License Agreement;<br/>- not provide access to real money gaming, lotteries, or charitable donations;<br/>- adhere to the terms of these App Store Review Guidelines (e.g. do not include objectionable content); and<br/>- not offer digital goods or services for sale.

The guideline can be summarized as:

Only free H5 games or those using Apple‑approved payment.

No extensions beyond WebKit’s built‑in features (e.g., no JSBridge).

Developers must be enrolled in the Apple Developer Program.

No real‑money gambling and content must meet other review criteria.

Shopee Games, embedded inside the Shopee App, relies heavily on JSBridge for login, shop navigation, and uses Shopee Coins (earned via e‑commerce purchases) as in‑game currency. Both aspects conflict with the Apple guidelines.

To comply, the team consulted the official Egret Engine recommendations and switched the iOS implementation from HTML5 to a native solution using Egret Native Runtime . While Egret’s official tools can generate a standalone iOS project, Shopee Games needs to be embedded, so a deeper investigation of Egret Native’s internals was required.

Egret Native Principles

Analyzing the iOS template generated by Egret Native reveals three layers:

Front‑end game layer – identical to the H5 source files.

Egret Native Runtime – the core adaptation layer that uses JSC to parse JavaScript, provides a JSBridge for communication, and implements a subset of browser features via a custom JS polyfill.

iOS Native layer – manages the lifecycle of the runtime and the view hierarchy.

The runtime depends on system libraries and a static library libEgretNativeIOS.a. Assets are stored in the app’s root assets folder, which by default supports only a single game.

Integration with Shopee App

The integration steps are straightforward: add libEgretNativeIOS.a and its dependencies to the Shopee App project, place the game package in the assets directory, and bind the required Shopee JSBridge for login, payment, and navigation. However, several deep‑level issues were discovered during implementation:

Template does not support multiple games. The assets folder can hold only one game, and the static library cannot be modified.

Network cache grows without limit. Egret Native caches network resources but lacks a cleanup mechanism.

Third‑party library name conflicts. Both libEgretNativeIOS.a and the Shopee App include SocketRocket, causing compilation failures.

Memory leaks. Repeated start/stop of the runtime inside the host app can leak textures or objects, though the leaks are currently minor.

Solutions applied:

Use the “preload” directory (configurable in Egret Native) to host multiple game bundles, allowing each game to be launched by setting the preload path before runtime initialization.

Implement cache‑size monitoring and manual cleanup in the Shopee App’s iOS native layer.

Rename or re‑namespace the conflicting SocketRocket symbols within the Shopee App.

Report memory‑leak issues to Egret; meanwhile, limit the frequency of runtime restarts.

After these adjustments, the combined solution no longer relies on WebKit, and all code resides within the submitted binary, satisfying Apple’s review criteria. The Shopee App and Shopee Games subsequently passed the App Store review.

Future Plans

Although Egret Native works, the team identified two major drawbacks:

The runtime is closed‑source, limiting custom fixes.

It only supports Egret games and is not optimal for 3D titles.

The roadmap includes developing a proprietary native runtime that can host multiple H5 game engines, similar to the architecture of WeChat Mini‑Games. The new runtime will expose WebGL‑compatible interfaces and essential BOM APIs to the JavaScript layer, enabling seamless execution of various engines.

Benefits of the new approach:

Broad compatibility across different game engines.

Easy migration of existing H5 games.

Leverage mature toolchains of each engine.

Challenges remain:

iOS 12+ is deprecating OpenGL, which the current solution relies on.

Supporting multiple engines makes it difficult to adopt newer graphics standards such as Metal, WebGL2, or Vulkan.

Given that iOS 15 still runs OpenGL and WebGL reliably, the team will accept these limitations for now while monitoring Apple’s migration path. The prototype is expected to be completed and fully adopted by 2022, with potential reuse in broader e‑commerce scenarios.