API Reference

Every public API in the Grovs iOS SDK 3.0. All properties and methods are static members of Grovs.

Threading and call order

• Completions and delegate callbacks are always called on the main thread.
• Everything can be called from any thread — the SDK moves the work to the main thread — except handleAppDelegate(continue:restorationHandler:), handleAppDelegate(open:options:), and reading delegate, which must happen on the main thread. UIKit already calls your app delegate there.
• Calls made before configure are ignored, with these exceptions: incoming links passed to handleSceneDelegate or handleAppDelegate are held and handled once configure runs, and setDebug and screenNameProvider take effect immediately. userIdentifier, userAttributes, pushToken, track, and trackScreenView log an error; setGlobalTags and setScreenAliases are dropped silently; methods with a completion call it with nil or false.

Properties

delegate

Grovs.delegate: GrovsDelegate?

Receives deep link payloads and SDK errors. Held weakly — keep a strong reference to the object elsewhere. Setting it before configure has no effect; pass the delegate to configure, or set it afterwards. Read it on the main thread.

userIdentifier

Grovs.userIdentifier: String?

Your identifier for the current user, typically your app's user_id. Shown in the Grovs dashboard and reports. Set it after configure. While the SDK is disabled, changes are held and sent when it is enabled again.

userAttributes

Grovs.userAttributes: [String: Any]?

Attributes describing the current user, shown in the dashboard. Values must be representable in JSON — strings, numbers, booleans, NSNull, or arrays and dictionaries of those. An assignment containing any other value is rejected and logged. Held while the SDK is disabled, like userIdentifier.

pushToken

Grovs.pushToken: String?

The APNs device token as a hex string, used to deliver push notifications for messages sent from the dashboard. See Messages. Held while the SDK is disabled.

screenNameProvider

Grovs.screenNameProvider: ((UIViewController) -> GrovsScreenName)?

Optional resolver consulted before the SDK's built-in name resolution for automatically tracked screens. Called on the main thread. See Events & Screen Tracking.

Configuration

configure

Grovs.configure(
    APIKey: String,
    useTestEnvironment: Bool,
    baseURL: String? = nil,
    autoTrackScreenViews: Bool = true,
    clipboardDomains: [String]? = nil,
    enabled: Bool = true,
    delegate: GrovsDelegate?,
    completion: GrovsBoolCompletion? = nil
)

Configures and authenticates the SDK. Call once per launch, in application(_:didFinishLaunchingWithOptions:). Calling it again replaces the previous configuration.

setSDK

Grovs.setSDK(enabled: Bool)

Turns collection on or off at runtime, for example when the user gives or withdraws consent. While disabled, the SDK does not authenticate, resolve the device, or send events, screen views, or purchases, and holds userIdentifier, userAttributes, pushToken, and screen alias updates. Events and purchases already on disk stay there. Enabling authenticates if needed and sends everything that was held. See Privacy & Consent.

setDebug

Grovs.setDebug(level: LogLevel)

Sets the minimum level of SDK log output. Default is .error. Logs go through os_log; in release builds, message content is marked private and appears as <private> in Console.app.

Deep links

handleSceneDelegate (openURLContexts)

Grovs.handleSceneDelegate(openURLContexts URLContexts: Set<UIOpenURLContext>)

Forward from scene(_:openURLContexts:).

handleSceneDelegate (continue)

Grovs.handleSceneDelegate(continue userActivity: NSUserActivity)

Forward from scene(_:continue:).

handleSceneDelegate (options)

Grovs.handleSceneDelegate(options connectionOptions: UIScene.ConnectionOptions)

Forward from scene(_:willConnectTo:options:). Handles a link that launched the app from a cold start.

handleAppDelegate (continue)

