Events

public struct Events

Realm event recording can be used to record all reads and writes performed on a Realm and report them to the server. Enable event recording by setting the eventConfiguration property of the Realm.Configuration used to open a Realm, and then obtain an Events instance with the events property on the Realm.

  • Begin recording events with the given activity name.

    All queries run and all objects instantiated within an event scope will be automatically reported as ‘read’ events when the scope is ended. All objects modified within an event scope will produce ‘write’ events which report the initial state of the object and the new values of all properties which changed.

    Declaration

    Swift

    public func beginScope(activity: String)
  • End recording the current event scope and report all generated events.

    This function saves the events to disk locally and then asynchronously sends them to the server. The optional completion function is called when the event data has been successfully persisted, and not when the actual upload has completed.

    Calls to this function must be paired with calls to beginScope() and an exception will be thrown if no scope is currently active.

    Declaration

    Swift

    public func endScope(completion: ((Swift.Error?) -> Void)? = nil)
  • Record a custom event.

    This function saves the event to disk locally and then asynchronously sends them to the server. The optional completion function is called when the event data has been successfully persisted, and not when the actual upload has completed.

    This function does not interact with event scopes, and can be called with no active scope.

    Declaration

    Swift

    public func recordEvent(activity: String, eventType: String? = nil, data: String? = nil,
                            completion: ((Swift.Error?) -> Void)? = nil)

    Parameters

    activity

    The activity name. This is an arbitrary string stored as-in in the activity event property.

    eventType

    The type of event. This is an arbitrary string stored as-in in the eventType event property.

    data

    The data payload for this event. If supplied, the string stored in the data event property. Note that while automatically generated events all store JSON in this field, custom events are not required to do so.

    completion

    An optional completion handler which will be called once the event has either been saved to the event Realm (but not necessarily uploaded to the server) or an error has occurred. A nil error indicates success.

  • Replace the metadata supplied in the event configuration with new values.

    If called while an event scope is active, the new metadata will not be used until the next event scope is begun.

    See EventConfiguration.metadata for more details on event metdata.

    Declaration

    Swift

    public func updateMetadata(_ newMetadata: [String : String])
  • End recording the current event scope and report all generated events.

    This function saves the events to disk locally and then asynchronously sends them to the server. The returned future is fulfilled when the event data has been successfully persisted, and not when the actual upload has completed.

    Calls to this function must be paired with calls to beginScope() and an exception will be thrown if no scope is currently active.

    Declaration

    Swift

    @_disfavoredOverload
    func endScope() -> Future<Void, Error>
  • Record a custom event.

    This function saves the events to disk locally and then asynchronously sends them to the server. The returned future is fulfilled when the event data has been successfully persisted, and not when the actual upload has completed.

    This function does not interact with event scopes, and can be called with no active scope.

    Declaration

    Swift

    @_disfavoredOverload
    func recordEvent(activity: String, eventType: String? = nil, data: String? = nil)
            -> Future<Void, Error>

    Parameters

    activity

    The activity name. This is an arbitrary string stored as-in in the activity event property.

    eventType

    The type of event. This is an arbitrary string stored as-in in the eventType event property.

    data

    The data payload for this event. If supplied, the string stored in the data event property. Note that while automatically generated events all store JSON in this field, custom events are not required to do so.