Quickstart for the React Native XMTP client SDK

The React Native XMTP client SDK (xmtp-react-native) provides a package you can use to build with XMTP in a React Native or Expo app.

Build with this SDK to provide messaging between blockchain wallet addresses, including DMs, notifications, announcements, and more.

Important

This SDK is in Pre-Preview status and ready for you to start experimenting with. However, we do not recommend using Pre-Preview 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 (xmtp-js). Here's a list of features and issues we're working on.

Is there a feature you need that's not on the list? Please open an issue.

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!

Example app

The xmtp-react-native repo also provides an example app that you can use to experiment with and explore implementation details.

Follow the React Native guide to set up a CLI environment.

To use the example app, run:

cd example
npm install --force
npm run [ios or android]

Install in a managed Expo project

npx expo prebuild

Install in a bare React Native project

For bare React Native projects, install and configure the expo package before continuing.

Add the package to your npm dependencies

npm i @xmtp/react-native-sdk

Configure for iOS

npx pod-install

We're working on testing the end-to-end installation and will provide more platform-specific configuration details.

Configure for Android

Your app must use Android minSdkVersion = 22 to work with the xmtp-react-native SDK.

We're working on testing the end-to-end installation and will provide more platform-specific configuration details.

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 (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 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 repo.

2. Complete the steps in Local Setup.

3. Get the FCM project ID and FCM credentials you created earlier and run:

     YOURFCMJSON=`cat YOURFIREBASEADMINFROMSTEP4.json` 

   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.

Update the iOS example app to send push notifications

Coming soon.