Changelog

All notable changes to the Grovs iOS SDK are documented here. The format follows Keep a Changelog, and the SDK follows semantic versioning.

Releases before 3.0.0 predate this file; see the git history for them.

3.1.0 is a minor release, but check these when upgrading:

• GrovsError has a new case, inAppDisplayFailed (5): an exhaustive switch over it no longer compiles until the case is handled.
• GrovsDelegate is now an @objc protocol with @objc optional methods, and the Swift default implementation of grovsDidEncounterError is gone. A method whose signature no longer matches compiles with only a "nearly matches" warning and is never called; check those warnings.
• The messages inbox is removed: displayMessagesViewController(...) and numberOfUnreadMessages(...) are deprecated no-ops.
• A push carrying only grovs_notification_id is no longer a Grovs push: isGrovsNotification(userInfo:) and the notification handlers return false for it.
• Automatic screen tracking now tracks a view controller class named exactly ViewController (or Controller) under that name; before, its name was cleaned to nothing and it was never tracked.
• More event names are reserved and refused by track(_:), as the backend refuses them: push_open, push_delivered, push_held, in_app_held, journey_entered, journey_held and journey_path, besides the in-app names below.
• Call handleNotificationOpen(userInfo:) only for a tap on a notification, never from didReceiveRemoteNotification or willPresent, or each delivery counts as an open.

• In-app messages: campaigns made in the dashboard are synced to the device, decided there and shown in a window above the app. Grovs.inApp pauses, resumes, discards and excludes screens, and reports shown, clicked and dismissed messages to the host.
• In-app questions: a message can ask for a star rating (1 to 5) or one choice from a list. One tap answers; a comment box (up to 500 characters, Send or Skip) and a thanks text may follow, and a star rating high enough can be followed by the system's review prompt. An answered campaign is not shown again on the device. GrovsInAppDelegate.grovsDidAnswerInAppMessage(campaignID:value:comment:) is called in place of the dismissal; like every GrovsInAppDelegate method it is optional. The event names in_app_answered and in_app_commented are reserved and cannot be tracked by the host app.
• In-app test messages: a message sent with "Send test" in the dashboard shows at the next sync, once the screen is free and messages are not paused. It is not counted or reported.
• GrovsError.inAppDisplayFailed (5): a message could not be drawn. An exhaustive switch over GrovsError needs the new case.
• Push campaigns: Grovs.handleNotificationResponse(_:) / handleNotificationOpen(userInfo:) report opens (POST /sdk/push_open) and deliver the push through the deep-link delegate: its data (userInfo without aps), merged over its link's payload when it has a link. Only a tap on the notification counts, not a dismissal or a custom action. Taps before configure or before authentication succeeds are held (a tap held before configure(enabled: false) is dropped), and an open that fails to report is retried on the next foreground, up to 3 attempts. Grovs.isGrovsNotification(userInfo:), Grovs.setPushToken(deviceToken:). A push token set before configure is held until then.
• GrovsNotificationService product (SPM and pod) for Notification Service Extensions: attaches grovs_image (JPEG, PNG or GIF; other formats are skipped), and can add it to content other code has already changed. The download is cancelled when the extension's time runs out.

• The messages inbox screens and the automatic display of dashboard messages. The SDK no longer calls the inbox endpoints, ships no XIB, and no longer treats a push carrying only grovs_notification_id as a Grovs push. Use in-app messages instead.

• Grovs.displayMessagesViewController(completion:) and displayMessagesViewController(completion:onFailure:) show nothing: they call completion once on the main thread and never call onFailure.
• Grovs.numberOfUnreadMessages(completion:) always yields 0, on the main thread.

• In-app: a message keeps the status bar hidden when the app hides it; the app's window gets the keyboard back after a comment; on iPad the scene holding the key window is used and the orientation follows the window's shape; a return to the app syncs at most once a minute (a campaign change still syncs at once); a message still waiting when the session ends is dropped; what waits is shown after a link, the store, a rating or push permission prompt when the app is still in front; the state is written at most twice a second and on going to the background.
• GrovsNotificationServiceExtension delivers each push to its own handler when the system reuses one extension instance for several pushes.
• The privacy manifest declares the file timestamp reason (C617.1) for the SDK's disk cache.
• A push token set before authentication no longer clears the user's identifier and attributes on the server: the server's values are kept for fields the app hasn't set.

