From 53e4fee0b98e85e45329ab1de5bc26d1a65d3538 Mon Sep 17 00:00:00 2001 From: Naomi Plasterer Date: Mon, 16 Oct 2023 16:26:31 -0700 Subject: [PATCH 1/5] feat: move the app into production --- README.md | 117 +++++++----------------------------------------------- 1 file changed, 15 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 8a0dc773d..54111251e 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,7 @@ This repo provides a package you can use to build with XMTP in a React Native or Expo app. -> **Important** -> This SDK is in **beta** status and ready for you to start experimenting with. -> -> However, we do **not** recommend using beta software in production apps. Software in this status will change as we add features and iterate based on feedback. - -We're still working on adding several features to bring this SDK to parity with the [XMTP client SDK for JavaScript](https://github.com/xmtp/xmtp-js) (`xmtp-js`). Here's a [list of features and issues](https://github.com/xmtp/xmtp-react-native/issues/14) we're working on. - -Is there a feature you need that's not on the list? Please [open an issue](https://github.com/xmtp/xmtp-react-native/issues). +Is there a feature you need that's currently supported? Please [open an issue](https://github.com/xmtp/xmtp-react-native/issues). Or better yet, open a PR and we'll get it reviewed and merged as soon as possible. If you contribute a PR that gets merged into this repo, you'll be eligible to [claim this XMTP contributor POAP](https://www.gitpoap.io/gp/1042)! @@ -157,7 +150,7 @@ These conversations include all conversations for a user **regardless of which a You can also listen for new conversations being started in real-time. This will allow applications to display incoming messages from new contacts. > **Warning** -> This stream will continue infinitely. To end the stream you can either break from the loop, or call `await stream.return()`. +> This stream will continue infinitely. To end the stream you can call `cancelStream()`. ```tsx const stream = await xmtp.conversations.stream() @@ -227,7 +220,7 @@ You can listen for any new messages (incoming or outgoing) in a conversation by A successfully received message (that makes it through the decoding and decryption without throwing) can be trusted to be authentic, i.e. that it was sent by the owner of the `message.senderAddress` wallet and that it wasn't modified in transit. The `message.sent` timestamp can be trusted to have been set by the sender. -The Stream returned by the `stream` methods is an asynchronous iterator and as such usable by a for-await-of loop. Note however that it is by its nature infinite, so any looping construct used with it will not terminate, unless the termination is explicitly initiated (by breaking the loop or by an external call to `Stream.return()`) +The Stream returned by the `stream` methods is an asynchronous iterator and as such usable by a for-await-of loop. Note however that it is by its nature infinite, so any looping construct used with it will not terminate, unless the termination is explicitly initiated by calling `cancelStreamMessages()` ```tsx const conversation = await xmtp.conversations.newConversation( @@ -249,6 +242,9 @@ To listen for any new messages from _all_ conversations, use `conversations.stre > **Note** > There is a chance this stream can miss messages if multiple new conversations are received in the time it takes to update the stream to include a new conversation. +> **Warning** +> This stream will continue infinitely. To end the stream you can call `cancelStreamAllMessages()`. + ```tsx for await (const message of await xmtp.conversations.streamAllMessages()) { if (message.senderAddress === xmtp.address) { @@ -319,38 +315,19 @@ All send functions support `SendOptions` as an optional parameter. The `contentT To learn more about content types, see [Content types with XMTP](https://xmtp.org/docs/concepts/content-types). -Support for other types of content can be added by registering additional `ContentCodecs` with the `Client`. Every codec is associated with a content type identifier, `ContentTypeId`, which is used to signal to the client which codec should be used to process the content that is being sent or received. - - - For example, see the [Codecs](https://github.com/xmtp/xmtp-react-native/blob/main/src/lib/CodecRegistry.ts) available in `xmtp-react-native`. ```tsx -// Assuming we've loaded a fictional NumberCodec that can be used to encode numbers, -// and is identified with ContentTypeNumber, we can use it as follows. - - const numberCodec = new NumberCodec(); - const registry = new CodecRegistry(); - registry.register(numberCodec); - - const id = numberCodec.contentType.id(); - const codec = registry.find(id); - - const encodedContent = codec.encode(3.14); - const data = content.EncodedContent.encode(encodedContent).finish(); - - await conversation.send(data); + await conversation.send({ + reaction: { + reference: otherMessage.id, + action: "added", + schema: "unicode", + content: "💖", + }, + }); ``` -As shown in the example above, you must provide a `contentFallback` value. Use it to provide an alt text-like description of the original content. Providing a `contentFallback` value enables clients that don't support the content type to still display something meaningful. - -> **Caution** -> If you don't provide a `contentFallback` value, clients that don't support the content type will display an empty message. This results in a poor user experience and breaks interoperability. - -To learn more about how to build a custom content type, see [Build a custom content type](https://xmtp.org/docs/concepts/content-types#build-a-custom-content-type). - -Custom codecs and content types may be proposed as interoperable standards through XRCs. To learn about the custom content type proposal process, see [XIP-5](https://github.com/xmtp/XIPs/blob/main/XIPs/xip-5-message-content-types.md). - ## Manually handle private key storage The SDK will handle key storage for the user by encrypting the private key bundle using a signature generated from the wallet, and storing the encrypted payload on the XMTP network. This can be awkward for some server-side applications, where you may only want to give the application access to the XMTP keys but not your wallet keys. Mobile applications may also want to store keys in a secure enclave rather than rely on decrypting the remote keys on the network each time the application starts up. @@ -369,71 +346,7 @@ The keys returned by `exportKeyBundle` should be treated with the utmost care as ## Enable the example app to send push notifications -You can use a Firebase Cloud Messaging server and an example push notification server to enable the `xmtp-react-native` example app to send push notifications. - -Perform this setup to understand how you might want to enable push notifications for your own app built with the `xmtp-react-native` SDK. - -### Set up a Firebase Cloud Messaging server - -For this tutorial, we'll use [Firebase Cloud Messaging](https://console.firebase.google.com/) (FCM) as a convenient way to set up a messaging server. - -1. Create an FCM project. - -2. Add the example app to the FCM project. This generates a `google-services.json` file that you need in subsequent steps. - -3. Add the `google-services.json` file to the example app's project as described in the FCM project creation process. - -4. Generate FCM credentials, which you need to run the example notification server. To do this, from the FCM dashboard, click the gear icon next to **Project Overview** and select **Project settings**. Select **Service accounts**. Select **Go** and click **Generate new private key**. - -### Run an example notification server - -Now that you have an FCM server set up, take a look at the [export-kotlin-proto-code](https://github.com/xmtp/example-notification-server-go/tree/np/export-kotlin-proto-code) branch in the `example-notifications-server-go` repo. - -This example branch can serve as the basis for what you might want to provide for your own notification server. The branch also demonstrates how to generate the proto code if you decide to perform these tasks for your own app. This proto code from the example notification server has already been generated in the `xmtp-android` example app. - -**To run a notification server based on the example branch:** - -1. Clone the [example-notification-server-go](https://github.com/xmtp/example-notification-server-go) repo. - -2. Complete the steps in [Local Setup](https://github.com/xmtp/example-notification-server-go/blob/np/export-kotlin-proto-code/README.md#local-setup). - -3. Get the FCM project ID and FCM credentials you created earlier and run: - - ```bash - YOURFCMJSON=`cat YOURFIREBASEADMINFROMSTEP4.json` - ``` - - ```bash - dev/run \ - --xmtp-listener-tls \ - --xmtp-listener \ - --api \ - -x "production.xmtp.network:5556" \ - -d "postgres://postgres:xmtp@localhost:25432/postgres?sslmode=disable" \ - --fcm-enabled \ - --fcm-credentials-json=$YOURFCMJSON \ - --fcm-project-id="YOURFCMPROJECTID" - ``` - -4. You should now be able to see push notifications coming across the local network. - -### Update the Android example app to send push notifications - -1. Checkout the `push-notifications-example` branch - -2. Add your `google-services.json` file to the `example/android/app` folder if you haven't already done it as a part of the FCM project creation process. - -3. Uncomment `apply plugin: 'com.google.gms.google-services'` in the example app's `build.gradle` file. - -4. Uncomment `classpath('com.google.gms:google-services:4.3.15')` in the top level of the example app's `build.gradle` file. - -5. Sync the gradle project. - -6. Replace `YOUR_SERVER_ADDRESS` in the `PullController.ts` file. If you're using the example notification server, it should be something like `YOURIPADDRESS:8080` since the Android emulator takes over localhost. - -7. Change the example app's environment to `production` in both places in `AuthView.tsx`. - -8. Replace `YOUR_FIREBASE_SENDER_ID` in the `PullController.ts` with your sender ID from Firebase. +Check out the `push-notifications-example` branch and follow instructions in the README ## 🏗 Breaking revisions From 0e3620fb606a36cbc1e572a68af5a81791b78e4e Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Mon, 16 Oct 2023 18:13:53 -0700 Subject: [PATCH 2/5] docs: a few tw tweaks --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 54111251e..862261d56 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # xmtp-react-native -![Lint](https://github.com/xmtp/xmtp-android/actions/workflows/lint.yml/badge.svg) ![Status](https://img.shields.io/badge/Project_Status-Beta-yellow) +![Lint](https://github.com/xmtp/xmtp-android/actions/workflows/lint.yml/badge.svg) ![Status](https://img.shields.io/badge/Project_Status-Production-brightgreen) This repo provides a package you can use to build with XMTP in a React Native or Expo app. @@ -92,7 +92,7 @@ Currently, network nodes are configured to rate limit high-volume publishing fro > **Important** > If you are building a production-grade app, be sure to use an architecture that includes a local cache backed by an XMTP SDK. -To learn more, see [Use a local cache](https://xmtp.org/docs/tutorials/performance#use-a-local-cache). +To learn more, see [Use local-first architecture](https://xmtp.org/docs/build/local-first). ## Create a client @@ -220,7 +220,7 @@ You can listen for any new messages (incoming or outgoing) in a conversation by A successfully received message (that makes it through the decoding and decryption without throwing) can be trusted to be authentic, i.e. that it was sent by the owner of the `message.senderAddress` wallet and that it wasn't modified in transit. The `message.sent` timestamp can be trusted to have been set by the sender. -The Stream returned by the `stream` methods is an asynchronous iterator and as such usable by a for-await-of loop. Note however that it is by its nature infinite, so any looping construct used with it will not terminate, unless the termination is explicitly initiated by calling `cancelStreamMessages()` +The Stream returned by the `stream` methods is an asynchronous iterator and as such usable by a for-await-of loop. Note however that it is by its nature infinite, so any looping construct used with it will not terminate, unless the termination is explicitly initiated by calling `cancelStreamMessages()`. ```tsx const conversation = await xmtp.conversations.newConversation( @@ -315,7 +315,7 @@ All send functions support `SendOptions` as an optional parameter. The `contentT To learn more about content types, see [Content types with XMTP](https://xmtp.org/docs/concepts/content-types). -For example, see the [Codecs](https://github.com/xmtp/xmtp-react-native/blob/main/src/lib/CodecRegistry.ts) available in `xmtp-react-native`. +For example, see the [Codecs](https://github.com/xmtp/xmtp-react-native/blob/main/src/XMTP.types.ts) available in `xmtp-react-native`. ```tsx await conversation.send({ @@ -346,7 +346,7 @@ The keys returned by `exportKeyBundle` should be treated with the utmost care as ## Enable the example app to send push notifications -Check out the `push-notifications-example` branch and follow instructions in the README +Check out the `push-notifications-example` branch and follow instructions [in the README](https://github.com/xmtp/xmtp-react-native/blob/push-notifications-example/README.md). ## 🏗 Breaking revisions @@ -376,7 +376,7 @@ XMTP provides both `production` and `dev` network environments to support the de The `production` and `dev` networks are completely separate and not interchangeable. For example, for a given blockchain account address, its XMTP identity on `dev` network is completely distinct from its XMTP identity on the `production` network, as are the messages associated with these identities. In addition, XMTP identities and messages created on the `dev` network can't be accessed from or moved to the `production` network, and vice versa. -> **Important** +> **Important** > When you [create a client](#create-a-client), it connects to the XMTP `dev` environment by default. To learn how to use the `env` parameter to set your client's network environment, see [Configure the client](#configure-the-client). The `env` parameter accepts one of three valid values: `dev`, `production`, or `local`. Here are some best practices for when to use each environment: From 05528547c66d54c378bdaa5b875b049117928e05 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Wed, 18 Oct 2023 17:30:41 -0700 Subject: [PATCH 3/5] docs: Naomi's feedback <3 --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 862261d56..7bed58d0b 100644 --- a/README.md +++ b/README.md @@ -315,7 +315,11 @@ All send functions support `SendOptions` as an optional parameter. The `contentT To learn more about content types, see [Content types with XMTP](https://xmtp.org/docs/concepts/content-types). -For example, see the [Codecs](https://github.com/xmtp/xmtp-react-native/blob/main/src/XMTP.types.ts) available in `xmtp-react-native`. +The SDK preregisters the following codecs: + +- For [Android](https://github.com/xmtp/xmtp-react-native/blob/main/android/src/main/java/expo/modules/xmtpreactnativesdk/wrappers/ContentJson.kt#L43-L53), using these [source codecs](https://github.com/xmtp/xmtp-android/tree/main/library/src/main/java/org/xmtp/android/library/codecs). + +- For [iOS](https://github.com/xmtp/xmtp-react-native/blob/main/ios/Wrappers/DecodedMessageWrapper.swift#L35-L48), using these [source codecs](https://github.com/xmtp/xmtp-ios/tree/main/Sources/XMTP/Codecs). ```tsx await conversation.send({ From 7b7aa90f01f175ebb99f8850bee8184b49ba526f Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Wed, 18 Oct 2023 17:34:25 -0700 Subject: [PATCH 4/5] docs: add ref doc link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7bed58d0b..831bae3f5 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ To learn more about XMTP and get answers to frequently asked questions, see [XMT ## Reference docs -You can use the `xmtp-js` client SDK [reference documentation](https://xmtp-js.pages.dev/modules) as reference documentation for this SDK. +Access the `xmtp-react-native` client SDK [reference documentation](https://xmtp.github.io/xmtp-react-native/). ## Example app From c00a5e692f6e4952602c638675f62c31b1c425fd Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Mon, 23 Oct 2023 16:01:28 -0700 Subject: [PATCH 5/5] docs: update ref docs url --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 831bae3f5..5696ec4ba 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ To learn more about XMTP and get answers to frequently asked questions, see [XMT ## Reference docs -Access the `xmtp-react-native` client SDK [reference documentation](https://xmtp.github.io/xmtp-react-native/). +Access the `xmtp-react-native` client SDK [reference documentation](https://xmtp.github.io/xmtp-react-native/modules.html). ## Example app