Biblioteca de eventos - Swift SDK

Configuração de evento padrão

Se você não precisar especificar parâmetros específicos, você poderá usar o EventConfiguration inicializado por padrão:

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

Passar parâmetros para configuração do evento

Você pode passar parâmetros opcionais para personalizar o EventConfiguration:

• metadata: Dicionário de strings de campos de metadados para anexar a cada evento

• syncUser: o usuário a ser usado para sincronizar o(s) Realm(s) de evento. If nil, defaults to the user from the Realm.Configuration.

• partitionPrefix: Prefixo de string para anexar ao valor da partição do evento

• logger: Custom logger to use for events. Se nulo, o padrão será o registrador do Realm do usuário.

• errorHandler: o manipulador de erros personalizado é chamado se ocorrer um erro de sincronização ao fazer o upload dos dados do evento. Se nil, o SDK registra o evento e depois chama abort(). Os aplicativos de produção devem sempre definir um evento errorHandler , a menos que abortar no erro seja o comportamento desejado.

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

Atualizar metadados do evento

Você pode atualizar os metadados mesmo depois de começar a gravar eventos. Utilize a função updateMetadata() para substituir os metadados fornecidos na configuração do evento por novos valores.

Se você atualizar metadados enquanto o escopo de um evento estiver ativo, a Biblioteca de Eventos não utilizará os novos metadados até que o próximo escopo do evento comece.

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

Interaja com o Realm de eventos

Depois de definir a configuração do evento, você pode invocar a funcionalidade de registro de eventos com a nova propriedade de eventos em um domínio. Isso retorna uma instância Event vinculada a esse domínio.

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

Registrar eventos de leitura ou gravação

The Event Library records read and write events within the context of a scope. O escopo é o período durante o qual a evento Library observa e registra as atividades do Realm. Você pode definir escopos diferentes para registrar diferentes tipos de eventos. Por exemplo, você pode ter escopos para fluxos de usuários específicos, como "login", escopos diferentes para telas diferentes ou escopos diferentes para atividades específicas relacionadas à conformidade.

Use começaScope(atividade: "alguma atividade") para começar a gravar um novo evento com o nome de atividade fornecido. Isso retorna um objeto de escopo , que você pode usar para confirmar ou cancelar o escopo posteriormente. O início de um escopo registra as atividades que ocorrem dentro desse escopo como eventos de leitura ou gravação.

• Leia evento: execute query e instancie objeto. Quando o escopo termina, o Realm de evento registra essas atividades como evento de leitura.

• Gravar eventos: modificar objetos. Quando o escopo termina, o Realm registra o estado inicial do objeto, bem como os novos valores de quaisquer propriedades que são alteradas durante o escopo do evento.

Utilizar beginScope para registrar um evento abre o Realm do evento se ele ainda não estiver aberto. O SDK abre os domínios de eventos no thread em segundo plano e relata erros na chamada de resposta de erro.

Quando terminar de gravar eventos para um escopo, use commit() para salvar os eventos que ocorreram dentro do escopo. When you end the recording, the Event Library saves the event to disk locally. Em seguida, se o dispositivo tiver uma conexão de rede, o SDK enviará de forma assíncrona os dados para o servidor.

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

Alternativamente, você pode cancel() um escopo de evento. Isso interrompe a gravação de eventos e não persiste os eventos no disco ou no servidor.

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. Isso retornará true se você tiver iniciado um escopo que ainda não confirmou ou cancelou.

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

Você pode passar um bloqueio de conclusão opcional para commit() quando terminar de gravar. O SDK chama esse bloco quando os dados do evento são persistidos com êxito - não quando o upload do Realm do evento é concluído.

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

Registrar eventos personalizados

A Biblioteca de eventos permite gravar cliques de botão ou outros eventos que não envolvem leituras e gravações de banco de dados. Use recordEvent para registrar um evento personalizado. Esta função utiliza estes parâmetros:

• activity: o nome da atividade. Esta é uma string arbitrária, como "registro de usuário".

• eventType: o tipo de evento. Esta é uma string arbitrária, como "pressionou o botão Enviar".

• data: uma carga de dados opcional para o evento.

• completion: an optional completion handler. A Biblioteca de Eventos chama esse bloco de conclusão assim que o evento é salvo no Realm de eventos ou se ocorrer um erro. Um erro de valor null indica o sucesso.

Um evento personalizado não tem um escopo como eventos de leitura e gravação. Em vez disso, gravar um evento personalizado é mais análogo a disparar um trigger.

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

serialização de objeto JSON

A Biblioteca de Eventos converte cada objeto de evento em um objeto JSON. A maioria dos tipos de Realm possui uma representação JSON análoga. Por exemplo, uma propriedade Realm String torna-se uma JSON String.

É assim que a biblioteca de evento representa os tipos que não possuem um JSON direto:

Os links de objeto incorporado não são codificados como a chave primária do destino. Em eventos de leitura, se o link for seguido, ele se expande para o objeto completo. Se o link não for seguido, esta continua a ser uma chave primária.

Personalizar serialização de eventos

Você pode personalizar a serialização JSON para objetos de evento. Para personalizar a carga útil do evento, use o protocolo CustomEventRepresentable .

Quando um objeto está em conformidade com CustomEventRepresentable, a biblioteca de evento serializa o objeto por:

• Construir um objeto acessor

• Chamando customEventRepresentation nesse objeto de acesso

• Serializando o resultado em vez do objeto original

Para estar em conformidade com CustomEventRepresentable, seu objeto deve implementar uma função customEventRepresentation que defina sua serialização 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

A collection AuditEvent onde os evento são armazenados deve ter um esquema definido no servidor para o aplicativo que recebe evento.

O esquema deve conter os seguintes campos:

Carga útil do evento

Cada evento contém uma carga útil na propriedade data que captura o estado atual dos objetos que estão sendo lidos ou gravados.

As cargas úteis para eventos personalizados podem ser o que o desenvolvedor desejar, incluindo nula.

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