[JuroUhlar]

Part of INTER-2593.

• Exit changesets pre-release mode, so the next release is 5.0.0
• Fold the patch changesets into v5-api-migration.md, written relative to 4.13.1 (JitPack removal, background thread, endpoint validation)
• Add a README callout linking the migration guide
• Bump @fingerprintjs/changesets-native-dependency-format to 0.2.1
• Fix formatting of the 5.0.0-test.* entries in CHANGELOG.md

Discussion point: one changeset only

One changeset gives 4.x users a single set of release notes. Verified locally with changeset version.

With several changesets, formatter 0.2.0 put the native SDK version section after the first entry. 0.2.1 fixes this, and the test entries are fixed by hand.

Discussion point: R8 rules fix dropped from notes

It only fixed a regression in the test releases, so it means nothing to 4.x users. The rules still ship.

[Copilot]

Copilot review overview

🟢 Approval recommended

The changes consistently prepare a single complete 5.0.0 release entry with matching formatter and prerelease configuration updates.

Review effort: Balanced
Findings: None

What changed in this PR

Prepares the unified 5.0.0 release notes and exits prerelease mode.

Changes:

• Consolidates migration notes into one major changeset.
• Corrects prerelease changelog formatting and adds a README callout.
• Updates the changeset formatter to 0.2.1.

File	Description
README.md	Highlights the 5.0.0 migration guide.
CHANGELOG.md	Corrects prerelease note formatting.
package.json	Updates the changeset formatter.
pnpm-lock.yaml	Locks formatter version 0.2.1.
.changeset/​pre.json	Exits prerelease mode.
.changeset/​v5-api-migration.md	Consolidates final migration notes.
.changeset/​validate-endpoints.md	Removes the merged patch changeset.
.changeset/​native-background-queue.md	Removes the merged patch changeset.
.changeset/​drop-jitpack-repo.md	Removes the merged patch changeset.
.changeset/​android-release-r8-rules.md	Removes the prerelease-only regression note.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 Following releases will be created using changesets from this PR:

fingerprint_flutter@5.0.0

Major Changes

• Migrated the SDK to Fingerprint API v4. This is a breaking change on every platform.

  Requirements

  • Flutter 3.44.0 and Dart 3.12.0.
  • Android 7.0 (API 24+). Native SDK 4.1.x. The plugin no longer applies the Kotlin Gradle plugin, so it builds under AGP 9. Apps on AGP 8 need Kotlin Gradle plugin 2.2.20 or newer. The plugin no longer adds the jitpack.io repository. If your app uses JitPack dependencies, declare the repository yourself.
  • iOS 15 / tvOS 15, Xcode 16, Swift 6. Native SDK 4.1.x (Fingerprint-iOS).
  • Only native patch releases are picked up automatically.
  • Web uses the bundled @fingerprint/agent v4. There is no extra npm peer dependency.

  Package

  fpjs_pro_plugin is now fingerprint_flutter.

  - fpjs_pro_plugin: ^4.13.1
  + fingerprint_flutter: ^5.0.0
  
  - import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
  + import 'package:fingerprint_flutter/fingerprint_flutter.dart';

  API

  • package:fingerprint_flutter/fingerprint_flutter.dart is the only public import. error.dart, result.dart, and region.dart are gone. pluginVersion is renamed to fingerprintFlutterVersion. Region.stringValue is removed, use Region.name.
  • Static FpjsProPlugin.initFpjs / getVisitorId / getVisitorData are replaced by an instance Fingerprint client with get({tags, linkedId, timeout}).
  • The constructor is synchronous and starts the client. Identification failures surface on get. On Android and iOS:
    • The native client is created and get starts on a background thread, so creating the client at app startup does not block the UI thread.
    • The constructor throws FlutterError if the Flutter binding does not exist yet, so call WidgetsFlutterBinding.ensureInitialized() first, as with initFpjs.
  • Timeouts are Duration. endpoint + endpointFallbacks become one endpoints list. Platform options nest under android, ios, and web.
  • scriptUrlPattern, scriptUrlPatternFallbacks, and extendedResponseFormat are removed.
  • tags must be JSON-compatible (string keys, finite numbers, no typed lists). get throws ArgumentError right away for invalid tags or a timeout under 1 ms, before identifying. The constructor throws ArgumentError for an endpoints entry that is not an http or https URL, or an android.locationTimeout under 1 ms.
  • Custom endpoints still get no automatic fallback on any platform, even though JS agent v4 adds one by default. List the regional default URL last if you want it.
  • On Android and iOS, region still defaults to Region.us. Set it for EU and AP workspaces.

  - await FpjsProPlugin.initFpjs(
  -   '<PUBLIC_API_KEY>',
  -   region: Region.eu,
  -   endpoint: 'https://metrics.example.com',
  -   endpointFallbacks: ['https://metrics2.example.com'],
  -   allowUseOfLocationData: true,
  -   locationTimeoutMillisAndroid: 5000,
  -   scriptUrlPattern:
  -       'https://metrics.example.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
  - );
  - final data = await FpjsProPlugin.getVisitorData(
  -   tags: {'userAction': 'login'},
  -   linkedId: 'user_1234',
  -   timeoutMs: 5000,
  - );
  + final fp = Fingerprint(
  +   apiKey: '<PUBLIC_API_KEY>',
  +   region: Region.eu,
  +   endpoints: [
  +     'https://metrics.example.com',
  +     'https://metrics2.example.com',
  +   ],
  +   android: const AndroidOptions(
  +     allowUseOfLocationData: true,
  +     locationTimeout: Duration(seconds: 5),
  +   ),
  +   ios: const IosOptions(allowUseOfLocationData: true),
  +   web: const WebOptions(
  +     cache: WebCache(
  +       storage: WebCacheStorage.sessionStorage,
  +       duration: WebCacheDuration.optimizeCost,
  +     ),
  +   ),
  + );
  + final result = await fp.get(
  +   tags: {'userAction': 'login'},
  +   linkedId: 'user_1234',
  +   timeout: const Duration(seconds: 5),
  + );
  + print(result.visitorId);
  + print(result.eventId);
  + print(result.suspectScore);

  Result

  • FingerprintResult: eventId, visitorId?, suspectScore?, sealedResult?, cacheHit? (web only).
  • requestId is now eventId. confidence / confidenceScore and the extended types (ipLocation, firstSeenAt, and the rest) are gone.
  • visitorId is null when hidden (Zero Trust).

  Errors

  One FingerprintError (code, message?, eventId?). Discriminate on error.code. Network failures report code: 'network_error'. On web, a failed agent script download reports script_load_fail. FingerprintError does not extend PlatformException; if you catch SDK errors with on PlatformException, switch to FingerprintError.

    try {
  -   await FpjsProPlugin.getVisitorData();
  - } on FingerprintProError catch (error) {
  -   if (error is TooManyRequestError) {
  +   await fp.get();
  + } on FingerprintError catch (error) {
  +   if (error.code == FingerprintError.tooManyRequests) {
        // handle rate limiting
      }
    }

  Web

  Caching is off unless you pass web: WebOptions(cache: ...).

  - <script src="assets/packages/fpjs_pro_plugin/web/index.js" defer></script>
  + <script src="assets/packages/fingerprint_flutter/web/index.js" defer></script>

  If this tag is missing, get throws script_load_fail. (f680434)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 4.1.0 and < 4.2.0
• Fingerprint Android SDK Version Range: >= 4.1.0 and < 4.2.0