Repository navigation
Releases
Releases · Countly/countly-sdk-swift
26.8.0
- Initial release of the Countly Swift SDK.
- Added multi-instance entrypoints on "Countly":
- "Countly.shared", the default instance, which reads and writes the storage a previous "countly-sdk-ios" integration left behind
- "Countly.instance(named:)", which creates the instance if needed. Getting a handle never starts it; the caller always calls "start(with:)". An empty name is refused instead of falling back to the default instance.
- "Countly.getInstance(named:)" / "Countly.listInstances()" / "Countly.haltAllInstances(clearStorage:)"
- "Countly.removeInstance(named:)", which stops a named instance and drops it from the registry, keeping its stored data. A handle kept to the removed instance can no longer be started.
- Each instance owns its app key, server, request queue, device ID, logger, clock and storage namespace. Named instances get their own files and user defaults keys; the default instance keeps the legacy ones.
- Added instance lifecycle on "CountlyInstance":
- "start(with:)" / "isStarted". "start(with:)" takes a copy of the config, so one object can start several instances, or the same instance again after a halt.
- "start(with:)" refuses a server URL that is not an absolute "http" or "https" URL, and an "http" URL while certificates are pinned.
- "suspend()" / "resume()"
- "halt(clearStorage:)", which tears the instance down and, when asked, wipes every persisted key including those "countly-sdk-ios" wrote, whether the instance is running or not. The instance stays registered and can be started again.
- Integration-wide operations: "setNewHost", "setNewAppKey", "setNewURLSessionConfiguration", "addCustomNetworkRequestHeaders", "recordMetrics", "addDirectRequest"
- "setNewHost" ignores, with an error, a URL that is not an absolute "http" or "https" URL, and an "http" URL while certificates are pinned. "setNewAppKey" ignores, with an error, an empty or placeholder key, and ignores the key in use.
- "setNewAppKey" first closes what belongs to the old app under the old key: the running views stop, pending events and profile changes are queued and the running session ends. A session then begins for the new app if one was running.
- After "setNewHost" or "setNewAppKey" the new server or app is caught up: the push token and, while consent is required, the consent state are sent again, and its behavior settings and remote config are fetched. "setNewAppKey" also clears the old app's remote config values.
- "addDirectRequest" encodes every key and value itself, so they are passed as they are, and drops the keys the SDK sets itself, such as "device_id", "av", "rr" and "dr". A request left without parameters is ignored with a warning.
- Added the events API on "countly.events":
- "recordEvent(key, segmentation, count, sum, duration)"
- "CountlyConfig.eventSendThreshold", the number of recorded events that triggers a batch, 100 by default
- "startEvent(key)" / "endEvent(key, segmentation, count, sum)" / "cancelEvent(key)"
- "recordedEvents()", the events buffered and not yet moved into the request queue
- "recordReservedEvent(key, ...)", which records a reserved event the SDK normally produces itself. An overload takes a "CountlyReservedEvent" instead of a key.
- Recorded events are kept in storage until they are moved into a request, so they survive the application being closed or killed. At most 1000 are kept.
- Feedback widget answers and push actions are sent right away rather than with the next batch.
- A count below one is recorded as 1, and a sum or duration that is not a finite number, or a negative duration, as 0, with a warning.
- Added the views API on "countly.views":
- "startView(name, segmentation)" / "startAutoStoppedView(name, segmentation)"
- "stopView(name:segmentation:)" / "stopView(id:segmentation:)" / "stopAllViews(segmentation:)". Of several open views with one name, the last one started is the one stopped or segmented by name.
- "pauseView(id:)" reports the time so far and stops counting; "resumeView(id:)" counts again without a new start. Stopping a paused view reports no further time. A second pause, or a resume of a view that is not paused, is ignored with a warning.
- "addSegmentation(toViewWithID:segmentation:)" / "addSegmentation(toViewWithName:segmentation:)"
- "setGlobalViewSegmentation(segmentation)" / "updateGlobalViewSegmentation(segmentation)", and "CountlyConfig.globalViewSegmentation" at init
- "addAutoViewTrackingExclusionList(names)"
- Every running view stops when the application goes to the background and starts again as a new visit when it returns. A view ID stays valid across that. "disableViewRestartForManualRecording" keeps the manual views from starting again; they still stop.
- After a device ID change without merge or an app key change, no manual view starts again, and the view IDs held for the stopped views no longer work. Automatic view tracking starts a view for the screen on display.
- Added the sessions API on "countly.sessions":
- "beginSession()" / "updateSession()" / "endSession()"
- Manual session control and manual hybrid mode via "CountlyConfig.manualSessionHandling" and "enableManualSessionControlHybridMode"
- "CountlyConfig.updateSessionPeriod", the interval of session updates and event batches, 60 seconds by default and 20 seconds on watchOS
- Session durations come from a monotonic clock, so changing the device's date and time cannot stretch or shrink a session.
- A session that is running when the server turns session tracking off still ends normally.
- On macOS the automatic session ends when the application hides or quits, and the next activation begins a new one.
- On watchOS the session follows the extension's active state on its own, so the host does not call "suspend()" and "resume()" from its extension delegate.
- Added the user profile API on "countly.userProfile":
- "setProperty(key, value)" / "setProperties(data)"
- "setCustomProperty(key, value)" / "unsetCustomProperty(key)"
- "setOnce(key, value)" / "increment(key)" / "incrementBy(key, value)" / "multiply(key, value)"
- "max(key, value)" / "min(key, value)"
- "push(key, value)" / "pushUnique(key, value)" / "pull(key, value)"
- "save()" / "clear()"
- "CountlyConfig.providedUserProperties", applied before the first request leaves the device
- Predefined properties: name, username, email, organization, phone, picture, picturePath, gender, byear. "byear" takes a whole number only.
- An empty string clears a property on the server. A null value is ignored with a warning.
- The same modifier called again on a key is combined before the save: increments add up, multiplications multiply, the highest or lowest value is kept, the first "setOnce" value is kept and list values are collected.
- A different change for a key that has one pending, another modifier or a value, saves the pending changes first, so both reach the server in call order.
- The calls need the "users" consent; without it they are ignored, and a save discards what is pending.
- The server's user property cache limit ("upcl") saves the pending changes once it is reached. Nothing pending is dropped because of it.
- "picturePath" uploads a local image on iOS and visionOS without sending the path itself. On the other platforms the path is dropped rather than sent as text.
- Added the consent API on "countly.consent":
- "giveConsent(for:)" for one feature or an array / "giveAllConsents()"
- "cancelConsent(for:)" for one feature or an array / "cancelAllConsents()"
- "setConsent(for:given:)"
- "createFeatureGroup(:features:)" / "setConsentFeatureGroup(:given:)" / "hasConsent(forGroup:)"
- "hasConsent(for:)" / "checkAllConsent()", which logs the state of every feature
- Init-time configuration via "CountlyConfig.requiresConsent", "consents" and "enableAllConsents"
- The consent state is sent only when a call changed something. An empty feature list, or a value that names no feature, is ignored with a warning.
- Withdrawing view consent closes every open view, manual ones included. Withdrawing push consent sends an empty push token. Withdrawing feedback consent closes a widget on screen without a "closed" event.
- The "star-rating" consent covers "recordRatingWidget".
- Added the surface a bridge SDK needs to wrap this one:
- "CountlyConfig.sdkName" and "CountlyConfig.sdkVersion", reported in place of this SDK's own, so a Flutter, React Native or Unity integration is attributed to itself
- "ConsentFeature(wireName:)", which maps a consent name as written on the wire onto its feature
- Added the device ID API on "countly.deviceID":
- "current" / "type" / "isTemporaryIDMode"
- Init-time configuration via "CountlyConfig.deviceID" and "temporaryDeviceIDMode"
- "setID(deviceID)", which picks the merge behavior from how the current ID was obtained
- "changeWithMerge(deviceID)" / "changeWithoutMerge(deviceID)". An empty device ID is ignored with a warning.
- "enableTemporaryIDMode()" / "disableTemporaryIDMode(deviceID)". Without a device ID, leaving the mode returns to the device ID and type in use before it, or generates one when the mode began at init.
- A change without merge first stops the views, queues the pending events and profile changes and takes the push token back, all under the leaving user's device ID, then removes consent without a consent request and starts the new user clean.
- A change with merge fetches the behavior settings and the remote config only once the server has accepted the merge request, so the new user is never created before the merge.
- Every start replaces the temporary device ID in requests still queued under it, so such a request cannot hold the queue up.
- Nothing is sent in temporary device ID mode, also requests queued before the mode began. They go out once it ends.
- "Countl...