Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions acceptance/public/identify.feature
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,39 @@ Feature: Identify
| $anon_distinct_id | anon-123 |
| $set.email | user@test.test |

@client
Scenario: Identify while opted out updates identity and reloads flags without sending events
Given a fresh SDK acceptance test harness
And the SDK clock is fixed at "2025-01-01T00:00:00Z"
And persistent storage is empty
And the mock PostHog server is reset
And the SDK is initialized with token "test-token"
And the current distinct id is "anon-123"
And analytics capture is opted out
When identify is called with distinct id "user-123"
Then get distinct id should return "user-123"
And the mock server should receive a feature flag request for distinct id "user-123"
And no event should be enqueued

@client
Scenario: Identify while opted out does not suppress the same properties after opt in
Given a fresh SDK acceptance test harness
And the SDK clock is fixed at "2025-01-01T00:00:00Z"
And persistent storage is empty
And the mock PostHog server is reset
And the SDK is initialized with token "test-token"
And the current distinct id is "anon-123"
And analytics capture is opted out
When identify is called with distinct id "user-123" and properties:
| property | value |
| email | user@test.test |
And opt in is called
And identify is called with distinct id "user-123" and properties:
| property | value |
| email | user@test.test |
Then one event named "$set" should be enqueued
And no event named "$identify" should be enqueued

@sdk:server
Scenario: Server identify without explicit or contextual identity generates a personless UUID
Given an isolated SDK instance
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-02
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
## Why

`identify` lists "the user is opted out" as a guard that short-circuits the whole call (Behavior, client-side flow, step 1), and `opt-in` says opt-out short-circuits `identify`. posthog-js and posthog-android don't do this. Their `identify` keeps running while opted out: it updates local identity and reloads feature flags, and only the event it captures is dropped.