• A tap on a push that carries a Grovs link counts once, as push_open: the link is resolved with source: push, so it no longer counts as a link open, and later events are not attributed to the link.
• Grovs.podspec compiles only Sources/Grovs; the extension code ships in its own pod.
• scripts/run_tests.sh runs the Grovs-Package scheme (a second library product moves the tests out of the Grovs scheme).
• GrovsDelegate and GrovsInAppDelegate are @objc protocols with @objc optional methods, so Objective-C apps can adopt them; GrovsError is an @objc enum and Grovs an NSObject. Source-compatible for most apps, but the Swift default implementations are gone: a method whose signature no longer matches compiles with only a "nearly matches" warning and is never called. Check those warnings when upgrading.
• grovsDidDismissInAppMessage(campaignID:reason:) can report orientation: the device turned to an orientation the campaign does not allow. It is not counted as a dismissal in the dashboard.
• In-app HTML: grovs.open() (and a link) opens only within 2 seconds of a tap in the message; later, for example after a slow network call, it is ignored.

Supersedes 2.4, which was bumped in the podspec but never tagged or published.

• Custom event tracking: Grovs.track(_:properties:tags:), Grovs.setGlobalTags(_:), and batched dispatch with retry.
• Screen view tracking: automatic UIKit tracking, Grovs.trackScreenView(_:properties:), the GrovsScreenTracking protocol, Grovs.setScreenAliases(_:), Grovs.screenNameProvider, and the SwiftUI View.grovsScreen() modifier.
• Purchase tracking: Grovs.logInAppPurchase(transactionID:completion:) and Grovs.logCustomPurchase(type:priceInCents:currency:productID:startDate:completion:).
• Clipboard-assisted deferred deep link matching, gated on a gd parameter and a domain allowlist (clipboardDomains: on configure), plus a copyToClipboardiOS link flag.
• Error reporting to the host app through the optional GrovsDelegate.grovsDidEncounterError(_:message:).
• PrivacyInfo.xcprivacy privacy manifest, shipped for SPM, CocoaPods, and the xcframework.
• A hosted test harness (scripts/run_hosted_tests.sh) so the keychain tests assert instead of skipping, and CI running tests, Thread Sanitizer, hosted keychain tests, and a version-drift gate.

• Logging goes through os_log and is redacted in release builds; Grovs.setDebug(level:) now takes the public LogLevel.
• The device payload and purchase events carry session_id.
• The raw device identifier is sent instead of a mapped model name.
• vendor_id is omitted while identifierForVendor is unavailable (before first unlock after a reboot) instead of sending a shared "unknown" that the backend would match as one device.
• The privacy manifest declares collected data as linked to the user, since the host's userIdentifier is stored against the same device record.
• Custom purchases carry a client-minted transaction_id, so a retry of a request the backend already committed is deduplicated instead of counted twice.
• A user agent fetched on an earlier launch is reused until the OS version changes, so WebKit is no longer spun up on every cold launch.
• CocoaPods ships the XIBs inside the Grovs resource bundle rather than loose in the host app, where a nib with the same name would collide.
• Cached event archives require secure coding.
• Requests are never sent without a parseable User-Agent.
• The SDK version has a single source of truth (GrovsVersion.current), checked against the podspec and MARKETING_VERSION in CI.
• Internal types that were unnecessarily public are internal again; the supported surface is Grovs, GrovsDelegate, GrovsError, GrovsScreenTracking, GrovsScreenName, LogLevel, TransactionType, CustomLinkRedirect/CustomRedirects, and View.grovsScreen().

• Disabling the SDK now stops all collection — including identifier, attribute, and push token updates, and lifecycle events already read from storage when consent is withdrawn — and payloads without a link are still delivered.
• Purchases persisted by an earlier launch are retried as soon as the SDK authenticates, instead of waiting for the next foreground.
• A superseded screen-alias response no longer discards newer aliases that are still pending.
• The message view stops its spinner when a page fails before the navigation commits (offline, DNS, TLS).
• Auto-displayed messages are no longer suppressed after a failed presentation, nor shown twice by overlapping display chains.
• Messages list pagination: a page superseded by a refresh is discarded, an older refresh can't overwrite a newer one, and a failed page is retried rather than skipped.
• Duplicate device resolves no longer cancel in-flight requests or release held events early.
• Keychain writes survive protection-class changes, and the SDK self-heals when the backend rejects the device identifier.
• Retain cycles, identity-recovery ordering, observer cleanup, and several data races (the suite runs clean under Thread Sanitizer).
• The AutoScreenTracker swizzle composes with other viewDidAppear swizzlers, and no longer replaces a completion block the host set on its own CATransaction.
• An unparseable baseURL refuses configuration and reports false instead of trapping.
• Retry-After is capped at 60 seconds.
• The clipboard flow reads the pasteboard once, so a denied paste alert isn't shown twice.

• Message content can only open http, https, mailto, tel, and sms links externally; every other scheme is ignored.