Add Message History feature doc and more group chat code samples #775
Conversation
jhaaaa
commented
Jul 8, 2024
•
jhaaaa
commented
- Message history doc preview link
- Group chat doc preview link
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Deploying xmtp-org with
|
| Latest commit: |
ae42d8f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://38297b6a.website-9re.pages.dev |
| Branch Preview URL: | https://message-hist.website-9re.pages.dev |
jhaaaa
changed the title
docs/build/group-chat.md
Outdated
|
|
||
| To enable your users to avoid losing access to their local databases, allow them to store their local cache in iCloud or Google Cloud, for example. This option will enable message persistence within a single app ecosystem. | ||
| If you choose to not enable message history, you can help users avoid losing access to their local databases by allowing them to store their local cache in iCloud or Google Cloud, for example. This option will enable message persistence within a single app ecosystem. |
There was a problem hiding this comment.
But we still advice at the very least adding a url on create so other apps may benefit from message history.
docs/build/group-chat.md
Outdated
|
|
||
| If you choose to provide neither message history nor local cache storage, be sure to clearly communicate the concept of losing access to group chat messages to your users. For example, you might consider using this language: | ||
|
|
||
| > If you log out of <app name> and log into a different app on this device, or delete <app name> from this device, you will lose access to all group chat messages you sent using this installation of <app name> on this device. |
There was a problem hiding this comment.
Don't worry though you will still have access to your group chat conversations. Just non of the previous messages in them.
docs/build/message-history.md
Outdated
|
|
||
| ## Set message history sync URL | ||
|
|
||
| When your app creates a new client, specify the location where the client should sync message history. |
There was a problem hiding this comment.
Whether you want to use the other message history features or not we recommend atleast setting this url. This allows other apps to pull in message history in the future. The easiest way would be to use our history sync url.
| enableV3: true, | ||
| appVersion: 'YourApp/1.0.0', | ||
| // Add the history sync URL option | ||
| historySyncUrl: 'SYNC_URL' |
There was a problem hiding this comment.
Maybe we should set our message history sync url here? Or should the sdk by default set it to the ephemera one? @tuddman did we decide if the SDK is going to set a message history url by default if they don't provide one?
There was a problem hiding this comment.
Love the idea of setting it to the Ephemera message history server URL by default... This way devs who aren't implementing message history won't have to do anything to ensure that they support the UX of other apps.
If anything, in the docs we can just disclose that this URL is set by default and if you don't want to participate - you can remove it.
However - is there any harm in having an app's message history collected on this server without their explicit permission?
There was a problem hiding this comment.
There's really two options to set here:
- should message-history-sync be enabled (by default)?
- and if so (enabled), what URL should the app use? And if not set, what is our default?
We decided that option-1 - should be the case in the SDK. Message history sync ability- should be enabled by default.
Ephemera's History server URL is http://history.dev.xmtp.network/
We can spin up an additional server which will be accessible at http://history.production.xmtp.network/ but the latter is not live yet.
We can set option 2 - if not otherwise provided - to that URL.
However - is there any harm in having an app's message history collected on this server without their explicit permission?
An app's message history is NOT collected on any server without their explicit permission. Even if it were, its all encrypted so it's safe in that respect, but it's not stored without their explicit permission, so a non-issue. The nuance is that new-device explicitly requests a history-sync, and it is the responding device with the same inbox-id that responds automatically. But as the inbox owner is in all cases presumptively the same person, it's really the case that they are providing explicit permission.
There was a problem hiding this comment.
Thank you for this, @tuddman and @nplasterer! I have just a few comments and questions, please...
-
Is message history sync ability enabled by default if the
historySyncUrlneeds to be set manually by the dev? The functionality is there - but it isn't enabled until the dev sets this value, is that correct? If we were to set thehistorySyncUrlvalue to http://history.dev.xmtp.network/ without dev intervention, I think this would truly be enabled by default? -
Regarding Ephemera's history server URL http://history.dev.xmtp.network/ - I wonder if we should adjust the URL to make it clear that it is a centralized server run by Ephemera?
- Maybe history.dev.ephemera-xmtp.network?
-
Regarding the future URL http://history.production.xmtp.network/ - I don't think it needs to include "production" and can be just http://history.ephemera-xmtp.network/, for example.
There was a problem hiding this comment.
I think it makes sense for it to have the name ephemera in it! @tuddman can you make that change?
The ability to get the messages into another installation is enabled by default if we include a default url. But requesting message history is not enabled by default if that makes sense. The app you are using still needs to make a request for a message history but with this default url being set it atleast gives us a better chance of an app having a message history to sync from.
There was a problem hiding this comment.
Love it, @nplasterer - absolutely understood.
Providing a default message history server URL helps ensure that App A can provide message history for other apps to use without any manual steps required for the dev of App A.
docs/build/message-history.md
Outdated
| ClientOptions.Api(XMTPEnvironment.PRODUCTION, true), | ||
| enableV3 = true, | ||
| appContext = context | ||
| historySyncUrl = "SYNC_URL" |
There was a problem hiding this comment.
Not for this PR but we recently started requiring the dbEncryption key is passed. So maybe we should change all of these client options to include a dbEncryption key to make that clear.
| <TabItem value="swift" label="Swift" attributes={{className: "swift_tab"}}> | ||
|
|
||
| ```swift | ||
| try await client.requestMessageHistorySync() |
There was a problem hiding this comment.
| try await client.requestMessageHistorySync() | |
| try await client.requestHistorySync() |
| <TabItem value="kotlin" label="Kotlin" attributes={{className: "kotlin_tab"}}> | ||
|
|
||
| ```kotlin | ||
| client.requestMessageHistorySync() |
There was a problem hiding this comment.
| client.requestMessageHistorySync() | |
| client.requestHistorySync() |
There was a problem hiding this comment.
I actually think this is named correctly. I wanted it to be more clear what we are syncing especially with potential conversation and personal preference syncs coming in the future. Open to revisiting this wording if you think it should just be history sync.
| <TabItem value="rn" label="React Native" attributes={{className: "rn_tab"}}> | ||
|
|
||
| ```jsx | ||
| await client.requestMessageHistorySync() |
There was a problem hiding this comment.
| await client.requestMessageHistorySync() | |
| await client.requestHistorySync() |
| Calling `sync()` for a group or groups gets any updates since the last sync and adds them to the local database. Be sure to periodically synchronize each group chat to ensure your app has the latest group chat details, including the most recent messages, member list, and group chat details, for example. | ||
| Calling `sync()` for a group or groups gets any updates since the last sync and adds them to the local database. | ||
|
|
||
| Sync group chats anytime a user accesses a conversation view. This sync is especially important if a user backgrounds (switches away from) your app, then reopens the app and accesses a conversation view. |
There was a problem hiding this comment.
When we say "conversation view" - just to be sure - Is this the view when a user opens a group chat and can see the messages in the group chat?
|
|
||
| Sync group chats anytime a user accesses a conversation view. This sync is especially important if a user backgrounds (switches away from) your app, then reopens the app and accesses a conversation view. | ||
|
|
||
| When the user reopens the app, the app might be using an old epoch (snapshot) of data. This is even more likely to be true if there were many group membership changes during the time the app was backgrounded. A group chat sync bumps the app to the latest epoch, helping to ensure that your user always sees the current group chat, including the most recent messages, member list, and group chat details, for example. | ||
|
|
||
| Updates are also retrieved and added to the local database when streaming and when the user takes an action. |
There was a problem hiding this comment.
I am unclear on what this sentence above means. Is this saying that streaming and user actions automatically trigger "sync group chat"?
There was a problem hiding this comment.
Not an automatic sync but streaming does receive messages and add them to local users database. My understanding is if a commit message is streamed (adding a user to the group) it should update the epoch in the stream.
|
|
||
| Sync group chats anytime a user accesses a conversation view. This sync is especially important if a user backgrounds (switches away from) your app, then reopens the app and accesses a conversation view. | ||
|
|
||
| When the user reopens the app, the app might be using an old epoch (snapshot) of data. This is even more likely to be true if there were many group membership changes during the time the app was backgrounded. A group chat sync bumps the app to the latest epoch, helping to ensure that your user always sees the current group chat, including the most recent messages, member list, and group chat details, for example. |
There was a problem hiding this comment.
Maybe we could make it clearer what an old epoch is. An old epoch is an old decryption/encryption key for the group. Every time a member is added or removed the decryption/encryption keys get rotated so that old members cannot decrypt messages going forward and no members can not decrypt old messages from the group before they joined etc... If an app doesn't sync often the epochs for a user can get so far behind that they can no longer decrypt messages (read new messages) or encrypt messages (send messages that can be decrypted by others in the group). This is why syncing often is important.
