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
1 change: 1 addition & 0 deletions .changeset/v4-major-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ PostHog iOS 4.0: see the [migration guide](https://github.com/PostHog/posthog-io
- **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` passed in the same call's properties
- **Breaking:** rename `maxRetries` to `pushNotificationSubscriptionMaxRetries`
- **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, and drop a value that isn't a string
- **Breaking:** omit event properties whose value is `NSNull`, including in nested dictionaries and dictionaries inside arrays, instead of sending them as `null` — `null` array elements and `$set`, `$set_once` and `$group_set` values are still sent
- **Breaking:** let PostHog drop an event whose name is over 200 UTF-8 bytes, or whose distinct ID is empty or whitespace-only, instead of rejecting the whole batch
- **Breaking:** retry a capture request that gets a 404 and keep its events queued, with no fallback to `/batch`, and stop retrying 3xx responses
- **Breaking:** with `debug` on, log capture failures as one line per batch with counts and PostHog's drop reasons, and stop logging each queued event and PostHog's response body — update log-based alerts
Expand Down
4 changes: 4 additions & 0 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,10 @@ Update cohorts, insights and actions that match `$locale`: a filter on `$locale

Feature flags aren't affected: the SDK doesn't send `$locale` or `$app_language` with flag requests, so flags only see these if you set them as person properties yourself.

### Null event properties

An event property set to `NSNull()` is now left out of the event instead of being sent as `null`, also inside nested dictionaries and dictionaries in arrays, and also when `beforeSend` sets it. An array keeps a `null` element at its position, and a dictionary left empty is sent as `{}`. `false`, `0`, `""` and empty arrays are sent as before. You can still pass `NSNull()`. To clear a person or group property, `$set`, `$set_once` and `$group_set` still send `null` values. A `$feature_flag_called` event for a flag with no value now has no `$feature_flag_response` instead of `null`.

### Network reachability

4.0 detects connectivity with `NWPathMonitor`:
Expand Down
6 changes: 4 additions & 2 deletions PostHog/Models/PostHogEvent.swift
Original file line number Diff line number Diff line change
Expand Up @@ -125,11 +125,13 @@ import Foundation
)
}

