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

Puede pasar parámetros opcionales para personalizar EventConfiguration:

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

• syncUser: El usuario que se usará para sincronizar los dominios de eventos. Si es nulo, se usa el usuario de Realm.Configuration de forma predeterminada.

• 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.

• errorHandlerEl controlador de errores personalizado que se llama si se produce un error de sincronización al cargar datos de eventos. Si es nil, el SDK registra el evento y luego llama a abort(). Las aplicaciones de producción siempre deben definir un evento errorHandler, a menos que se desee cancelar la ejecución debido al error.

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.

Si actualiza los metadatos mientras un ámbito de evento está activo, la biblioteca de eventos no utiliza los nuevos metadatos hasta que comience el siguiente ámbito de evento.

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

Grabar eventos personalizados

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:una carga de datos opcional para el evento.

• 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.

Un evento personalizado no tiene un alcance como los eventos de lectura y escritura. Registrarlo es más similar a activar un disparador.

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:

Los enlaces de objetos no incrustados se codifican como la clave principal del destino. En eventos de lectura, si se sigue el enlace, este se expande al objeto completo. Si no se sigue el enlace, este permanece como clave principal.

Personalizar la serialización de eventos

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