イベント ライブラリ - Swift SDK

デフォルトのイベント構成

特定のパラメータを指定する必要がない場合は、デフォルトで初期化されたEventConfigurationを使用できます。

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

イベント構成へのパラメーターの渡し

任意のパラメータを渡して、 EventConfigurationをカスタマイズできます。

• metadata: 各イベントに追加するメタデータ フィールドの string の辞書

• syncUser: イベント邦土を同期するために使用するユーザー。 nil の場合、デフォルトはRealm.Configurationのユーザーになります。

• partitionPrefix: イベント パーティション値に追加する string プレフィックス

• logger: イベントに使用するカスタム ロガー。 nil の場合、デフォルトはユーザー邦土のロガーになります。

• errorHandler: イベント データのアップロード中に 同期エラー が発生した場合に呼び出されるカスタム エラー ハンドラー。 nilの場合、SDK はイベントをログに記録し、 abort()を呼び出します。 実稼働アプリでは、エラーで中止することが目的の動作でない限り、常にイベントerrorHandlerを定義する必要があります。

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

イベント メタデータの更新

イベントの記録を開始した後でもメタデータを更新できます。 イベント構成で提供されたメタデータを新しい値に置き換えるには、 updateMetadata()関数を使用します。

イベント スコープがアクティブなときにメタデータを更新すると、イベント ライブラリは次のイベント スコープが開始されるまで新しいメタデータを使用しません。

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

イベント Realm とのやり取り

イベント構成を定義したら、 Realm で新しい イベント プロパティを使用してイベント記録機能を呼び出すことができます。これにより、その Realm に関連付けられたEventインスタンスが返されます。

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

読み取りイベントまたは書込み (write) イベントの記録

イベント ライブラリは、スコープのコンテキスト内の読み取りイベントと書込み (write) イベントを記録します。 スコープは、イベント ライブラリが Realm のアクティビティを監視し、記録する期間です。 異なるタイプのイベントを記録するには、異なるスコープを設定できます。 たとえば、「ログイン」などの特定のユーザーフローに対してスコープを設定したり、さまざまな画面に対して異なるスコープを設定したり、特定のコンプライアンス関連のアクティビティに対して異なるスコープを設定したりできます。

startScoper（アクティビティ: "いくつかのアクティビティ"）を使用して、指定されたアクティビティ名で新しいイベントの記録を開始します。 これにより、後でスコープをコミットまたはキャンセルするために使用できるSscopeオブジェクトが返されます。 スコープを開始すると、そのスコープ内で発生するアクティビティを読み取りまたは書込みイベントとして記録します。

• 読み取りイベント: クエリを実行し、オブジェクトをインスタンス化します。 スコープが終了すると、イベント邦土はこれらのアクティビティを読み取りイベントとして記録します。

• 書き込みイベント: オブジェクトを変更します。 スコープが終了すると、イベント邦土はオブジェクトの初期状態と、イベントのスコープ内で変更されたプロパティの新しい値を記録します。

イベントを記録するには、 beginScopeを使用します（イベント邦土がまだ開いていない場合）。 SDK はバックグラウンド スレッドでイベント邦土を開き、エラーをエラー コールバックに報告します。

スコープのイベントを記録し始めたら、 commit()を使用してスコープ内で発生したイベントを保存します。 記録を終了すると、イベント ライブラリはイベントをローカルにディスクに保存します。 次に、デバイスにネットワーク接続がある場合、SDK は非同期にデータをサーバーに送信します。

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

あるいは、イベントスコープをcancel()することもできます。 これにより、イベントの記録が停止し、イベントがディスクやサーバーに永続化しません。

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

特定のスコープが現在進行中かどうかは、 isActiveブール値を使用して、特定のスコープが現在進行中かどうかを確認できます。 まだコミットまたはキャンセルしていないスコープを開始した場合は、 trueが返されます。

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

記録が完了するときに、任意の完了ブロックをcommit()に渡すことができます。 SDK は、イベント Realm のアップロードが完了した場合ではなく、イベント データが正常に保存された場合にこのブロックを呼び出します。

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

カスタム イベントの記録

イベント ライブラリを使用すると、ボタンをクリックしたり、データベースの読み取りや書込みを含まないその他のイベントを記録できます。 カスタム イベントを記録するには、 RecordEventを使用します。 この関数は、次のパラメーターを取ります。

• activity: アクティビティ名。 これは「user register」などの任意の string です。

• eventType: イベントの種類。 これは「送信ボタンを押した」などの任意のstringです。

• data: イベントの任意のデータペイロード。

• completion: 任意の完了ハンドラー。 イベント ライブラリは、イベントがイベント レルムに保存されると、またはエラーが発生した場合にこの完了ブロックを呼び出します。 nil エラーは成功を示します。

カスタム イベントには、読み取りイベントや書込みイベントのようなスコープはありません。 代わりに、カスタム イベントを記録することは、trigger を起動することよりも類似しています。

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

JSON オブジェクト直列化

イベント ライブラリは、各イベント オブジェクトを JSON オブジェクトに変換します。 ほとんどのRealm タイプは類似した JSON 表現をとります。 たとえば、Realm string プロパティは JSON string になります。

以下は、イベント ライブラリが直接的な JSON アナライザを持たない型を表す方法です。

非埋め込みオブジェクト リンクは、ターゲットのプライマリキーとしてエンコードされます。 読み取り イベントでは、 リンクに従うと、完全なオブジェクトに展開されます。 リンクを追跡しない場合は、これはプライマリキーのままになります。

イベント直列化をカスタマイズ

イベント オブジェクトの JSON シリアル化をカスタマイズできます。 イベントペイロードをカスタマイズするには、 CustomEventRepresentationableプロトコルを使用します。

オブジェクトがCustomEventRepresentableに準拠している場合、イベント ライブラリは次の方法でオブジェクトを直列化します。

• accessor オブジェクトの構築

• そのアクセス オブジェクトでcustomEventRepresentationを呼び出す

• 元のオブジェクトではなく結果を直列化

CustomEventRepresentableに準拠するには、カスタマイズされた直列化を定義するcustomEventRepresentation関数をオブジェクトが実装する必要があります。

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

イベント

イベントが保存されるAuditEventコレクションには、アプリがイベントを受信するためにサーバー上に定義されたスキーマが必要です。

スキーマには、次のフィールドが含まれている必要があります。

イベントペイロード

各イベントには、読み取りまたは書き込みされるオブジェクトの現在の状態を取得するdataプロパティのペイロードが含まれています。

カスタム イベントのペイロードは、 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
      }
    }]
  }
}