func toJSON() -> [String: Any] {
/// - Parameter dropNulls: Removes null-valued property members, for the analytics and AI
/// queues. Replay snapshots keep their properties as built.
func toJSON(droppingNullProperties dropNulls: Bool = false) -> [String: Any] {
var json: [String: Any] = [
"event": event,
"distinct_id": distinctId,
"properties": properties,
"properties": dropNulls ? droppingNullProperties(properties) : properties,
"timestamp": toISO8601String(timestamp),
"uuid": uuid.postHogUuidString,
]
Expand Down
3 changes: 2 additions & 1 deletion PostHog/PostHogApi.swift
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,8 @@ class PostHogApi {
json["window_id"] = windowId
}
json["options"] = options
json["properties"] = properties
// Also covers events queued before null properties were dropped at encode time.
json["properties"] = droppingNullProperties(properties)
return json
}

Expand Down
4 changes: 2 additions & 2 deletions PostHog/QueueEndpoint+Factories.swift
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ extension QueueEndpoint where Record == PostHogEvent {
flushIntervalSeconds: { $0.flushIntervalSeconds },
rateCapMax: { _ in 0 },
rateCapWindowSeconds: { _ in 0 },
encode: { event in toJSONData(event.toJSON()) },
encode: { event in toJSONData(event.toJSON(droppingNullProperties: true)) },
decode: { data in PostHogEvent.fromJSON(data) },
describe: { event in "event '\(event.event)'" },
recordId: { event in event.uuid.postHogUuidString },
Expand Down Expand Up @@ -76,7 +76,7 @@ extension QueueEndpoint where Record == PostHogEvent {
flushIntervalSeconds: { $0.flushIntervalSeconds },
rateCapMax: { _ in 0 },
rateCapWindowSeconds: { _ in 0 },
encode: { event in toJSONData(event.toJSON()) },
encode: { event in toJSONData(event.toJSON(droppingNullProperties: true)) },
decode: { data in PostHogEvent.fromJSON(data) },
describe: { event in "AI event '\(event.event)'" },
recordId: { event in event.uuid.postHogUuidString },
Expand Down
66 changes: 66 additions & 0 deletions PostHog/Utils/DictUtils.swift
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,72 @@ private func sanitizeArray(_ array: [Any]) -> [Any] {
return sanitized
}

/// Person and group property updates keep their null values: `$set: ["plan": NSNull()]` is how a
/// caller clears a person property, so these values are sent as given.
private let nullPreservingPropertyKeys: Set<String> = ["$set", "$set_once", "$group_set"]

/// Removes null-valued object members from event properties before they are written to the queue
/// or sent, as the sdk-specs capture requirement "Capture drops null-valued object properties" asks.
///
/// Recurses into nested dictionaries, including dictionaries inside arrays. Null array elements are
/// kept at their index, and a dictionary emptied by the cleanup stays `{}`. Other values (`false`,
/// `0`, `""`, `"null"`, empty containers) are unchanged. `$set`, `$set_once` and `$group_set` are
/// left as given.
///
/// - Parameter properties: Event properties, after `beforeSend`.
/// - Returns: The properties without null-valued object members.
func droppingNullProperties(_ properties: [String: Any]) -> [String: Any] {
var result = properties
for (key, value) in properties where !nullPreservingPropertyKeys.contains(key) {
if let cleaned = droppingNulls(in: value) {
result[key] = cleaned
} else if isNullValue(value) {
result.removeValue(forKey: key)
}
}
return result
}

/// Returns `value` with null object members removed, or `nil` when it is not a container or has
/// nothing to remove, so unchanged containers are not copied.
private func droppingNulls(in value: Any) -> Any? {
if let dict = value as? [String: Any] {
Comment thread
turnipdabeets marked this conversation as resolved.
Resolved
return droppingNulls(inDictionary: dict)
}
// Number or boolean keys are stringified later by `sanitizeDictionary`, so clean these too.
if let dict = value as? [AnyHashable: Any] {
return droppingNulls(inDictionary: dict)
}
if let array = value as? [Any] {
var result = array
var changed = false
for (index, element) in array.enumerated() {
// Null elements stay at their index; only objects inside the array are cleaned.
if let cleaned = droppingNulls(in: element) {
result[index] = cleaned
changed = true
}
}
return changed ? result : nil
}
return nil
}

private func droppingNulls<Key: Hashable>(inDictionary dict: [Key: Any]) -> [Key: Any]? {
var result = dict
var changed = false
for (key, member) in dict {
if let cleaned = droppingNulls(in: member) {
result[key] = cleaned
changed = true
} else if isNullValue(member) {
result.removeValue(forKey: key)
changed = true
}
}
return changed ? result : nil
}

/// Whether a value is missing or serializes as JSON `null`: `nil`, `NSNull`, or a `nil` optional boxed in `Any`.
func isNullValue(_ value: Any?) -> Bool {
guard let value else { return true }
Expand Down
167 changes: 167 additions & 0 deletions PostHogTests/PostHogCaptureV1Test.swift
Original file line number Diff line number Diff line change
Expand Up @@ -1386,3 +1386,170 @@ final class PostHogCaptureAiTest {
#expect(server.aiRequests.map { server.parsePostHogEvents($0).count } == [1, 1])
}
}

/// sdk-specs capture "Capture drops null-valued object properties" and capture-ai "AI capture drops null-valued object properties".
@Suite("Capture V1 null properties", .serialized, .resetsGlobalState)
final class PostHogCaptureNullPropertiesTest {
private let server: MockPostHogServer

/// The spec scenario's input, `{"test":null,"nested":{"drop":null},"items":["1",null,2,{"drop":null},[null]],...}`.
private static let nullableProperties: [String: Any] = [
"test": NSNull(),
"nested": ["drop": NSNull()] as [String: Any],
"items": ["1", NSNull(), 2, ["drop": NSNull()] as [String: Any], [NSNull()]] as [Any],
"empty": "",
"zero": 0,
"enabled": false,
"literal": "null",
"emptyArray": [] as [Any],
]

/// The spec scenario's expected output.
private static let cleanedProperties: NSDictionary = [
"nested": [String: Any](),
"items": ["1", NSNull(), 2, [String: Any](), [NSNull()]] as [Any],
"empty": "",
"zero": 0,
"enabled": false,
"literal": "null",
"emptyArray": [] as [Any],
]

init() {
deleteSafely(applicationSupportDirectoryURL())
server = MockPostHogServer()
server.start(batchCount: 0)
}

deinit {
server.stop()
}

private func makeSDK(beforeSend: BeforeSendBlock? = nil) -> PostHogSDK {
let config = PostHogConfig(projectToken: "phc_null_\(UUID().uuidString)", host: "http://localhost:9001")
config.flushAt = 1
config.preloadFeatureFlags = false
config.sendFeatureFlagEvent = false
config.disableReachabilityForTesting = true
config.disableQueueTimerForTesting = true
config.disableFlushOnBackgroundForTesting = true
config.captureApplicationLifecycleEvents = false
if let beforeSend {
config.setBeforeSend(beforeSend)
}
server.batchProjectToken = config.projectToken
return PostHogSDK.with(config)
}

/// The wire properties of the first event in `request`.
private func sentProperties(_ request: URLRequest) throws -> [String: Any] {
let body = try #require(server.parseRequest(request))
let event = try #require((body["batch"] as? [[String: Any]])?.first)
return try #require(event["properties"] as? [String: Any])
}

/// The spec payload's keys of `properties`, leaving out SDK properties.
private func custom(_ properties: [String: Any]) -> NSDictionary {
NSDictionary(dictionary: properties.filter { Self.nullableProperties[$0.key] != nil })
}

@Test("capture omits null-valued properties, keeps null array elements and emptied objects, and leaves falsy values")
func captureDropsNullProperties() async throws {
let sut = makeSDK()
defer { sut.close() }

sut.capture("Nullable Properties", properties: Self.nullableProperties)
await waitUntil { self.server.batchRequests.count == 1 }

let properties = try sentProperties(try #require(server.batchRequests.first))
#expect(properties.keys.contains("test") == false)
#expect(custom(properties) == Self.cleanedProperties)
#expect(properties["$lib"] as? String == postHogSdkName)
}

@Test("captureAi omits null-valued properties on the AI endpoint")
func captureAiDropsNullProperties() async throws {
let sut = makeSDK()
defer { sut.close() }

let uuid = sut.captureAi("$ai_generation", distinctId: "user", properties: Self.nullableProperties)
#expect(uuid != nil)
await waitUntil { self.server.aiRequests.count == 1 }

let properties = try sentProperties(try #require(server.aiRequests.first))
#expect(properties.keys.contains("test") == false)
#expect(custom(properties) == Self.cleanedProperties)
}

@Test("null-valued properties added by beforeSend are omitted")
func beforeSendNullsAreOmitted() async throws {
let sut = makeSDK { event in
event.properties["hookNull"] = NSNull()
event.properties["hookItems"] = [NSNull(), ["drop": NSNull()] as [String: Any]] as [Any]
return event
}
defer { sut.close() }

sut.capture("Hook Properties")
await waitUntil { self.server.batchRequests.count == 1 }

let properties = try sentProperties(try #require(server.batchRequests.first))
#expect(properties.keys.contains("hookNull") == false)
#expect(properties["hookItems"] as? NSArray == [NSNull(), [String: Any]()] as NSArray)
}

@Test("the analytics and AI queues write events to disk without null-valued properties")
func queuesWriteWithoutNullProperties() throws {
let api = PostHogApi(PostHogConfig(projectToken: "phc_null", host: "http://localhost:9001"))
let event = PostHogEvent(event: "Persisted Properties", distinctId: "user", properties: Self.nullableProperties)

for endpoint in [QueueEndpoint<PostHogEvent>.batch(api: api), .ai(api: api)] {
let data = try #require(endpoint.encode(event))
let stored = try #require(fromJSONData(data)?["properties"] as? [String: Any])
#expect(stored.keys.contains("test") == false)
#expect(custom(stored) == Self.cleanedProperties)
}
}

@Test("a dictionary with non-string keys is written without its null-valued members")
func nonStringKeyedDictionaryDropsNulls() throws {
let api = PostHogApi(PostHogConfig(projectToken: "phc_null", host: "http://localhost:9001"))
let numberKeyed: [Int: Any] = [1: NSNull(), 2: "kept"]
let event = PostHogEvent(event: "Number Keys", distinctId: "user", properties: ["numberKeyed": numberKeyed])

let data = try #require(QueueEndpoint<PostHogEvent>.batch(api: api).encode(event))
let stored = try #require(fromJSONData(data)?["properties"] as? [String: Any])
#expect(stored["numberKeyed"] as? [String: String] == ["2": "kept"])
}

@Test("an event queued with null-valued properties, as older versions stored it, is sent without them")
func storedNullPropertiesAreDroppedOnSend() async throws {
let api = PostHogApi(PostHogConfig(projectToken: "phc_null", host: "http://localhost:9001"))
let event = PostHogEvent(event: "Persisted Properties", distinctId: "user", properties: Self.nullableProperties)

_ = await withCheckedContinuation { continuation in
api.captureV1(events: [event]) { continuation.resume(returning: $0) }
}

let properties = try sentProperties(try #require(server.batchRequests.first))
#expect(properties.keys.contains("test") == false)
#expect(custom(properties) == Self.cleanedProperties)
}

@Test("null person and group property values in $set, $set_once and $group_set are sent as given")
func personAndGroupNullsAreKept() async throws {
let sut = makeSDK()
defer { sut.close() }

sut.capture("event", userProperties: ["plan": NSNull()], userPropertiesSetOnce: ["first_plan": NSNull()])
await waitUntil { self.server.batchRequests.count == 1 }
sut.group(type: "company", key: "acme", groupProperties: ["tier": NSNull()])
await waitUntil { self.server.batchRequests.count == 2 }

let properties = try sentProperties(server.batchRequests[0])
#expect((properties["$set"] as? [String: Any])?["plan"] is NSNull)
#expect((properties["$set_once"] as? [String: Any])?["first_plan"] is NSNull)
let groupProperties = try sentProperties(server.batchRequests[1])
#expect((groupProperties["$group_set"] as? [String: Any])?["tier"] is NSNull)
}
}
2 changes: 1 addition & 1 deletion PostHogTests/PostHogSDKTest.swift
Original file line number Diff line number Diff line change
Expand Up @@ -890,7 +890,7 @@ final class PostHogSDKTests {
#expect(events.count == 1)
#expect(event.event == "$feature_flag_called")
#expect(event.properties["$feature_flag"] as? String == "missing")
#expect(event.properties["$feature_flag_response"] is NSNull)
#expect(event.properties.keys.contains("$feature_flag_response") == false)

sut.reset()
sut.close()
Expand Down
Loading