feat(remote-feature-flag-controller): segment threshold flags by metaMetricsFlags with canonical ID default

[asalsys]

Summary

• Add optional getCanonicalProfileId constructor callback and metaMetricsFlags map for threshold flag segmentation.
• Threshold flags use canonical profile ID by default; flags whose names are present in metaMetricsFlags use MetaMetrics ID instead.
• Generalize threshold calculation to hash the selected segmentation ID while preserving the existing deterministic bucketing behavior.
• Pass the new optional segmentation options through @metamask/wallet remote feature flag controller initialization.

Segmentation Behavior

Flag configuration	Identifier used	Constructor callback
Flag name absent from metaMetricsFlags	Canonical profile ID	getCanonicalProfileId()
Flag name present in metaMetricsFlags	MetaMetrics ID	getMetaMetricsId()

If the selected identifier is empty, threshold arrays are preserved as-is and not processed.

Example threshold config using canonical segmentation by default:

{
  "myCanonicalFlag": [
    {
      "name": "groupA",
      "scope": { "type": "threshold", "value": 0.5 },
      "value": "valueA"
    },
    {
      "name": "groupB",
      "scope": { "type": "threshold", "value": 1.0 },
      "value": "valueB"
    }
  ]
}

Example controller setup for a flag that should keep MetaMetrics segmentation:

new RemoteFeatureFlagController({
  // ...
  getMetaMetricsId,
  getCanonicalProfileId,
  metaMetricsFlags: {
    legacyMetaMetricsFlag: true,
  },
});

Migration

Consumers must pass getCanonicalProfileId for threshold flags that should use canonical profile segmentation, which is now the default for flags absent from metaMetricsFlags.

Existing threshold flags that must keep MetaMetrics-based bucketing should be listed in metaMetricsFlags and continue to provide getMetaMetricsId.

Test plan

• yarn workspace @metamask/remote-feature-flag-controller run jest --no-coverage src/utils/user-segmentation-utils.test.ts src/remote-feature-flag-controller.test.ts
• Threshold flags absent from metaMetricsFlags use getCanonicalProfileId for segmentation
• Threshold flags present in metaMetricsFlags use getMetaMetricsId for segmentation
• Threshold arrays are preserved when the selected identifier is empty
• Threshold cache entries use the selected segmentation ID and stale entries are cleaned up when flags are removed from the server response

Related

• Documentation: MetaMask/contributor-docs#176

---

Note

High Risk
Changes default A/B bucketing for threshold flags, so users can land in different groups unless legacy flags are listed in metaMetricsFlags; rollout and cache behavior are user-facing and migration-sensitive.

Overview
Threshold rollout no longer always keys off MetaMetrics ID. RemoteFeatureFlagController now accepts optional getCanonicalProfileId and metaMetricsFlags: flags not listed in the map hash canonicalProfileId + flag name for bucketing and cache keys; flags in the map keep MetaMetrics-based segmentation (for legacy behavior).

When the chosen segmentation ID is empty, threshold arrays are left unprocessed (same as before for missing MetaMetrics). Explicit metaMetricsIds targeting is unchanged but only runs when MetaMetrics ID is available. calculateThresholdForFlag is generalized to any non-empty segmentation ID. Stale thresholdCache cleanup now drops entries for either the current MetaMetrics or canonical ID.

@metamask/wallet forwards the new options into remote feature flag initialization. Tests and changelogs are updated accordingly.

^{Reviewed by Cursor Bugbot for commit 9c6a7a1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[NicolasMassart]

Two comments, one blocking and a nit.

[NicolasMassart]

issue (blocking): idType is modeled as a per-entry property, but getThresholdIdType determines the segmentation ID by looking only at the first valid threshold entry. That means a mixed configuration silently uses the first entry's idType for the entire flag, making the behavior dependent on entry ordering.

If mixed idType values are not intended, it would be safer to validate that all threshold entries agree and fail fast (or move idType to a flag-level configuration). Otherwise, please add a test documenting the intended behavior for mixed configurations.

[asalsys]

Outdated we are removing idType and passing metaMetricsFlags from the client.

[NicolasMassart]

nitpick (non-blocking): This comment still says unrecognized threshold versions fall back to the legacy { name, value } wrapper, but this PR removes that behavior and now always returns the selected value directly. The documentation should be updated to match the implementation.

[asalsys]

Outdated we are removing idType and passing metaMetricsFlags from the client.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b933ca5. Configure here.}