Event Library - Swift SDK Only

Default 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()

Pass Parameters to Event Configuration

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-")

Update Event Metadata

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 = realm.events!
let updateUsernameScope = events.beginScope(activity: "Update username")
// Call some function that updates the user's username
updateUsername()
updateUsernameScope.commit()
// Update the metadata you supplied with the initial EventConfiguration
events.updateMetadata(["username": "John Michael Kane"])

Interact with the Event Realm

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 = realm.events!

Record Read or Write Events

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.

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: \(person.name)")
readEventScope.commit()
let mutateEventScope = events.beginScope(activity: "mutate object")
// Write event
try! realm.write {
    // Change name from "Anthony" to "Tony"
    person.name = "Tony"
}
mutateEventScope.commit()

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: \(person1.name)")
eventScope.cancel()

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: \(person2.name)")
if readPersonScope.isActive {
    print("The readPersonScope is active")
} else {
    print("The readPersonScope is no longer active")
}
readPersonScope.cancel()

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 = "tony.stark@starkindustries.com"
}
mutateScope.commit(completion: { error in
    if let error = error {
        print("Error recording write event: \(error.localizedDescription)")
        return
    }
    print("Successfully recorded a write event")
})

Record Custom Events

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")

JSON Object Serialization

The Event Library converts each event object to a JSON object. Most SDK 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:

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.

Customize Event Serialization

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()
        self.name = 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)}"
    }
}

Events

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:

Event Payload

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.

{
  "type":"Person",
  "value": [{
    "_id":"62b38b3c10846041166f5deb",
    "_partition":"",
    "employeeId":2,
    "name":"Anthony",
    "userId":null
  }]
}

{
  "Person": {
    "modifications": [{
      "newValue": {
        "name":"Tony"
      },
      "oldValue":{
        "_id":"62b38b3c10846041166f5deb",
        "_partition":"",
        "employeeId":2,
        "name":"Anthony",
        "userId":null
      }
    }]
  }
}