Grovs.handleAppDelegate(
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool

Forward from application(_:continue:restorationHandler:) and return its result. Main thread only.

handleAppDelegate (open)

Grovs.handleAppDelegate(
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool

Forward from application(_:open:options:) and return its result. Main thread only.

lastReceivedPayload

Grovs.lastReceivedPayload(completion: @escaping GrovsPayloadClosure)

The most recent deep link payload, or nil.

allReceivedPayloadsSinceStartup

Grovs.allReceivedPayloadsSinceStartup(completion: @escaping GrovsPayloadsClosure)

Every payload received since the app launched, or nil.

Links

generateLink

Grovs.generateLink(
    title: String? = nil,
    subtitle: String? = nil,
    imageURL: String? = nil,
    data: [String: Any]? = nil,
    tags: [String]? = nil,
    customRedirects: CustomRedirects? = nil,
    showPreviewiOS: Bool? = nil,
    showPreviewAndroid: Bool? = nil,
    copyToClipboardiOS: Bool? = nil,
    copyToClipboardAndroid: Bool? = nil,
    trackingCampaign: String? = nil,
    trackingSource: String? = nil,
    trackingMedium: String? = nil,
    completion: @escaping GrovsURLClosure
)

Creates a smart link. The completion receives the URL, or nil on failure. See Link Creation for every parameter.

linkDetails

Grovs.linkDetails(path: String, completion: @escaping GrovsLinkClosure)

Details for a link previously generated in the current environment, identified by its path. nil if the request fails.

Messages

displayMessagesViewController

Grovs.displayMessagesViewController(completion: GrovsEmptyClosure?)
Grovs.displayMessagesViewController(completion: GrovsEmptyClosure?, onFailure: GrovsEmptyClosure?)

Presents the message list modally. completion runs when it is dismissed. onFailure runs if it could not be shown — the SDK is not configured, authentication failed, or there was no view controller to present from. The single-argument form calls completion in both cases.

numberOfUnreadMessages

Grovs.numberOfUnreadMessages(completion: @escaping GrovsIntClosure)

The number of unread messages, or nil if the request fails.

Revenue

logInAppPurchase

Grovs.logInAppPurchase(transactionID: UInt64, completion: @escaping GrovsBoolCompletion)

Logs an App Store purchase by its StoreKit 2 transaction ID. Only the ID is sent; product, price, and currency are resolved on the backend through the App Store Server API. A transaction ID already logged on this device is skipped. Obtaining the ID needs StoreKit 2 (iOS 15) in your own code. See Revenue.

logCustomPurchase

Grovs.logCustomPurchase(
    type: TransactionType,
    priceInCents: Int,
    currency: String,
    productID: String,
    startDate: Date? = nil,
    completion: @escaping GrovsBoolCompletion
)

Logs a purchase, cancellation, or refund made outside Apple's In-App Purchase system. currency is an ISO 4217 code; startDate defaults to now.

Events

track

Grovs.track(_ name: String, properties: [String: Any]? = nil, tags: [String]? = nil)

Tracks a custom event. The name must be non-empty and not a reserved system event name. See Events & Screen Tracking for property rules and limits.

trackScreenView

Grovs.trackScreenView(_ screenName: String, properties: [String: Any]? = nil)

Tracks a screen view. screen_name is added to the properties. A repeat of the same name within one second is dropped.

setGlobalTags

Grovs.setGlobalTags(_ tags: [String]?)

Tags attached to every later event, or nil to clear them.

setScreenAliases

Grovs.setScreenAliases(_ aliases: [String: String])

Maps view controller class names to friendly dashboard names, e.g. ["CheckoutViewController": "Checkout Page"].

Types

GrovsDelegate

public protocol GrovsDelegate: AnyObject {
    func grovsReceivedPayloadFromDeeplink(link: String?, payload: [String: Any]?, tracking: [String: Any]?)
    func grovsDidEncounterError(_ error: GrovsError, message: String)  // optional
}

Both methods are called on the main thread. grovsDidEncounterError has a default empty implementation.

GrovsError

public enum GrovsError: Int, CustomStringConvertible {
    case authenticationFailed = 1
    case networkRequestFailed = 2
    case eventDispatchFailed = 3
    case linkGenerationFailed = 4
}

Failure categories reported through grovsDidEncounterError. description is the snake-case name, e.g. "authentication_failed". See Handling SDK errors.

GrovsScreenTracking

public protocol GrovsScreenTracking {
    var grovsScreenName: String? { get }
}

Adopt on a UIViewController to name it for automatic screen tracking. Return nil to skip it.

GrovsScreenName

public enum GrovsScreenName {
    case automatic
    case suppress
    case name(String)
}

Returned from screenNameProvider: .automatic falls through to the SDK's resolution, .suppress skips the controller, .name(_:) overrides the name.

LogLevel

public enum LogLevel: Int, Comparable {
    case info = 0
    case warn = 1
    case error = 2
}

TransactionType

public enum TransactionType: String, Codable {
    case buy
    case cancel
    case refund
}

Used with logCustomPurchase.

CustomRedirects

public struct CustomRedirects: Codable {
    public var ios: CustomLinkRedirect?
    public var android: CustomLinkRedirect?
    public var desktop: CustomLinkRedirect?
 
    public init(ios: CustomLinkRedirect? = nil, android: CustomLinkRedirect? = nil, desktop: CustomLinkRedirect? = nil)
}

Per-platform redirect overrides for generateLink.

CustomLinkRedirect

public struct CustomLinkRedirect: Codable {
    public let link: String
    public var openAppIfInstalled: Bool
 
    public init(link: String, openAppIfInstalled: Bool = true)
}

When openAppIfInstalled is true, the app opens if installed; otherwise link is always used.

Closure types

SwiftUI

grovsScreen

func grovsScreen(_ screenName: String, properties: [String: Any]? = nil) -> some View
func grovsScreen(properties: [String: Any]? = nil, fileID: String = #fileID) -> some View

Tracks a screen view when the view appears, and suppresses automatic tracking for the enclosing hosting controller so the screen is not counted twice. The unnamed form derives the name from the file name — CheckoutView.swift becomes "Checkout".

trackScreenView (modifier)

func trackScreenView(_ screenName: String, properties: [String: Any]? = nil) -> some View

Same as grovsScreen(_:properties:).