[fadi-george]

Description

One Line Summary

Send direct_attribution_id on the session create when a notification open starts a new session.

Details

Motivation

Part of the iOS SDK Sessions stack (SDK-5400). The sessions API attributes a session to the notification that started it, but the open only reached the legacy influence manager. Android counterpart: OneSignal/OneSignal-Android-SDK#2783.

Scope

• OSNotificationsManager forwards opens from the background (the same !isActive path that feeds OSSessionManager) to OSSessionService.onNotificationOpened.
• Unlike Android, init's session start is dispatched to the main queue before iOS delivers a cold-start open, so the session usually starts first. Both orders are handled:
  • Open before the session starts (resume past the threshold): the ID is held and startNewSession returns it on OSSessionStart.directAttributionId, which goes on the create delta. A focus that continues the current session, or any unfocus, discards it, so an open during an active session never changes it or carries over.
  • Open after the session starts (cold start): if the current session started in this process, was never focused, and is within the 30 second threshold, the open is the one bringing it to the foreground. OSSessionUserProvider.sessionAttributed enqueues a new OS_ATTRIBUTE_SESSION_DELTA, which the executor folds into that session's queued create.
• The fold only applies while the create has never been prepared for sending. That state is persisted, so it holds across a kill. After a send attempt the attribution is dropped, since a retry replays the same idempotency_key and must send the same body.
• The attribute delta is exempt from identity verification like the other session deltas.
• Normal opens send no direct_attribution_id. Legacy outcome attribution is unchanged, and nothing is sent when the session doesn't use the sessions API.
• Opens delivered while the app is already active are not attributed, matching the legacy influence path.
• Only opens delivered while the app is inactive, which is how a tap that brings the app forward arrives, are attributed. A background action button (only possible with an app-defined category, since OneSignal's own buttons always use UNNotificationActionOptionForeground) runs with the app in the background and would otherwise credit a later normal open or a background-launch session. This mirrors Android's shouldInitDirectSessionFromNotificationOpen, which only forwards opens that launch the app. Legacy influence still gets every !isActive open.
• Opens are only attributed when direct influence is enabled in the remote params (OSInfluenceDataRepository.isDirectInfluenceEnabled, off by default), matching Android's influenceParams.isDirectEnabled check.

Testing

Unit testing

• OSSessionServiceTests: open before start attributes the new session; normal open omits it; open within the threshold leaves the session alone and doesn't attribute the next one; an open followed by unfocus isn't credited later; cold-start open after and before the session starts; open past the threshold of a background session, and for a session from an earlier process, attributes the next session.
• OSSessionOperationExecutorTests: attribution folded into a waiting create and in the same flush as the create; dropped after the create was sent and when there is no create; survives a kill; a sent create is not changed by an attribution replayed after a kill.
• SessionRecordUserTests: end-to-end for both orders, and no attribution on a normal start.
• The inactive-state and direct influence checks in OSNotificationsManager have no unit test: the test host is always active, and the legacy ObjC open tests are disabled, so reaching it would mean swizzling UIApplication.
• Full UnitTestApp_TestPlan_Reduced passes locally (302 tests, iOS 26.5 simulator).

Manual testing

Not tested on device yet; the cold-start ordering is from main-queue dispatch order, not device logs. End-to-end verification is planned in the iOS rollout and QA ticket.

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• Outcomes
• Sessions
• In-App Messaging
• REST API requests
• Public API changes

Checklist

Overview

• I have filled out all REQUIRED sections above
• PR does one thing
• Any Public API changes are explained in the PR details and conform to existing APIs

Testing

• I have included test coverage for these changes, or explained why they are not needed
• All automated tests pass, or I explained why that is not possible
• I have personally tested this on my device, or explained why that is not possible

Final pass

• Code is as readable as possible.
• I have reviewed this PR myself, ensuring it meets each checklist item

🤖 Generated with Claude Code

[cursor]

Multi-model review (Claude Opus 5.5, GPT 5.6, Grok 4.7)

The two-ordering design is coherent and the tests cover the main happy paths. One stated invariant does not hold across a process kill.

Act on

• OSRequestCreateSession.prepared is in-memory only. After a kill, a create that was already sent decodes as unprepared. An OS_ATTRIBUTE_SESSION_DELTA persisted immediately by OSOperationRepo.enqueueDelta can then change direct_attribution_id, and the retry rebuilds a different body with the same idempotency_key. All three reviewers flagged this. Persist the freeze. testAttributionAfterTheCreateWasSentIsDropped only covers an in-process 500.

Consider

• After the first flush (~5s) the create is frozen. A later open that still matches opensUnfocusedRecord (never-focused, <30s) is sent as a fold, dropped, and not held for the next session. A process already running in the background, then opened by a tap, loses attribution.
• startNewSession publishes the record before enqueue(start). A concurrent open can enqueue the attribute delta first; attribute(_:) drops it if the create is not in requestQueue yet.

Noted

• New required method on public OSSessionUserProvider (in-repo conformers updated).
• pendingAttributionId has no TTL; a background action that never focuses can credit a later session.
• Open and OSSessionStartGate sample the 30s window from different clocks.

  

_{Sent by Cursor Automation: PR Reviews}

[abdulraqeeb33]

The attribution fold and the prepared-body freeze look right. One nit on the pending id.

[abdulraqeeb33]

pendingAttributionId is cleared by onUnfocus, and by a focus that continues the current record. The tracker runs onUnfocus once per willResignActive, and didEnterBackground does not run it again. A custom action without UNNotificationActionOptionForeground can be delivered while the app is still Inactive, after that unfocus, and the next startNewSession past 30 seconds will send it. Stamp the time when the id is stored, and drop it when the gap is at least OSSessionStartGate.threshold.

[fadi-george]

Good catch. Fixed in 1998a74: the held open is stamped and dropped if the next session starts 30s or more after it.

That alone misses closing Notification Center between 30s after the unfocus and 30s after the action, so 1b48ff2 also only forwards opens that bring the app forward: a tap on the notification or one of its OneSignal buttons (always UNNotificationActionOptionForeground). Actions from app-defined categories are no longer attributed, which matches Android only attributing opens that launch the app.

[nan-li]

Can you test this on device with a direct session, but also influenced sessions?

[abdulraqeeb33]

The expiry and the forward-only open check look right. The new influence gate drops attribution while the flag is still missing.

[abdulraqeeb33]

isDirectInfluenceEnabled defaults to false and is only saved from outcomes.direct.enabled. The sessions create is already gated by the sessions cutover flag. An open before that save, and any open while the key is missing, never calls onNotificationOpened, so direct_attribution_id is omitted and not retried. Drop this check, or treat a missing key as enabled, and log the skip.