# fluwx: calling the WeChat native SDK from Flutter

> fluwx is a Flutter plugin that wraps the WeChat SDK for sharing, payment, auth, mini programs and customer service. It is a thin bridge, so the platform configuration on Android and iOS is where the real work sits.

**OpenFlutter/fluwx** — Flutter版微信SDK.WeChat SDK for flutter.

- Repository: https://github.com/OpenFlutter/fluwx
- Website: https://pub.dev/packages/fluwx
- Stars: 3,322 · Forks: 555
- Language: Dart
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/openflutter-fluwx

## What fluwx actually solves for a Flutter app

A Flutter app that needs WeChat integration has two options: write platform channels against the WeChat SDK on Android and iOS separately, or use a plugin that already did it. fluwx is the second option. The README describes it as a Flutter plugin for the WeChat SDK that lets developers call the native WeChat APIs.

The audience is narrow and specific. You are building a Flutter app for users who have WeChat installed, and you need one or more of: sharing images, text or music to a session, favorite or timeline; WeChat Pay; an auth code that you exchange for a login; launching a mini program; subscribing to messages; opening the WeChat app; launching your app from a WeChat link; or opening customer service. If your users are outside mainland China, none of this matters and the plugin is dead weight.

The README is candid about the boundary: "Fluwx is good but not God." It points readers at the official WeChat documentation before integrating, because the plugin exposes the SDK, it does not abstract away the platform registration rules. That framing is honest and it sets the right expectation. fluwx removes the channel-writing work, not the account and certificate work.

## How the plugin is structured and what registerApi does

The entry point is a Fluwx object. You call registerApi with your app id and, on iOS, a universal link. The README notes that the app_id in pubspec.yaml is not used to initialize the WeChat SDK, so registration is always an explicit call you make in Dart. That is a deliberate split: configuration lives in pubspec.yaml, initialization lives in your app code.

Behind that call, the plugin forwards to the WeChat SDK on each platform. The repository layout shows the split clearly: lib/ holds the Dart surface, packages/ holds the platform implementations, and doc/ holds per-capability guides for share, payment, auth, launching from H5 and customer service. The pubspec.yaml section named fluwx carries app_id, debug_logging and flutter_activity. The README states debug_logging does not work on iOS, and that flutter_activity is used for cold boot from WeChat on Android, with the plugin falling back to the launcher activity when it is unset.

There is a second package, fluwx_no_pay, for builds that should not carry payment features. The README says you switch to it rather than toggling a flag, so the payment code is genuinely absent rather than disabled. For apps that never take payment, that is a smaller dependency surface and one less thing to justify in a store review.

## Installing fluwx and registering it in a first run

Installation is a pubspec.yaml dependency. The README shows the package with payment included, and warns in the same breath that the caret placeholder must be replaced with a real version, or you can look up the versions page on pub.dev. The current release line is v6.0.4, published on 2026-09-23, with v6.0.2 and v6.0.1 before it in July 2026.

```yaml
dependencies:
  fluwx: ^${latestVersion}
```

If you do not want payment features, the README says to use fluwx_no_pay instead, which it describes as a separate package without payment.

Then register the API as early as possible. The README gives this example, with a placeholder app id and universal link:

```dart
Fluwx fluwx = Fluwx();
final success = fluwx.registerApi(appId: "wxd930ea5d5a228f5f",universalLink: "https://your.univerallink.com/link/");
print("register API success: $success");
```

The universalLink parameter only applies to iOS. On iOS the README lists four requirements: a valid universal link, the Associated domains entitlement, LSApplicationQueriesSchemes in Info.plist containing weixin, wechat, weixinULAPI and weixinURLParamsAPI, and a CFBundleURLTypes entry named weixin with your WeChat App ID in its URL schemes. On Android the requirement is that the MD5 fingerprint of your signing certificate is registered with WeChat. The README states plainly that a debug build signed with the machine's debug key will not be recognized and you will get errCode = -1.

On OpenHarmony there is one extra step the README calls out: add weixin to querySchemes in module.json5 so the app can check whether WeChat is installed. It also warns that you must not use the IDE's automatic signing and should apply for a debug certificate manually.

## Where fluwx will cost you time

The failure modes here are not in the Dart code. They are in the WeChat platform rules, and the plugin cannot shield you from them.

Debug builds on Android are the first wall. Because WeChat matches the signature fingerprint of your installed app, an unregistered debug key produces errCode = -1 on every call. The README's answer is to modify your debug key, which means either registering it or signing debug builds with a registered key. Either way it is a step that has nothing to do with Flutter and everything to do with your keystore.

iOS has more moving parts. A universal link, the Associated domains entitlement, four entries in LSApplicationQueriesSchemes and a URL type in Info.plist all have to be right before anything works. Miss one and the symptom is usually a silent no-op or a return to your app with no payload, which is harder to debug than an exception.

