feat: add device-based consent to override MPID-scoped consent

[denischilik]

Add device-level consent state

Summary

Adds a device-level consent state that, when set, supersedes user/MPID-level consent everywhere consent is evaluated. Previously consent could only be recorded per-user (per-MPID), meaning consent decisions were lost across identity changes and couldn't represent a single device-wide choice. This adds an optional device-scoped consent that takes precedence over per-user consent.

When device consent is set, it overrides user/MPID-level consent for:

• Kit enablement — consent forwarding rule evaluation (shouldIncludeFromConsentRules)
• Consent forwarding to kits — onConsentStateUpdated forwarded calls
• Uploads — the consent block included in batches, for all MPIDs

It is persisted device-wide (independent of the active MPID, stored in app-level SharedPreferences) and setting it triggers the same kit refresh as a user consent change. Set it to null to clear and revert to user/MPID-level consent.

MParticleOptions.deviceBasedConsentEnabled(true) additionally mirrors MParticleUser.setConsentState() into device storage, so existing consent-prompt code continues to work without changes when the MPID changes during checkout.

How it works

A new getEffectiveConsentState(mpid) on ConfigManager is the single resolution point: it returns the device consent if present, otherwise falls back to the per-MPID consent. All consent-evaluation call sites now route through it.

deviceBasedConsentEnabled is persisted across launches. When enabled, MParticleUserDelegate.setConsentState() writes to both MPID storage and device storage so consent collected on an anonymous profile is retained after identity changes.

Sample code

Enable device mirroring at startup (recommended for consent-before-login flows):

MParticleOptions options = MParticleOptions.builder(context)
        .credentials("KEY", "SECRET")
        .deviceBasedConsentEnabled(true)
        .build();

MParticle.start(options);

val options = MParticleOptions.builder(context)
    .credentials("KEY", "SECRET")
    .deviceBasedConsentEnabled(true)
    .build()

MParticle.start(options)

Set / update / clear at runtime:

// Set device-wide consent (supersedes any per-user consent)
ConsentState consent = ConsentState.builder()
        .addGDPRConsentState("data_sharing", GDPRConsent.builder(true)
                .document("privacy_policy_v3")
                .build())
        .build();
MParticle.getInstance().setDeviceConsentState(consent);

// Clear it — reverts to user/MPID-level consent
MParticle.getInstance().setDeviceConsentState(null);

// Set device-wide consent (supersedes any per-user consent)
val consent = ConsentState.builder()
    .addGDPRConsentState(
        "data_sharing",
        GDPRConsent.builder(true).document("privacy_policy_v3").build(),
    )
    .build()
MParticle.getInstance().setDeviceConsentState(consent)

// Clear it — reverts to user/MPID-level consent
MParticle.getInstance().setDeviceConsentState(null)

Testing

Added unit tests covering device-consent override precedence and flag persistence (ConfigManagerTest), and updated the public API surface count (ApiVisibilityTest).

Related iOS PR: mParticle/mparticle-apple-sdk#784

[cursor]

PR Summary

High Risk
Changes how consent is resolved for event uploads and kit forwarding—privacy/compliance-critical paths—with new persisted override behavior that apps may enable via options.

Overview
Adds device-level consent that can override per-MPID consent for kit forwarding rules and upload batches—addressing cases where MPID changes (e.g. after identify) would otherwise drop consent set on an anonymous profile.

New public surface: MParticle.getDeviceConsentState() / setDeviceConsentState() (clear with null), isDeviceBasedConsentEnabled(), and MParticleOptions.Builder.deviceBasedConsentEnabled(). When that option is on, existing MParticleUser.setConsentState() also mirrors consent to device storage without extra app calls.

ConfigManager persists device consent and the enabled flag in SharedPreferences and exposes getEffectiveConsentState(mpid); reads/writes for user consent, batch uploads (MessageBatch), and kit updates now use the effective state. Unit tests cover override behavior and flag persistence; changelog documents the feature.

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

[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 2e277cd. Configure here.}

[cursor]

Stale device consent without flag

Medium Severity

After deviceBasedConsentEnabled is off at startup, a device consent value previously written by mirrored setConsentState can remain in preferences. getEffectiveConsentState still prefers that stored device consent, but setConsentState no longer updates device storage, so MPID consent changes may not reach kit forwarding or uploads.

Additional Locations (1)

• android-core/src/main/java/com/mparticle/identity/MParticleUserDelegate.java#L281-L289

 

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud