Librería de eventos - Swift SDK

Configuración de eventos predeterminada

Si no necesita especificar parámetros particulares, puede utilizar el valor predeterminado inicializado EventConfiguration:

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 cadenas de campos de metadatos 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: Prefijo de cadena para agregar al valor de la partición del evento

• loggerRegistrador personalizado para eventos. Si es nulo, se usa el registrador del dominio del usuario de forma predeterminada.

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

Actualizar metadatos del evento

Puedes actualizar los metadatos incluso después de haber iniciado la grabación de eventos. Usa la función updateMetadata() para reemplazar los metadatos proporcionados en la configuración del evento con los nuevos valores.

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úa con el reino de eventos

Después de definir la configuración de eventos, puede invocar la función de grabación de eventos con la nueva propiedad "eventos" en un dominio. Esto devuelve una Event instancia asociada a ese dominio.

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

Registrar eventos de lectura o escritura

La Biblioteca de Eventos registra eventos de lectura y escritura dentro del contexto de un ámbito. El ámbito es el periodo durante el cual la Biblioteca de Eventos supervisa y registra las actividades del dominio. Puede configurar diferentes ámbitos para registrar distintos tipos de eventos. Por ejemplo, puede tener ámbitos para flujos de usuario específicos, como "inicio de sesión", distintos ámbitos para distintas pantallas o distintos ámbitos para actividades específicas relacionadas con el cumplimiento normativo.

Use beginScope(activity: "some activity") para comenzar a registrar un nuevo evento con el nombre de actividad especificado. Esto devuelve un objeto Scope, que puede usar para confirmar o cancelar el alcance posteriormente. Al iniciar un alcance, se registran las actividades que ocurren dentro de él como eventos de lectura o escritura.

• Eventos de lectura: ejecutan consultas e instancian objetos. Al finalizar el ámbito, el dominio de eventos registra estas actividades como eventos de lectura.

• Escribir eventos: modificar objetos. Al finalizar el ámbito, el dominio de eventos registra el estado inicial del objeto, así como los nuevos valores de cualquier propiedad que cambie durante el ámbito del evento.

Usar beginScope para registrar un evento abre el dominio de eventos si aún no está abierto. El SDK abre dominios de eventos en el subproceso en segundo plano e informa de los errores a la devolución de llamada de errores.

Al terminar de grabar eventos para un ámbito, use commit() para guardar los eventos ocurridos dentro de él. Al finalizar la grabación, la biblioteca de eventos guarda el evento en el disco localmente. Luego, si el dispositivo tiene conexión de red, el SDK envía los datos al servidor de forma asíncrona.

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

Como alternativa, puede cancel() un ámbito de evento. Esto detiene el registro de eventos y no los conserva en el disco ni en el servidor.

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

Puede comprobar si un ámbito dado está en curso mediante el booleano isActive. Este valor devuelve true si ha iniciado un ámbito que aún no ha confirmado ni cancelado.

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

Puedes pasar un bloque de finalización opcional a commit() al finalizar la grabación. El SDK llama a este bloque cuando los datos del evento se han almacenado correctamente, no cuando se completa la carga del dominio de eventos.

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: el nombre de la actividad. Esta es una cadena arbitraria, como "registro de usuario".

• eventType: el tipo de evento. Esta es una cadena arbitraria, como "presionó el botón Enviar".

• data:una carga de datos opcional para el evento.

• completion: un controlador de finalización opcional. La biblioteca de eventos llama a este bloque de finalización una vez que el evento se ha guardado en el dominio de eventos o si se produce un error. Un error nulo indica éxito.

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

La biblioteca de eventos convierte cada objeto de evento en un objeto JSON. La mayoría de los tipos de dominio tienen una representación JSON similar. Por ejemplo, una propiedad de cadena de dominio se convierte en una cadena JSON.

Así es como la biblioteca de eventos representa los tipos que no tienen un análogo JSON directo:

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.

Cuando un objeto se ajusta a CustomEventRepresentable, la biblioteca de eventos serializa los objetos mediante:

• Construyendo un objeto de acceso

• Llamando a customEventRepresentation en ese objeto de acceso

• Serializar el resultado en lugar del objeto original

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

La colección AuditEvent donde se almacenan los eventos debe tener un esquema definido en el servidor para la aplicación que recibe eventos.

El esquema debe contener los siguientes campos:

Carga útil del evento

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.

Las cargas útiles para eventos personalizados pueden ser las que desee el desarrollador, incluso nulas.

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