WeChat mini program demo guide

The repository has four WeChat mini program examples, showing the native mini program, subpackage loading, TypeScript types and Taro React. The full source is at GitLab sdk/miniprogram (repository access requires permission). For now the examples only come with the source, with no separate download; to use the SDK in your own project, just install the published package.

If you build mini programs with uni-app, see the UniApp WeChat mini program demo, a separate project (sdk/uniapp/demo-miniprogram).

Choose an example

Project	Purpose	Config to change	Directory to import in the developer tools
example	Complete IM example as a native mini program	miniprogram/config.js, project.config.json	sdk/miniprogram/example
example-subpackage	Main package holds only the bindings (bind), with the SDK loaded asynchronously from a subpackage, plus an independent subpackage	miniprogram/config.js, project.config.json	sdk/miniprogram/example-subpackage
example-ts	TypeScript type example, for type checking only	contract.ts, tsconfig.json	Not runnable
example-taro	Taro 4 + React integration example	src/im.ts, project.config.json	After building, import sdk/miniprogram/example-taro with miniprogramRoot set to dist

Requirements

• Node.js 20.19 or later, pnpm, WeChat Developer Tools, and your own mini program AppID (touristappid in project.config.json is only a placeholder).
• The IM service's HTTPS and WSS addresses, and the app's AppKey.
• WeChat base library 2.21.3 or later. If you use Skyline, encrypted storage or privacy APIs, test on your target base library version and on real devices.
• Configure server domains in the mini program admin console: the request domains include the IM HTTPS address and the object storage address used for uploads (signed PUT), the socket domain is the IM WSS address, and also add the downloadFile domain and any uploadFile domains you actually use. "Don't verify domains" in the developer tools only applies while debugging; real devices need the domains configured.
• Privacy declarations and user authorization for the photo album, microphone and so on are up to your mini program.
• Your server issues sign-in tickets; the Client Secret and App Token must never go into the mini program. Password sign-in and sign-up only work when the app's policies allow them.

Use the published package

@deeprespond/im-miniprogram@1.1.1 is published on npm. In your native mini program project, run:

npm install @deeprespond/im-miniprogram@1.1.1

Then run "Tools → Build npm" in the developer tools, and check that package.json, miniprogramRoot and the build output directory line up.

• The package's miniprogram field points to the CommonJS build; add miniprogram_npm/@deeprespond/** to setting.babelSetting.ignore in project.config.json.
• The native package has no runtime dependencies, so you don't need the Web SDK as well.
• The repository source may be newer than the published version. Before using a new API, check that the published package has it; being able to build it from source doesn't mean a new version has been released.

Native and subpackage demos from the full repository

From the repository root, run:

cd sdk/web
pnpm install --frozen-lockfile
pnpm build
cd ../..
make sdk-miniprogram-example

This builds the current SDK, builds npm for the native examples with the official miniprogram-ci, and copies the SDK and bindings into the subpackage directory; it doesn't upload the mini program. example references the repository's SDK through file:../, so you can't copy the example directory on its own and install it.

1. Change appid in the project's project.config.json.
2. Change appKey and apiUrl in the project's miniprogram/config.js; apiUrl must be an HTTPS address WeChat can reach.
3. Import the directory from the table above in the developer tools, check miniprogramRoot, and compile. If you rebuild npm by hand, keep the same output directory.
4. Native example: first try one-to-one chat, friends, groups and chat rooms, then check page lifecycles and Skyline rendering.
5. Subpackage example: set up a custom compile in the developer tools with im/pages/index as the start page; then try a cold start of the independent subpackage with standalone/pages/index, and check that the sdk directory was generated.

The developer tools and real devices may behave differently, so test on both.

Taro React

From the repository root, run:

make sdk-miniprogram-taro

It builds the Web SDK and React bindings, installs Taro's dependencies, runs type checks and the WeChat mini program build, and checks that no browser-only code or LiveKit ended up in the build.

Change example-taro/src/im.ts and the AppID, rebuild, and import example-taro. It only shows how to integrate with Taro and has fewer page features than the complete native example.

In your own Taro project, install the same version of the Web SDK and React bindings, import the polyfills first, and import from the /miniprogram subpath. Don't use the browser entry or the native mini program's prebuilt package instead.

Type checks and automated tests

make sdk-miniprogram-test
make sdk-miniprogram-integration

• make sdk-miniprogram-test: unit tests, component tests, checks against the official wx types, and the example-ts type example.
• make sdk-miniprogram-integration: integration tests, which need the repository's test server running first; see sdk/conformance/README.md.

Both the developer tools and real devices must use HTTPS and WSS, not the HTTP address from local testing. Don't let several test runs change the same app's policies at once.

The automated tests only cover logic and page flows. Running in the official developer tools and on real devices, file uploads, the mini program being reclaimed by the system, encrypted storage, privacy APIs, subpackages and Skyline still need testing in your own environment.

Two accounts and limits

• Testing with two accounts. Sign in with different accounts of the same app on two phones (or two separate debugging instances), add each other as friends, then try messaging, group chat, read receipts, recall, and leaving and re-entering pages.
• One client. A mini program can have only one client per AppKey; creating another returns client_exists. To switch users, sign out and destroy the old client before creating a new one.
• Files by path. Files are always given to the SDK as local paths, never as Blobs. If removing media metadata fails, the SDK never quietly keeps it. Manage foreground and background switches during previews and recording with keepForeground.
• No audio or video. calls.supported and channels.supported are both false, so mini programs can't join call or channel media; being able to look up a channel doesn't mean being able to take part in audio and video.
• Supported platforms. The native package supports mini programs in WeChat and WeCom; Alipay, Douyin, QQ mini programs and Donut aren't supported.

Troubleshooting

Symptom	Check
SDK or bind not found	Whether you built the Web SDK first and then ran make sdk-miniprogram-example; whether the npm output directory and subpackage copy are right
Sign-in fails	The AppKey, app policies, whether the account belongs to this app, and whether the ticket is still valid
Requests fail on real devices	HTTPS and WSS certificates; whether the allowed domains include the IM address and the upload (signed PUT) and download domains
Browser code or LiveKit ends up in the Taro build	Whether polyfills are imported first, the /miniprogram subpath is used, and all package versions match
The TS example won't run	example-ts is for type checking only and can't run
The connection drops after previewing a file	Whether keepForeground manages the switch and is released promptly; wait for the reconnect after returning to the foreground
Channels can be looked up but not joined	Mini programs don't support channel media yet; turning on audio and video in the app's policies doesn't change that