- posthog-js `identify()` (`packages/browser/src/posthog-core.ts:3327`) returns early only for an uninitialized SDK, an invalid distinct id, and `_requirePersonProcessing`. It has no consent check. The only opt-out gate is in `capture()` (`posthog-core.ts:1795`), which drops the event when `!this.is_capturing()`. `identify` caches the person-properties hash only when `capture()` accepted the `$identify` / `$set` event (`posthog-core.ts:3411-3424`), and reloads feature flags when the distinct id changes (`posthog-core.ts:3456-3461`).
- posthog-js decided that flag loading does not depend on opt-out: "Feature flag loading is no longer gated by capture opt-out" (PostHog/posthog-js#3596, [comment](https://github.com/PostHog/posthog-js/issues/3596#issuecomment-4797090791)).
- posthog-android `identify()` (`posthog/src/main/java/com/posthog/PostHog.kt:1592`) guards only on `isEnabled()` (setup called), person processing, and a blank distinct id (`PostHog.kt:1597-1609`). The opt-out check is in `capture()` (`PostHog.kt:972`). On a new distinct id it persists the identity and reloads flags (`PostHog.kt:1670`).

`bootstrap` already states the same rule for identified-bootstrap reconciliation: "opt-out suppresses event emission, not the local identity state".

posthog-js references are at `origin/main` 8c8327543. posthog-android references are at `origin/main` 8309f837.

## What Changes

- **Requirement** (`Canonical identify behavior`): client SDKs must not short-circuit `identify` on opt-out. While opted out, `identify` updates local identity state and person properties for flags, and reloads flags when the distinct id changes. It does not capture `$identify` or `$set`, and does not update the person-properties dedup hash for an event it did not capture. Two new `@client` scenarios: identify while opted out changes the distinct id, sends a flags request for the new distinct id, and enqueues no event. And after opt-in, identify again with the same properties still sends `$set`, because the opted-out call did not cache the hash.
- **Behavior prose** (`identify`, client-side flow step 1 and step 3, Error handling): opt-out is removed from the guards and the drop list, and the opted-out behavior is described. Applied at archive, outside the requirement delta.
- **Behavior prose** (`opt-in`, `optOut` step 3 and Interactions): opt-out blocks event capture. `identify` still updates local identity and reloads flags. What these sections say about `capture`, `group`, and `alias` is unchanged. Applied at archive, outside the requirement delta.
- **Acceptance** (`acceptance/public/identify.feature`): the two new `@client` scenarios, using existing step text.

## Capabilities

### New Capabilities

_None._

### Modified Capabilities

- `identify`: the `Canonical identify behavior` requirement gains one normative sentence and two `@client` scenarios. The existing scenarios are unchanged.
- `opt-in`: prose only (no requirement change).

## Impact

- **posthog-js**: conforms. Reference test: `packages/browser/src/__tests__/browser-next-differential/scenarios.ts:126` (`defaultOptOutScenario`, run by `browser-next-differential.test.ts:42`) checks that `identify` while opted out sets the distinct id and identified state and delivers no event. That harness disables feature flags (`legacy-browser-adapter.ts:54`), and no posthog-js test calls `identify()` after opt-out and asserts the flags request. The flags-reload part of this change has no covering reference test. For the dedup-hash rule, `packages/browser/src/__tests__/personProcessing.test.ts:1051` checks that an `$identify` dropped by capture (there via `before_send`) does not suppress a later `$set` with the same properties.
- **posthog-android**: conforms for identity and flags reload. In the same-id anonymous-to-identified transition, it updates the dedup hash after `capture()` whether or not the event was captured (`PostHog.kt:1693`), which differs from the dedup-hash rule here. Its new-id path does not cache the hash, so it passes the opt-in scenario.
- **posthog-ios**: a matching change is in progress on branch `fix/identify-flags-while-opted-out`.
- **posthog-react-native** (posthog-js `packages/core`): conforms for identity and flags reload. `identify` has no opt-out check (`packages/core/src/posthog-core.ts:351`), and opt-out is enforced when events are enqueued (`packages/core/src/posthog-core-stateless.ts:1281`). It caches the dedup hash on a new distinct id whether or not the event was captured (`packages/core/src/posthog-core.ts:399`), so it fails the opt-in scenario.
- Other client SDKs (Flutter, Unity) were not checked in this change.
- **Server SDKs**: not applicable (no opt-out state).
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
## MODIFIED Requirements

### Requirement: Canonical identify behavior

The SDK SHALL implement the canonical `identify` behavior described by this spec. Implementations MAY adapt method names, parameter casing, type syntax, and lifecycle hooks to platform idioms where this spec explicitly allows variation, but MUST preserve the observable outcomes in the scenarios below. Server SDKs MUST resolve an omitted per-call distinct id from request-scoped analytics context when available, otherwise generate a fresh UUID for the event and disable person-profile processing unless the caller explicitly supplied `$process_person_profile`. For legacy `/batch/` delivery, this control MUST be represented by `properties.$process_person_profile = false`; for Capture v1 `/i/v1/analytics/events` delivery, it MUST be represented by `options.process_person_profile = false` with no `$process_person_profile` sentinel left in `properties`. An explicit per-call distinct id MUST take precedence over context. Server `identify` MUST NOT throw or reject to the application when the distinct id is omitted. Generated ids MUST NOT be used for feature-flag evaluation or persisted as ambient user identity. Client SDKs MUST NOT short-circuit `identify` because the user is opted out: while opted out, `identify` MUST make the same local state changes it makes when opted in (distinct id, anonymous id, identified flag, person properties for flags, and the feature flag reload when the distinct id changes). Opt-out gates event capture only: the SDK MUST NOT capture or send the `$identify` or `$set` event, and MUST NOT update the person-properties dedup hash for an event it did not capture.

#### Scenario: Client identify changes the current distinct id and sends identity properties (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** the current distinct id is "anon-123"
- **WHEN** identify is called with distinct id "user-123" and properties:
| property | value |
| email | user@test.test |
- **THEN** get distinct id should return "user-123"
- **AND** one event named "$identify" should be enqueued
- **AND** the enqueued event properties should include:
| property | value |
| distinct_id | user-123 |
| $anon_distinct_id | anon-123 |
| $set.email | user@test.test |

#### Scenario: Identify with a distinct id already matching the anonymous id transitions to identified (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** the current distinct id is "anon-123"
- **AND** the SDK has not yet identified a user
- **WHEN** identify is called with distinct id "anon-123"
- **THEN** get distinct id should return "anon-123"
- **AND** one event named "$set" should be enqueued
- **AND** no event named "$identify" should be enqueued

#### Scenario: Identify while opted out updates identity and reloads flags without sending events (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** the current distinct id is "anon-123"
- **AND** analytics capture is opted out
- **WHEN** identify is called with distinct id "user-123"
- **THEN** get distinct id should return "user-123"
- **AND** the mock server should receive a feature flag request for distinct id "user-123"
- **AND** no event should be enqueued

#### Scenario: Identify while opted out does not suppress the same properties after opt in (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** the current distinct id is "anon-123"
- **AND** analytics capture is opted out
- **WHEN** identify is called with distinct id "user-123" and properties:
| property | value |
| email | user@test.test |
- **AND** opt in is called
- **AND** identify is called with distinct id "user-123" and properties:
| property | value |
| email | user@test.test |
- **THEN** one event named "$set" should be enqueued
- **AND** no event named "$identify" should be enqueued

#### Scenario: Server identify delivers a profile update for explicit distinct id (@server)
- **GIVEN** an isolated SDK instance and a fresh receiver
- **AND** the SDK is initialized with token "test-token" and flush threshold 20
- **WHEN** identify is called with distinct id "user-123" and properties `{ "email": "user@test.test", "active": false, "score": 0, "note": null }`
- **AND** pending captures are flushed
- **THEN** exactly one capture request contains exactly one `$identify` event
- **AND** the received event's root `distinct_id` equals `user-123`
- **AND** its `$set` equals the supplied JSON object, preserving boolean, numeric and null values

#### Scenario: Server identify delivers nested user properties (@server)
- **GIVEN** an isolated SDK instance and a fresh receiver
- **AND** the SDK is initialized with token "test-token" and flush threshold 20
- **WHEN** identify is called with distinct id "user-456" and properties `{ "preferences": { "theme": "dark" }, "tags": ["beta", "team"] }`
- **AND** pending captures are flushed
- **THEN** exactly one capture request contains exactly one `$identify` event
- **AND** the received event's root `distinct_id` equals `user-456`
- **AND** its `$set` equals the supplied nested JSON object

#### Scenario: Server identify without explicit or contextual identity generates a personless UUID (@server)
- **GIVEN** an isolated server SDK instance with no request-scoped identity and a fresh receiver
- **AND** the SDK is initialized with token "test-token" and flush threshold 20
- **WHEN** identify is called with person properties and no explicit distinct id
- **AND** pending captures are flushed
- **THEN** exactly one capture request contains exactly one `$identify` event
- **AND** the received event's root `distinct_id` is a generated UUID
- **AND** its `$set` equals the supplied person properties
- **AND** the received event has `properties.$process_person_profile` equal to `false` on legacy `/batch/`, or `options.process_person_profile` equal to `false` and no `properties.$process_person_profile` on Capture v1 `/i/v1/analytics/events`
- **AND** the SDK call does not throw or reject

#### Scenario: Server identify uses request-scoped analytics identity before generating one (@server)
- **GIVEN** an isolated server SDK instance with request-scoped analytics distinct id "context-user"
- **WHEN** identify is called without an explicit distinct id
- **AND** pending captures are flushed
- **THEN** the received `$identify` event's root `distinct_id` is "context-user"
- **AND** the SDK call does not throw or reject

#### Scenario: Server identify uses the explicit id before request-scoped analytics identity (@server)
- **GIVEN** an isolated server SDK instance with request-scoped analytics distinct id "context-user"
- **WHEN** identify is called with explicit distinct id "explicit-user"
- **AND** pending captures are flushed
- **THEN** the received `$identify` event's root `distinct_id` is "explicit-user"

#### Scenario: Client identify validates missing distinct id (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **WHEN** identify is called without a distinct id
- **THEN** identity state should not change
- **AND** no identity event should be enqueued
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
## 1. Spec delta

- [x] 1.1 Modify **Canonical identify behavior** in `identify` so client SDKs keep running `identify` while opted out, and add the identify-while-opted-out and same-properties-after-opt-in `@client` scenarios
- [x] 1.2 Add the matching scenarios to `acceptance/public/identify.feature` with existing step text

## 2. Prose alignment (applied at archive, outside the requirement-delta mechanism)

- [x] 2.1 `identify`: remove opt-out from Behavior step 1 guards and describe the opted-out behavior, make the step 3 dedup-hash update conditional on capture, and remove "opted-out user" from the Error handling drop list
- [x] 2.2 `opt-in`: reword `optOut` step 3 and the Interactions entry so opt-out blocks event capture and `identify` still updates local identity and reloads flags

## 3. Validation

- [x] 3.1 Run `openspec validate --specs --strict` and resolve any errors
- [x] 3.2 Run `openspec archive` to sync the delta into `specs/identify/spec.md` and archive the change
Loading
Loading