feat: add per-hook evaluation exposure deduplication

[abelonogov-ld]

Summary

Opt-in deduplication of evaluation exposures for hooks. A hook is told about every evaluation until you wrap it, so nothing changes for existing hooks:

Components.hooks()
    .addHook(new MetricsHook())                                    // every evaluation
    .addHook(new DedupingHook(new ObservabilityHook()))            // 10 minute window
    .addHook(new DedupingHook(new TelemetryHook(), 60_000))
    .addHook(new DedupingHook(new ExperimentHook(), myCustomDeduper))

New public API, all in com.launchdarkly.sdk.android.integrations:

• HookDecorator — an abstract hook that forwards every stage to the hook it wraps, and reports that hook's metadata. Decorators stack in either order.
• DedupingHook — a decorator that suppresses an evaluation whose result the wrapped hook has just been told about. Wrap with a window, or with a deduper of your own.
• EvaluationExposureDeduper — the policy. The window is its only setting. Subclass it to decide differently; shouldRecord and reset are the only methods DedupingHook calls.
• EvaluationExposureKey — what identifies an evaluation result: environment name, flag key, variation, flag version, experiment status, and fully qualified context key.
• EvaluationSeriesContext.getEvaluationExposureKey() — resolves that identity on demand, along with the EvaluationExposureKeySupplier the SDK hands the series context to resolve it with. An evaluation costs a flag lookup only when a hook asks, and only once however many hooks ask.

The policy keeps one record per flag per environment, holding the result that flag last reported. The wrapped hook hears about the flag again as soon as the result changes, and once per window while it stays the same. Tracking the last result rather than every result seen means a flag flipping back and forth cannot hide its flips, and it bounds the records to the flags the environment serves.

The decision is taken in beforeEvaluation, before the series opens, so a suppressed evaluation reaches neither stage of the wrapped hook. Hooks pair their stages: the observability plugin starts a span in the before stage and ends it in the after one, so suppressing only the after stage would leave that span in its map to be evicted later and exported with a meaningless duration and no feature_flag event.

LDClient.identify clears what the wrapped hook has been told about, so the first evaluation of each flag afterwards always reaches it. Analytics events are untouched: feature, debug, and summary events are still recorded for every evaluation, so the evaluation counts LaunchDarkly reports for a flag do not change.

Describe alternatives you've considered

• A deduper configured on Hook itself. It was the first shape this took. It puts a policy on the interface that every hook implementer has to think about, and it cannot be composed, so a hook that wanted deduplication plus anything else had nowhere to put the second behavior. The decorator gives both without touching Hook.
• Filtering only afterEvaluation. This is what the browser and React Native observability plugins do, and it is much less machinery: no exposure key before the evaluation, no supplier, no suppression marker in the series data. It is wrong here, because the mobile observability hook pairs its stages, as above.
• Deduplicating on every distinct exposure seen, rather than one record per flag. A flag that flips between two results would report neither flip after the first, and the set of remembered exposures grows with every result a flag has ever had.
• Wall clock time for the window. A correction that moves the device clock backwards leaves every recorded time in the future, so those flags stay suppressed until real time catches up, which for a large correction is hours of dropped exposures. Windows are measured against SystemClock.elapsedRealtime(), which no correction reaches and which, unlike System.nanoTime(), keeps counting while the device sleeps.

Additional context

• Additive and off by default. An unwrapped hook behaves exactly as it does today.
• A hook set on LDConfig is one instance shared by the clients for every environment in secondaryMobileKeys, and so is its deduper. The environment is therefore part of both the exposure key and the per-flag record; sharing a record across environments would make each look like the other having changed its result, and neither would ever be suppressed.
• Experiment status is a component of the key in its own right, because the version reported on events is the flag's own version: a prerequisite flipping can move an evaluation into or out of an experiment while it lands on the same variation of the same flag version.
• Mirrored on iOS in launchdarkly/ios-client-sdk, with docs in sdk-meta and ld-docs-private.

---

Note

Overview
Adds opt-in per-hook evaluation exposure deduplication. Wrap a hook in DedupingHook to suppress repeated same-result evaluations within a configurable window (default 10 minutes); unwrapped hooks still see every evaluation.

New public API in integrations: DedupingHook, EvaluationExposureDeduper, EvaluationExposureKey, and on-demand EvaluationSeriesContext.getEvaluationExposureKey(). Suppression happens in beforeEvaluation so both hook stages are skipped together. identify resets the cache. Analytics events are unchanged.

LDClient now reads the flag and context once before hooks run, so exposure keys describe the result that evaluation actually returns. Also adds HooksConfigurationBuilder.addHook() and updates the example app to demo dual-window dedupe plus local.properties-based mobile key / staging config.

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

[kinyoklion]

Some SDKs used to have functionality like this and it was removed. Not all data is available in the client as to which events matter when. Like an experiment iteration. So we don't dedupe events. We can offer ways and guidance about how to avoid these situations. And you are welcome to de-dupe obersavability data.

[abelonogov-ld]

Some SDKs used to have functionality like this and it was removed. Not all data is available in the client as to which events matter when. Like an experiment iteration. So we don't dedupe events. We can offer ways and guidance about how to avoid these situations. And you are welcome to de-dupe obersavability data.

@kinyoklion Sure, I am not going to dedup events at all, it should only dedup evaluation hook call. I will removes events from it. I feel this functionality where triggered by a customer story

[tanderson-ld]

it should only dedup evaluation hook call

I'm not sure I agree with this. I think we should put this dedupe logic in as narrow a spot and as close to the consumer as possible since it does result in loss of information. If you want one hook to get all evals and another to get deduped, configuring it at the top level doesn't work.

Can you make a hook decorator that does the deduping and you just wrap your hook in deduping decoration if you want it?

[cursor]

Cursor Bugbot has reviewed your changes using default effort 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 3cba0c4. Configure here.}