Docs Menu
Docs Home
/ /
Atlas Device SDKs
/ /

Event Library - Swift SDK

On this page

  • Overview
  • Before You Begin
  • Enable Event Recording
  • Default Event Configuration
  • Pass Parameters to Event Configuration
  • Update Event Metadata
  • Record Events
  • Interact with the Event Realm
  • Record Read or Write Events
  • Record Custom Events
  • Event Object Serialization
  • JSON Object Serialization
  • Customize Event Serialization
  • Event Realm File Size
  • Event Library Reference
  • Events
  • Event Payload

The Event Library enables you to track a user's activity while using a Sync-enabled mobile application. The Event Library can record read and write transactions. Developers can also configure custom events to record button presses, the data displayed in the UI, or other important details.

When you use the Event Library, you can specify the events you want to record. This means opening two realms:

  • The user realm, where the user does the reading and writing in the client application

  • The event realm, where the Event Library records scoped and custom events

The data from both realms syncs to your App Services App. The client user never interacts directly with the event realm or its data; and the event realm Sync user can even be different from the user realm.

Because the Event Library generates a large amount of data:

  • The client device must have enough capacity to store the data

  • Expect Device Sync usage for the event realm to be higher than the reading and writing in the user realm

  • The App's backing Atlas cluster must have enough storage capacity to handle the data generated by the Event Library

The Event Library stores data in an AuditEvent collection in your linked Atlas data source. Enable Development Mode in your App Services App to let Atlas create the collection and infer the schema from the uploaded events


Partition-Based Sync Required

The Event Library does not support recording AuditEvents using Flexible Sync. This functionality requires a Partition-Based Sync App Services App to record AuditEvent data.

To enable event recording, set the Event.Configuration property on the Realm.Configuration.

You can initialize the EventConfiguration in either of two ways:

  • Use the default-initialized configuration when you don't need to specify details

  • Pass additional parameters to customize the event configuration

If you don't need to specify particular parameters, you can use the default-initialized EventConfiguration:

var config = user.configuration(partitionValue: "Some partition value")
config.eventConfiguration = EventConfiguration()

You can pass optional parameters to customize the EventConfiguration:

  • metadata: String dictionary of metadata fields to append to each event

  • syncUser: The user to use for syncing event realm(s). If nil, defaults to the user from the Realm.Configuration.

  • partitionPrefix: String prefix to append to the event partition value

  • logger: Custom logger to use for events. If nil, defaults to the logger from the user realm.

  • errorHandler: The custom error handler called if a Sync error occurs when uploading event data. If nil, the SDK logs the event and then calls abort(). Production apps should always define an event errorHandler unless aborting on the error is the desired behavior.

let eventSyncUser = try await app.login(credentials: Credentials.anonymous)
var config = user.configuration(partitionValue: "Some partition value")
config.eventConfiguration = EventConfiguration(metadata: ["username": "Jason Bourne"], syncUser: eventSyncUser, partitionPrefix: "event-")

You can update metadata even after you have started recording events. Use the updateMetadata() function to replace the metadata supplied in the event configuration with new values.

If you update metadata while an event scope is active, the Event Library does not use the new metadata until the next event scope begins.

var config = user.configuration(partitionValue: "Some partition value")
config.eventConfiguration = EventConfiguration(metadata: ["username": "Jason Bourne"], syncUser: user, partitionPrefix: "event-")
let realm = try! Realm(configuration: config)
let events =!
let updateUsernameScope = events.beginScope(activity: "Update username")
// Call some function that updates the user's username
// Update the metadata you supplied with the initial EventConfiguration
events.updateMetadata(["username": "John Michael Kane"])

After you define your event configuration, you can invoke the event recording functionality with the new events property on a realm. This returns an Event instance tied to that realm.

let realm = try! Realm(configuration: config)
let events =!

Changed in version 10.36.0: endScope() deprecated for commit() and cancel(), new Scope object

The Event Library records read and write events within the context of a scope. The scope is the period during which the Event Library watches for and records realm activities. You can set different scopes to record different types of events. For example, you might have scopes for specific user flows such as "login", different scopes for different screens, or different scopes for specific compliance-related activities.

Use beginScope(activity: "some activity") to begin recording a new event with the given activity name. This returns a Scope object, which you can use to later commit or cancel the scope. Beginning a scope records activities that occur within that scope as read or write events.

  • Read events: run queries and instantiate objects. When the scope ends, the event realm records these activities as read events.

  • Write events: modify objects. When the scope ends, the event realm records the initial state of the object, as well as the new values of any properties that change durign the scope of the event.

Using beginScope to record an event opens the event realm if it is not already open. The SDK opens event realms on the background thread and reports errors to the error callback.


Overlapping Event Scopes

If more than one event scope is active simultaneously, generated events are recorded by all active scopes.

When you're done recording events for a scope, use commit() to save events that occurred within the scope. When you end the recording, the Event Library saves the event to disk locally. Then, if the device has a network connection, the SDK asynchronously sends the data to the server.

