flutter_store_listing 2.1.0
flutter_store_listing: ^2.1.0 copied to clipboard
Flutter plugin to handle app reviews with the StoreKit review API on iOS and macOS, and to generate and open store listings for the App Store, the Mac App Store and Google Play.
2.1.0 #
The StoreKit review prompt now works on macOS, and the package declares the
macOS platform. 2.0 gave macOS the store listing in Dart and deferred the
prompt, on the grounds that the native side needs a view controller rather
than a window scene. That premise was right, and the SDK says so exactly:
AppStore.requestReview(in:) takes a UIWindowScene on iOS and an
NSViewController on macOS.
isInAppReviewSupportedanswers true on macOS, where it answered false. A widening, which is what makes this a minor release: UI that gated on the getter gains a working prompt.- Read this one if your Mac app has a "Rate this app" button. On 2.0,
requestReview()on macOS always fell back to the write-review page, so a button wired to it opened the Mac App Store every time. On 2.1 it asks StoreKit instead — which is rate-limited per user and per app version and usually shows nothing, while still reportinginAppReviewRequestedandisSuccess == true. A deterministic action has become a best-effort one. For a control the user pressed deliberately, callopenStoreListing(writeReview: true)instead;requestReview()is for the prompt you ask for on the app's own initiative. - One Swift source tree for both Apple platforms.
ios/is nowdarwin/, withsharedDarwinSource: trueon both platform entries, one podspec and onePackage.swift. There is nothing to change in your own code — Flutter resolves the new path itself, under CocoaPods and Swift Package Manager alike. A CocoaPods project will see itsPodfile.lockrewritten with the new path on the nextpod install, which matters only if you run it with a frozen lockfile in CI. - macOS 12 is still supported. The modern API needs macOS 13; below that
the prompt falls back to the deprecated no-argument
SKStoreReviewController.requestReview(), rather than the package raising Flutter's own floor for one call. - A new
noPresenterreply maps toinAppReviewUnavailable, so the fallback runs. It means there is no visible window to present into. That is not macOS's version of iOS'snoActiveScene, which suppresses the fallback because it is transient — see below. StoreKitInAppReview.supportsPlatformis new, a static synchronous answer to "does this package ship a prompt for this platform".
Two bugs found on the way #
The first draft suppressed the fallback on a windowless Mac. noPresenter
was mapped to inAppReviewNotNow by analogy with iOS, on the reasoning that a
store page is no more showable than a dialog when there is nowhere to show it.
That reasoning was wrong: on macOS the listing opens in the Mac App Store
app, a separate process needing no window in the calling app. A host with no
visible window — a status-item app, or one whose window has been closed —
would have got nothing at all on 2.1 where 2.0 opened the write-review sheet,
and would have gone on getting nothing, since such an app need never grow a
window. It is inAppReviewUnavailable now, and the native side checks for a
visible window rather than merely a view controller, so a hidden or minimised
window reaches the fallback too.
isInAppReviewSupported kept its own copy of the platform list. The getter
is synchronous and InAppReviewPrompt.isAvailable() is not, so the same fact
was written twice — and teaching the prompt about macOS left the getter saying
platform == StorePlatform.iOS with the whole suite still green, because
nothing compared the two. The getter now asks
StoreKitInAppReview.supportsPlatform, and a test holds them to the same
answer for every StorePlatform value, including ones added later.
2.0.0 #
Breaking: every method returns a StoreListingOutcome instead of a bool,
the platform is a value rather than a compile-time global, and the iTunes
lookup is gone. The design and its reasoning are in
doc/api-2.0-design.md.
What this fixes #
- macOS, Windows, Linux and web used to take the Android branch. A macOS
build opened a Google Play web page for a macOS bundle id and returned
true. macOS now opens its own App Store listing — in the Mac App Store app, verified on macOS 27.0.1, with?action=write-reviewbringing up the store's Write a Review sheet; the rest reportunsupportedPlatform. - A bare
boolcould not tell "no app store here" from "could not resolve the id" from "the launcher refused" — or, when the id resolved to the string"null", from success.StoreListingOutcomedistinguishes all of them, andoutcome.isSuccessis there when you do not care which. getIosAppId()did a network call to discover a build-time constant. It hit the iTunes/lookupendpoint on every launch, passed nocountryso it searched the US storefront only — an app not published in the US failed permanently, not just offline — andresults[0]['trackId'].toString()yielded the literal string"null"on a missing field, which then launched/idnull. Deleted.appStoreIdis a configuration value, and thehttpdependency is gone from every consumer's tree with it.- Nothing was testable. The platform came from a conditional import, and
the iOS prompt was a
static const MethodChannelwith no seam, so neither could be faked. Both are injectable now and the suite covers every outcome. - iOS could claim a prompt it had not shown. The Swift side fell back to an
arbitrary member of
connectedSceneswhen none was foreground-active, then reported success. It now says so, and you get the newinAppReviewNotNow— no fallback runs, because that state is transient and the user never asked to leave the app. An app requesting a review from a post-frame callback at startup sees this sometimes; ask again later.
Migration #
| 1.4.0 | 2.0.0 |
|---|---|
FlutterStoreListing() |
FlutterStoreListing.instance — there is no unnamed constructor, deliberately |
FlutterStoreListing.customize(…) |
FlutterStoreListing.custom(…) |
forceIosAppId |
appStoreId, a configure()/custom() argument; no public field |
forceAndroidPackageName |
androidPackageName, likewise argument-only |
isSupported() |
isStoreListingSupported — synchronous |
isSupportedNativeRequestReview() |
isInAppReviewSupported — synchronous |
launchStoreListing({iosWriteReview}) |
openStoreListing({writeReview}) — default flipped to false |
launchRequestReview({onlyNative}) |
requestReview({fallback}) |
getIosAppId(), getAndroidPackageName() |
storeId() |
getIosStoreListing(), getAndroidStoreListing() |
appStoreUri(), playStoreWebUri() — static, returning Uri |
urlCanLaunch, defaultUrlCanLaunch |
removed; unused since 1.4.0 |
urlLaunch, defaultUrlLaunch |
the StoreListingLauncher seam |
playStorePackageName |
removed; the default launcher is the only thing that needed it |
| — | configure(), storeListingUri(), StorePlatform, ReviewFallback |
Most of that is a compile error if you miss it, which is why the unnamed
constructor was removed rather than kept as a generative one: it would have
gone on compiling while quietly returning an instance configure() never
touched.
Two changes are silent, so check them.
- Configure
appStoreId, or Apple platforms reportstoreIdUnavailable. The iTunes lookup that used to find it is gone. Debug builds assert; release builds report the outcome, because an app may legitimately run unconfigured. Verify the id before you ship. - Desktop and web flip from
trueto false. A call site that branched on the oldboolseesisSuccess == falsewhere it used to see success after opening a Google Play page. That is the first bug above being fixed, but no compiler will point at it.
// Before
FlutterStoreListing().launchRequestReview(onlyNative: true);
await FlutterStoreListing().launchStoreListing();
// After — note writeReview: true to keep 1.4.0's behaviour, since the
// default is now the plain listing.
FlutterStoreListing.configure(appStoreId: '1479297675');
await FlutterStoreListing.instance
.requestReview(fallback: ReviewFallback.none);
await FlutterStoreListing.instance.openStoreListing(writeReview: true);
Also #
StoreListingOutcomemay gain values in a minor release, which is a breaking change by Dart's rules and so is said here rather than implied to be free. Keep adefaultclause in a switch statement, or a wildcard_case in a switch expression —defaultis a compile-time error in an expression.ReviewFallback,StorePlatformandInAppReviewRequestare closed.- The review fallback runs when there is no prompt, not when there is one
that cannot be shown yet.
InAppReviewPrompt.requestReview()returnsInAppReviewRequestrather than aboolso those two are distinguishable:unavailableruns yourReviewFallback,notNowreportsinAppReviewNotNowand does nothing. Aboolcould not carry it, becauseisAvailable()answers from the platform alone on iOS and so readstrueboth for an inactive scene and for a plugin that never registered — and those want opposite handling. If you implement the seam, note thatunavailableis the value for a failure, which is whatfalseused to mean. InAppReviewPromptis the Android in-app review seam. A separate package can implement it against Play's review API and you wire it in withconfigure(inAppReview: …), so the proprietary Play dependency stays out of this package and out of F-Droid builds. No such package is published yet.- A prompt passed to
configure()is preferred, not substituted.configure()is global and a prompt is usually platform-specific, so the one call above would otherwise have replaced StoreKit on iOS for every app that ships on both stores — and a Play-backed prompt reports itself unavailable on iOS, so the user who should have seen the native rating dialog got the App Store write-review page instead. The configured prompt is asked first on every platform and this package's own prompt stays behind it (PreferredInAppReview). A prompt passed tocustom()still wins outright. - The bundled implementations are exported
(
DefaultStoreListingLauncher,PackageInfoStoreIdentity,StoreKitInAppReview,PreferredInAppReview), so you can decorate the default behaviour — log a launch, confirm before leaving the app — instead of reimplementing the Android store intent to get at it. - macOS support is Dart-only and
pubspec.yamldeclares no macOS platform, so pub.dev badges this package Android and iOS. The macOS path builds anapps.apple.comURL and hands it tourl_launcher, so there is no native implementation here to register; declaring the platform means shipping amacos/directory, which lands with the native macOS prompt. The listing works on macOS with no extra step on your side. The example app now has a macOS target, so this is reproducible rather than asserted. configure()merges: an argument left out keeps its current value, so an app's own call and a review package's compose rather than overwriting.- The shared instance reads its configuration per call, so a reference
captured in a
Statefield initialiser beforemain()configures it still works. - The Android Kotlin implementation is unchanged from 1.4.0 apart from the
no_activitycomment, which described the Dart retry this release removes. The Dart side now distinguishesMissingPluginException(fall back tourl_launcher) from aPlatformExceptionsuch asno_activity(do not —url_launcherisActivityAwaretoo and detached in the same window), and a reply it cannot read — a wrong type included — falls back rather than throwing out of a method that promises an outcome.
1.4.0 #
Android gets a native implementation, and the market:// probe is gone.
launchStoreListing used to ask canLaunchUrl('market://') and open
market://details?id=… when that said yes. On a device where the app was
installed from the Play Store it generally did say yes: Android makes "the app
that installed your app" visible automatically, with no <queries> entry and
whatever the targetSdk. For most users, then, market://details?id=… is
what actually opened, and this release changes the route rather than the
destination — both it and the https URL with the package set land in the
Play Store app.
The probe did fail for installs from outside the Play Store — sideloaded, or
from another store — on an app targeting API 30 or higher with no <queries>
entry of its own, because com.android.vending is then not automatically
visible. Those users got the https URL in a browser, and still do whenever the
Play Store app is absent.
It now opens the listing the way Google's "Linking to Google Play" guide
documents: an ACTION_VIEW intent for the play.google.com URL with the
package set to com.android.vending, which url_launcher cannot express.
When the Play Store app is absent or disabled the same URL is viewed without
the restriction, so devices without Play — F-Droid installs among them — still
reach the listing in a browser. No <queries> entry is needed: the
implementation attempts the intent and handles ActivityNotFoundException
rather than querying, which package visibility does not filter.
For most users this is the behaviour they already had, now arrived at on purpose and by the route Google documents, rather than through a probe whose answer depended on how the app had been installed. On a device without the Play Store app, the listing still opens in whatever claims Play links.
- The package declares
androidinflutter.plugin.platformsfor the first time, so pub.dev lists Android support that was always there in practice. Every consumer's Android build therefore gains a Gradle module and a Kotlin compile step, and the module declaresminSdk 24— Flutter's own floor, and the same valueurl_launcher_androiddeclares, so an app already pullingurl_launcheris at 24 regardless. - The Android side has no
implementationdependencies: no androidx, and in particular no Play Core, so Play's in-app review API is still deliberately out of this package and it stays clean in F-Droid builds. JUnit, Mockito and Robolectric aretestImplementationonly, resolved when the module's own tests are run. FlutterStoreListing.customize(urlCanLaunch: …)still compiles but is no longer called by this package. It is removed in 2.0.FlutterStoreListing.playStorePackageNameis exposed for callers building their own intents.
1.3.0 #
Requires Flutter 3.44 / Dart 3.10. Swift Package Manager support needs the
generated FlutterFramework Swift package, which Flutter only produces from
3.44.0 on.
Behaviour change: launchRequestReview no longer contradicts its own
documentation. It was inverted in both branches, so iOS callers got the
opposite of what the API said:
- A successful native prompt also opened the App Store write-review page, ejecting the user to the App Store immediately after the in-app dialog. The two are now exclusive — the store listing is the fallback for when the native dialog is unavailable, which is what the doc comment always claimed.
onlyNative: truereturnedfalseprecisely when the prompt had been shown, and the iOS branch returnedtruewhen the native call had failed and nothing at all had happened. Both are now the right way round:truemeans a review was asked for,falsemeans it was not.
If you branch on the return value of launchRequestReview(), re-check it. If
you call it for its side effect only, the visible change is that iOS users are
no longer sent to the App Store after being shown the in-app prompt.
- Allow
package_info_plus10.x (widened to>=1.0.3 <11.0.0). This was the only thing making version solving fail for apps that needpackage_info_plus10.x. - Add Swift Package Manager support. The plugin ships
ios/flutter_store_listing/Package.swiftalongside the podspec, so it no longer appears in Flutter's "plugins do not support Swift Package Manager" warning. CocoaPods consumers are unaffected; both build the same sources. - Rewrite the iOS plugin in Swift. This is a prerequisite for the item
below:
AppStore.requestReview(in:)is a Swift-only StoreKit 2 API and cannot be called from Objective-C. - iOS: use
AppStore.requestReview(in:)on iOS 16+. The wholeSKStoreReviewControllerclass is deprecated as of iOS 18; the deprecatedrequestReview(in:)remains the fallback for iOS 15. The old@available(iOS 10.3, *)guards and the no-scenerequestReview()call are gone. - Remove the Android platform entry. Its
onMethodCallonly ever returnednotImplemented(), and the Dart side never invoked the channel off iOS, so consumers were building an AAR for nothing. Nothing changes at runtime: Android still opens the Play listing throughurl_launcher. Play's in-app review API is deliberately left out so this package stays free of proprietary dependencies, which would otherwise reach F-Droid builds. - Fix
forceAndroidPackageNamebeing ignored bylaunchStoreListing(), which read the package name straight frompackage_info_plus. - The package is now WebAssembly-compatible:
dart:iois behind a conditional import instead of being imported unconditionally forPlatform. - Remove the discontinued
pedanticdependency (it was unused, and declared as a runtime instead of a dev dependency). - iOS: use
httpsfor the iTunes lookup API — App Transport Security blocks cleartexthttpby default, so this likely failed on device unless the host app carried an ATS exception. - iOS: generate store listing URLs for
apps.apple.comwithout a hardcoded/us/storefront, instead of the legacyitunes.apple.com/us/app/id…form. - Give the iOS podspec real metadata (it was unedited template boilerplate) and a 15.0 deployment target, matching the oldest iOS that Flutter 3.44 itself supports.
- Add an actual test suite — the previous one was an empty
main()— and a GitHub Actions workflow that analyzes, formats, tests and builds the example for iOS.
1.2.0 #
- Update AGB Version, Android SDK Version, etc.
1.1.0 #
- Compatibility with Flutter 3.29
1.0.0 #
- Upgrade
package_info_plusdependency.
0.3.1 #
- Upgrade dependencies.
0.3.0 #
- Upgrade dependencies
- Android: Upgrade to AGP 8.1, migrate namespace, etc.
0.2.2 #
- Update dependencies, dart 3.0
0.2.1+1 #
- Update dependencies.
0.2.1 #
- update to dependency
package_info_plus
0.2.0+1 #
- Remove unnecessary casts.
0.2.0 #
- Nullsafety migration.
0.1.1+2 #
- More documentation, updated links.
- No longer a singleton, override app store id and android package name.
- Add isSupported() methods.
- Made API more consistent.
- Added simple example.
0.1.0 #
- First release
0.0.1 #
- Initial version