Librería de eventos - Swift SDK

Default Event Configuration

Si no necesitas especificar parámetros particulares, puedes usar el EventConfiguration inicializado por defecto:

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

Pasar parámetros a la configuración del evento

You can pass optional parameters to customize the EventConfiguration:

• metadata: Diccionario de metadatos de tipo String para agregar a cada evento

• 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: Registrador personalizado para usar en eventos. Si es nil, se utiliza por defecto el registrador del usuario en el 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

Después de definir la configuración de eventos, puedes invocar la funcionalidad de grabación de eventos con la nueva propiedad events en un realm. Esto devuelve una instancia Event ligada a ese 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.

Utiliza beginScope(activity: "some activity") para comenzar a registrar un nuevo evento con el nombre de actividad dado. Esto devuelve un objeto Scope, que puedes usar posteriormente para confirmar o cancelar el alcance. El comenzar un alcance registra las actividades que ocurren dentro de ese alcance como eventos de lectura o escritura.

• 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

La librería de eventos te permite registrar clics de botón u otros eventos que no impliquen lecturas y guardados en la base de datos. Utiliza registroEvento para registrar un evento personalizado. Esta función toma los siguientes parámetros:

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

Serialización de objetos JSON

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:

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

Puede personalizar la serialización JSON de los objetos de evento. Para personalizar la carga útil del evento, utilice el protocolo CustomEventRepresentable.

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

Para cumplir con CustomEventRepresentable, tu objeto debe implementar una función customEventRepresentation que defina tu serialización personalizada.

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

Eventos

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

Cada evento contiene una carga útil en la propiedad data que captura el estado actual de los objetos que se están leyendo o escribiendo.

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
      }
    }]
  }
}