Sync preferences

Preference sync enables you to sync the following preference-related information across multiple existing app installations:

• Conversation consent preferences
• Conversation HMAC keys (for push notifications)

Databases used by preference sync

Each xmtpd node contains:

• A welcomes database: Keeps a ledger of all groups an inbox ID is a part of.
• A group messages database: Keeps a ledger of all messages in the groups an inbox ID is a part of.

In the welcomes database, the groups are of these types:

• 1:1 chat: A group that handles conversations between an inbox ID and one other user.
• Group chat: A group that handles conversations between an inbox ID and multiple other users.
• Preferences: A group that handles syncing preferences between an inbox ID's existing app installations.

One-to-one chat, group chat, and preferences groups in the welcome database are updated by apps as follows:

• 1:1 chats
  • conversations.list
  • syncAll
  • streamAll
• Group chats
  • conversations.list
  • syncAll
  • streamAll
• Preferences
  • preferences.sync
  • syncAll
  • streamAll

Preferences group

To describe preference sync, let's first focus on how the preferences group works.

1. A preferences group has one member, which is one inbox ID.

2. Let's say Inbox ID Alix has an Installation A of App A on their phone. At this time, Inbox ID Alix has a preferences group that looks like this:

   

3. Inbox ID Alix then logs in to an Installation B of App B on their phone. The next time Installation A runs preferences.sync, syncAll, or streamAll, it updates the preferences group as follows:

   

4. Then let's say Inbox ID Alix logs in to an Installation C of App A on their tablet. The next time Installation A or B runs preferences.sync, syncAll, or streamAll, it updates the preferences group as follows:

   

Preferences sync worker

Now, let's describe how the preferences sync worker helps keep user consent preferences in sync across existing app installations.

1. Let's say Inbox ID Alix uses Installation A to block Inbox ID Bo.

   

2. This sends a message to the preferences group in the group message database. This is not an actual chat message, but a serialized proto message that is not shown to app users.

   

3. When Installation B calls preferences.sync, syncAll, or streamAll, it gets the message from the preferences group. The sync worker listens for these preferences group messages and processes the message to block Inbox ID Bo in Installation B.

   

4. Likewise, when Installation C calls preferences.sync, syncAll, or streamAll, it gets the message from the preferences group, and the sync worker ensures Inbox ID Bo is blocked there as well.

   

Preferences sync handles syncing HMAC keys in the same way.

For example, it will handle syncing an HMAC key shared by Installation B to other installations. When Installation A and C call preferences.sync, syncAll, or streamAll, the sync worker gets Installation B's HMAC key message from the preferences group and ensures that Installation A and C get the HMAC key for Installation B.

Sync preferences

Use this call to sync preferences (consent preferences and HMAC keys) across app installations in a preferences group. This will also sync welcomes to ensure that you have all potential new installations before syncing.

This is a lighter-weight alternative to syncing preferences using syncAll or streamAll.

await client.preferences.sync();