// Read event
let readEventScope = events.beginScope(activity: "read object")
let person = realm.objects(Person.self).first!
print("Found this person: \(")
let mutateEventScope = events.beginScope(activity: "mutate object")
// Write event
try! realm.write {
// Change name from "Anthony" to "Tony" = "Tony"

Alternately, you can cancel() an event scope. This stops recording events, and does not persist the events to disk or to the server.

let eventScope = events.beginScope(activity: "read object")
let person1 = realm.objects(Person.self).first!
print("Found this person: \(")

You can check whether a given scope is currently in progress using the isActive bool. This returns true if you have begun a scope that you have not yet committed or canceled.

let readPersonScope = events.beginScope(activity: "read object")
let person2 = realm.objects(Person.self).first!
print("Found this person: \(")
if readPersonScope.isActive {
print("The readPersonScope is active")
} else {
print("The readPersonScope is no longer active")

You can pass an optional completion block to commit() when you finish recording. The SDK calls this block when the event data has been successfully persisted - not when the event realm upload has completed.

let mutateScope = events.beginScope(activity: "mutate object with completion")
// Write event
try! realm.write {
// Add a userId
person.userId = ""
mutateScope.commit(completion: { error in
if let error = error {
print("Error recording write event: \(error.localizedDescription)")
print("Successfully recorded a write event")

The Event Library lets you record button clicks or other events that do not involve database reads and writes. Use recordEvent to record a custom event. This function takes these parameters:

  • activity: the activity name. This is an arbitrary string, such as "user registration."

  • eventType: the type of event. This is an arbitrary string, such as "pressed Submit button."

  • data: an optional data payload for the event.

  • completion: an optional completion handler. The Event Library calls this completion block once the event has been saved to the event realm, or if an error occurs. A nil error indicates success.

A custom event doesn't have a scope like read and write events. Instead, recording a custom event is more analogous to firing a trigger.

events.recordEvent(activity: "event", eventType: "custom event")

The Event Library converts each event object to a JSON object. Most Realm types have an analogous JSON representation. For example, a Realm String property becomes a JSON String.

This is how the Event Library represents the types that do not have a direct JSON analog:

Encoded to a string in ISO 8601-1:2019 format.
Excluded entirely from the event.
Encoded to a RFC-4122-compliant string.
Encoded to our ObjectID string representation.
Encoded to a string, not a number. JSON numbers are officially infinite- precision, but are rarely actually implemented as such.
Encoded as an array.
Encoded as an array.
Encoded as an object.
Embedded objects
Encoded as an object.

Non-embedded object links are encoded as the primary key of the target. In read events, if the link is followed, this expands to the full object. If the link is not followed, this remains a primary key.

You can customize JSON serialization for event objects. To customize the event payload, use the CustomEventRepresentable protocol.

When an object conforms to CustomEventRepresentable, the Event Library serializes objects by:

  • Constructing an accessor object

  • Calling customEventRepresentation on that accessor object

  • Serializing the result instead of the original object

To conform to CustomEventRepresentable, your object must implement a customEventRepresentation function that defines your customized serialization.

// To customize event serialization, your object must
// conform to the `CustomEventRepresentable` protocol.
class Person: Object, CustomEventRepresentable {
@Persisted(primaryKey: true) var _id: ObjectId
@Persisted var name: String
@Persisted var employeeId: Int
@Persisted var userId: String?
convenience init(name: String, employeeId: Int) {
self.init() = name
self.employeeId = employeeId
// To conform to `CustomEventRepresentable`, your object
// must implement a `customEventRepresentation` func that
// defines your customized event serialization
func customEventRepresentation() -> String {
if employeeId == 0 {
return "invalid json"
return "{\"int\": \(employeeId)}"

The event realm can grow quite large if the device is offline for an extended time.

To compensate for this, the Event Library automatically splits event data into multiple partitions as needed. When a partition reaches its maximum size, the Event Library closes the event realm and automatically begins writing to a new partition.

The Event Library checks whether the user has any unsynced partitions. If they do, the Event Library opens one, uploads the data, and then closes the file and deletes it. This repeats until the user has no unsynced partitions.

The AuditEvent collection where events are stored must have a schema defined on the server for the App receiving events.

The schema must contain the following fields:

Type of Event
Optional string. read or write for scoped events, or an arbitrary string for custom events.
Event Scope
Optional string. The scope name passed to beginScope() to begin recording the event, or an arbitrary string for custom events.
Device local time when the event scope is ended and the data is committed, or the time when the event hits the server.
The event payload. This is a JSON blob for scoped events, or an arbitrary string for custom events.
metadata key (string)
An optional metadata dictionary. When this dictionary contains keys and values, the key becomes a field name in the event object, and the value is stored in that field for every event.

Each event contains a payload in the data property that captures the current state of the objects being read or written to.

Payloads for custom events can be whatever the developer desires, including nil.


Because the payload captures the current state of the objects being read or written to, this produces a very large amount of data. However, this must be done on the client rather than the server, as the exact data that the user views may never exist server-side. In practice, this means that the device must have the capacity to store a large amount of data if it goes offline. Additionally, Device Sync usage for the event realm may be much higher than for the reading and writing the user does in the user realm.


In our Record Events examples above, these are the data payloads for the read and write events:

Read Event Payload
"value": [{
Write Event Payload
"Person": {
"modifications": [{
"newValue": {
← Set the Client Log Level - Swift SDK