You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`xmtp-android` provides a Kotlin implementation of an XMTP message API client for use with Android apps.
6
6
7
7
Use `xmtp-android` to build with XMTP to send messages between blockchain accounts, including DMs, notifications, announcements, and more.
8
8
9
-
This SDK is in **Developer Preview** status and ready for you to start building with.
9
+
To keep up with the latest SDK developments, see the [Issues tab](https://github.com/xmtp/xmtp-android/issues) in this repo.
10
10
11
-
However, we do **not** recommend using Developer Preview software in production apps. Software in this status may change based on feedback.
11
+
To learn more about XMTP and get answers to frequently asked questions, see the [XMTP documentation](https://xmtp.org/docs).
12
12
13
-
Specifically, while push notifications should work with the current SDK, we are working on providing push notifications in the example app. We are also working on providing performance optimizations in the example app. These updates to the example app may inform changes to the SDK.
14
-
15
-
Follow along in the [tracking issue](https://github.com/xmtp/xmtp-android/issues/1) for updates.
Use the [XMTP Android quickstart app](https://github.com/xmtp/xmtp-android/tree/main/example) as a tool to start building an app with XMTP. This basic messaging app has an intentionally unopinionated UI to help make it easier for you to build with.
20
18
21
-
## Example app
19
+
To learn about example app push notifications, see [Enable the quickstart app to send push notifications](library/src/main/java/org/xmtp/android/library/push/README.md).
22
20
23
-
For a basic demonstration of the core concepts and capabilities of the `xmtp-android` client SDK, see the [Example app project](https://github.com/xmtp/xmtp-android/tree/main/example). This is currently a work in progress.
21
+
## Reference docs
24
22
25
-
To learn about example app push notifications, see [Enable the example app to send push notifications](library/src/main/java/org/xmtp/android/library/push/README.md).
23
+
> **View the reference**
24
+
> Access the [Kotin client SDK reference documentation](https://xmtp.github.io/xmtp-android/).
26
25
27
26
## Install from Maven Central
28
27
29
-
You can find the latest package version on [Maven Central](https://central.sonatype.com/artifact/org.xmtp/android/0.0.5/versions)
28
+
You can find the latest package version on [Maven Central](https://central.sonatype.com/artifact/org.xmtp/android/0.0.5/versions).
> If you are building a production-grade app, be sure to use an architecture that includes a local cache backed by an XMTP SDK.
63
+
64
+
To learn more, see [Use a local cache](https://xmtp.org/docs/tutorials/performance#use-a-local-cache).
65
+
60
66
## Create a client
61
67
62
68
A client is created with `Client().create(account: SigningKey): Client` that requires passing in an object capable of creating signatures on your behalf. The client will request a signature in two cases:
63
69
64
70
1. To sign the newly generated key bundle. This happens only the very first time when a key bundle is not found in storage.
65
-
2. To sign a random salt used to encrypt the key bundle in storage. This happens every time the client is started, including the very first time).
71
+
2. To sign a random salt used to encrypt the key bundle in storage. This happens every time the client is started, including the very first time.
66
72
67
73
> **Note**
68
-
> The client connects to the XMTP `dev` environment by default. [Use `ClientOptions`](#configuring-the-client) to change this and other parameters of the network connection.
74
+
> The client connects to the XMTP `dev` environment by default. [Use `ClientOptions`](#configure-the-client) to change this and other parameters of the network connection.
69
75
70
76
```kotlin
71
77
// Create the client with a `SigningKey` from your app
@@ -139,9 +145,7 @@ for (conversation in allConversations) {
139
145
}
140
146
```
141
147
142
-
These conversations include all conversations for a user **regardless of which app created the conversation.** This functionality provides the concept of an [interoperable inbox](https://xmtp.org/docs/dev-concepts/interoperable-inbox), which enables a user to access all of their conversations in any app built with XMTP.
143
-
144
-
You might choose to provide an additional filtered view of conversations. To learn more, see [Handle multiple conversations with the same blockchain address](#handle-multiple-conversations-with-the-same-blockchain-address) and [Filter conversations using conversation IDs and metadata](https://xmtp.org/docs/client-sdk/javascript/tutorials/filter-conversations).
148
+
These conversations include all conversations for a user **regardless of which app created the conversation.** This functionality provides the concept of an [interoperable inbox](https://xmtp.org/docs/concepts/interoperable-inbox), which enables a user to access all of their conversations in any app built with XMTP.
145
149
146
150
### Listen for new conversations
147
151
@@ -165,16 +169,15 @@ val newConversation = client.conversations.newConversation("0x3F11b27F323b62B159
165
169
166
170
### Send messages
167
171
168
-
To be able to send a message, the recipient must have already created a client at least once and consequently advertised their key bundle on the network. Messages are addressed using account addresses. The message payload must be a plain string.
169
-
170
-
> **Note**
171
-
> Other types of content are currently not supported.
172
+
To be able to send a message, the recipient must have already created a client at least once and consequently advertised their key bundle on the network. Messages are addressed using account addresses. In this example, the message payload is a plain text string.
172
173
173
174
```kotlin
174
175
val conversation = client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897")
175
176
conversation.send(text ="Hello world")
176
177
```
177
178
179
+
To learn how to send other types of content, see [Handle different content types](#handle-different-types-of-content).
180
+
178
181
### List messages in a conversation
179
182
180
183
You can receive the complete message history in a conversation by calling `conversation.messages()`
### Handle multiple conversations with the same blockchain address
220
-
221
-
With XMTP, you can have multiple ongoing conversations with the same blockchain address. For example, you might want to have a conversation scoped to your particular app, or even a conversation scoped to a particular item in your app.
222
-
223
-
To accomplish this, you can pass a context with a `conversationId` when you are creating a conversation. We recommend conversation IDs start with a domain, to help avoid unwanted collisions between your app and other apps on the XMTP network.
224
-
225
-
```kotlin
226
-
// Start a scoped conversation with ID mydomain.xyz/foo
227
-
val conversation1 = client.conversations.newConversation(
All the send functions support SendOptions as an optional parameter. The contentType option allows specifying different types of content than the default simple string, which is identified with content type identifier ContentTypeText. 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. See XIP-5 for more details on codecs and content types.
257
+
All the send functions support `SendOptions` as an optional parameter. The `contentType` option allows specifying different types of content than the default simple string, which is identified with content type identifier `ContentTypeText`.
284
258
285
-
Codecs and content types may be proposed as interoperable standards through XRCs. If there is a concern that the recipient may not be able to handle a non-standard content type, the sender can use the contentFallback option to provide a string that describes the content being sent. If the recipient fails to decode the original content, the fallback will replace it and can be used to inform the recipient what the original content was.
259
+
To learn more about content types, see [Content types with XMTP](https://xmtp.org/docs/concepts/content-types).
260
+
261
+
Support for other types of content can be added by registering additional `ContentCodec`s 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.
286
262
287
263
```kotlin
288
264
// Assuming we've loaded a fictional NumberCodec that can be used to encode numbers,
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.
273
+
274
+
> **Caution**
275
+
> 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.
297
276
298
-
<!--provide kotlin details and code sample. showing swift for context of the kind of info you might want to provide. =)-->
277
+
#### Handle custom content types
278
+
279
+
Beyond this, custom codecs and content types may be proposed as interoperable standards through XRCs. To learn more about the custom content type proposal process, see [XIP-5](https://github.com/xmtp/XIPs/blob/main/XIPs/xip-5-message-content-types.md).
280
+
281
+
### Compression
299
282
300
283
Message content can be optionally compressed using the compression option. The value of the option is the name of the compression algorithm to use. Currently supported are gzip and deflate. Compression is applied to the bytes produced by the content codec.
As a performance optimization, you may want to persist the list of conversations in your application outside of the SDK to speed up the first call to `client.conversations.list()`.
311
294
312
-
The exported conversation list contains encryption keys for any V2 conversations included in the list. As such, you should treat it with the same care that you treat [private keys](#manually-handle-private-key-storage).
295
+
The exported conversation list contains encryption keys for any V2 conversations included in the list. As such, you should treat it with the same care that you treat private keys.
313
296
314
297
You can get a JSON serializable list of conversations by calling:
0 commit comments