The V6 line is itself a migration cost. The README points to doc/MIGRATE_TO_V6.md and warns that V6 has many breaking changes, especially on iOS, including scene_delegate support and Swift Package Manager. If you are on v5 and your iOS integration is custom, budget for that document before you upgrade.

Finally, consider whether you need the plugin at all. If your app only needs to open WeChat with a shared link, a plain URL launch may be enough, and you avoid a native dependency entirely.

## Alternatives and how they differ

The realistic alternative is writing your own platform channel against the WeChat SDK. The difference is where the work lands. With a custom channel you own the Android and iOS glue, you can trim it to exactly the three calls you need, and you are not exposed to a third party's release cadence or its V6 migration. The cost is that you also own the iOS universal link wiring, the Android signature handling, and every future WeChat SDK change.

fluwx sits in the middle. It gives you a Dart API, a per-capability doc set, and a separate no-pay package, but it still requires you to satisfy the same WeChat platform prerequisites. The plugin does not remove the external account setup, it removes the channel code.

A second, narrower alternative is to skip WeChat SDK integration entirely and use a web-based flow where the platform allows it. That works for some sharing and login scenarios and avoids native dependencies, but it cannot do WeChat Pay or mini program launch, which are the reasons most teams reach for fluwx in the first place. That is the line to draw: if payment or mini programs are in scope, native integration is not optional.

## Maintenance, licensing and what to check before upgrade

The repository is not archived, and the last push was on 2026-09-23, the same day as the v6.0.4 release. The two prior releases, v6.0.1 and v6.0.2, landed on 2026-07-20. That is a recent and reasonably regular release pattern, and it matters here because WeChat SDK changes and iOS platform changes both force plugin updates.

The licence is Apache-2.0. For most applications that is a permissive licence and the practical obligations are the usual ones: keep the licence and notice files, and be aware of the patent grant and termination terms. This is not legal advice; if you are redistributing the plugin in a commercial product, have your own counsel read the LICENSE file in the repository.

The upgrade cost is concentrated in major versions. The README's V6 note is explicit that iOS integration changed, naming scene_delegate and Swift Package Manager. That means an upgrade is not a version bump in pubspec.yaml alone; it can require Info.plist and Xcode project changes. Before upgrading, read doc/MIGRATE_TO_V6.md, and check whether your iOS app delegate setup conflicts with scene_delegate support. On the Android side, the debug_logging flag is documented as not working on iOS, so do not rely on it for iOS troubleshooting.

## Conclusion

Adopt fluwx if you are shipping a Flutter app for a Chinese audience and need WeChat login, payment, sharing or mini program launch without writing platform channels yourself. Do not adopt it if you cannot register a WeChat open platform app, because the Android signature and iOS universal link requirements are external and blocking. Before writing feature code, verify three things: that your debug keystore is registered with WeChat so errCode -1 stops appearing, that LSApplicationQueriesSchemes and CFBundleURLTypes are correct in Info.plist, and that you have read doc/MIGRATE_TO_V6.md if you are coming from v5, since the V6 line changed iOS integration substantially.

## FAQ

### How do I install fluwx in a Flutter project?

Add fluwx to the dependencies section of pubspec.yaml, replacing the version placeholder with a real version from pub.dev. If you do not need payment features, the README says to use the separate fluwx_no_pay package instead.

### Why does fluwx return errCode = -1 on Android?

The README states this happens because the MD5 fingerprint of your app's signing certificate is not registered with WeChat, which is typical for debug builds signed with the machine's debug key. You need to register the signature or modify your debug key.

### What iOS configuration does fluwx need before it works?

The README lists a valid universal link, the Associated domains entitlement, LSApplicationQueriesSchemes containing weixin, wechat, weixinULAPI and weixinURLParamsAPI, and a CFBundleURLTypes entry named weixin holding your WeChat App ID. The universalLink parameter to registerApi only applies on iOS.

### Does fluwx support WeChat payment?

Yes. The default fluwx package includes payment, and the README lists payment with WeChat among the plugin's capabilities. A separate fluwx_no_pay package exists for builds that must not include payment features.

### Do I need to call registerApi if app_id is set in pubspec.yaml?

Yes. The README states the app_id in pubspec.yaml is not used to initialize the WeChat SDK, so you still need to call fluwx.registerApi manually, and it recommends registering as early as possible.

## Sources

- [License: Apache-2.0](https://github.com/OpenFlutter/fluwx/blob/main/LICENSE)
- [OpenFlutter/fluwx on GitHub](https://github.com/OpenFlutter/fluwx)
- [Project website](https://pub.dev/packages/fluwx)
- [README](https://github.com/OpenFlutter/fluwx/blob/main/README.md)
- [Releases](https://github.com/OpenFlutter/fluwx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openflutter-fluwx