Search…
Manage Relay Postboxes
Provides the essentials to give your users their postbox.
Postboxes are a fundamental component of the Relay SDK. Postboxes are a store of peer based messages to your user. These postboxes can be provisioned to receive messages from the user's peers.
Provisioning a relay postbox is a simple one-step process, as seen below.
Create a Relay Postbox
Your user can create a new postbox by calling the
createPostbox API with a valid unique identifier. This unique identifier should be saved in consuming apps, as it is required for all other relay API methods. Additionally, a Sudo
ownershipProofToken must be provided to the API, this can be obtained via the SudoProfiles getOwnershipProof API using an audience of sudoplatform.relay.postbox.The input postbox identifier must be a valid version 4 UUID.
iOS
Android
To create a postbox, the following routine is used:
createPostbox(withConnectionId:ownershipProofToken:).
The first property,
withConnectionId is non-optional and expects a valid v4 UUID. ownershipProofToken is a token attesting the ownership of the Sudo by the user.
An example implementation of creating a postbox is:
1
let connectionId = UUID().uuidString
2
let ownershipProofToken = // Generate token
3
4
do {
5
try await relayClient.createPostbox(withConnectionId: connectionId, ownershipProofToken: ownershipProofToken)
6
} catch {
7
// Handle error
8
}
Copied!
createPostbox does not return anything, but an error will be thrown if the postbox creation was unsuccessful. If an error occurs, the error.localizedDescription can be presented to the user to notify them as to what caused the error.A postbox is created by using the
createPostbox method as shown below:1
// val ownershipProofToken: String
2
// A valid v4 UUID.
3
val connectionId: String = UUID.randomUUID().toString()
4
5
launch {
6
try {
7
withContext(Dispatchers.IO) {
8
relayClient.createPostbox(connectionId, ownershipProofToken)
9
}
10
} catch (e: SudoDIRelayClient.DIRelayException) {
11
// Handle/notify user of exception
12
}
13
}
Copied!
The call of
createPostbox does not return anything, but an exception will be thrown if the postbox creation was unsuccessful. If an exception occurs, the e.localizedMessage can be presented to the user to notify them as to what caused the exception.Deleting a Relay Postbox
A postbox can be deleted from the Relay SDK using the
deletePostbox API.By deleting the postbox, the user's postbox and all stored messages will be deleted; the postbox will no longer be usable.
iOS
Android
To delete a postbox, the following routine is used:
deletePostbox(withConnectionId:).
An example implementation is as follows:
1
// connectionId: previously created v4 UUID
2
3
do {
4
try await relayClient.deletePostbox(withConnectionId: connectionId)
5
} catch {
6
// Handle error
7
}
Copied!
The deletion call will return nothing on success, or throw an error upon failure.
A postbox is deleted by using the
deletePostbox method as shown below:1
// val connectionId: String // Postbox identifier.
2
launch {
3
try {
4
withContext(Dispatchers.IO) {
5
relayClient.deletePostbox(connectionId)
6
}
7
} catch (e: SudoDIRelayClient.DIRelayException) {
8
// Handle/notify user of exception
9
}
10
}
Copied!
The call of
deletePostbox does not return anything, but an exception will be thrown if the postbox deletion was unsuccessful. If an exception occurs, the e.localizedMessage can be presented to the user to notify them as to what caused the exception.As deleting an entire postbox may take some time, a subscription can be set up to notify your user of when the deletion has been completed.
Subscribing to Postbox Deletion
Your user may wish to do other things while the deletion of the postbox occurs. Your user can subscribe to receive updates about the status of the postbox deletion. Doing so lets them be notified when the deletion completes. The API allows you to start and stop receiving updates.
iOS
Android
Below is an example usage of
subscribeToPostboxDeleted(withConnectionId:).1
// connectionId: previously created ID
2
3
do {
4
let token = try await relayClient.subscribeToPostboxDeleted(withConnectionId: connectionId) { result in
5
switch result {
6
case .success(let status):
7
// Handle deletion status
8
case .failure(let error):
9
// Handle error/ present error to user
10
}
11
}
12
13
} catch {
14
// Handle error
15
}
Copied!
To cancel the subscription, simply call:
1
token.cancel()
Copied!
To subscribe to the postbox deletion update, use the
subscribeToRelayEvents method. You must pass an identifier of the subscription and an instance of a class that implements the DIRelayEventSubscriber interface. This class will be notified of incoming messages, postbox deletion request updates, and any changes in the status of the subscription.Setting Up A Subscription
To setup the subscription call the
subscribeToRelayEvents method as so:1
// val connectionId: String // Postbox identifier.
2
val subscriber = object : DIRelayEventSubscriber {
3
override fun messageIncoming(message: RelayMessage) {
4
// Handle incoming message.
5
}
6
7
override fun postBoxDeleted(update: PostboxDeletionResult) {
8
// Handle postbox deleted update.
9
}
10
11
override fun connectionStatusChanged(state: DIRelayEventSubscriber.ConnectionState) {
12
// Handle changes in the state of the subscription connection
13
}
14
}
15
16
launch {
17
try {
18
withContext(Dispatchers.IO) {
19
relayClient.subscribeToRelayEvents(
20
connectionId,
21
subscriber
22
)
23
}
24
} catch (e: SudoDIRelayClient.DIRelayException) {
25
// Handle/notify user of exception
26
}
27
}
Copied!
There is also an extension function that allows you to pass lambdas instead of an object that implements the
DIRelayEventSubscriber interface.1
// val connectionId: String // Postbox identifier.
2
launch {
3
try {
4
withContext(Dispatchers.IO) {
5
relayClient.subscribeToRelayEvents(
6
connectionId,
7
onConnectionChange = { state: DIRelayEventSubscriber.ConnectionState ->
8
// Handle changes in the state of the subscription connection.
9
},
10
onMessageIncoming = { message: RelayMessage ->
11
// Handle incoming message.
12
},
13
onPostboxDeleted = { update: PostboxDeletionResult ->
14
// Handle postbox deleted update.
15
}
16
)
17
}
18
} catch (e: SudoDIRelayClient.DIRelayException) {
19
// Handle/notify user of exception
20
}
21
}
Copied!
Cancelling A Subscription
To cancel a subscription, use the
unsubscribeToRelayEvents or unsubscribeAll method. For example:1
// val connectionId: String // Postbox identifier.
2
launch {
3
try {
4
withContext(Dispatchers.IO) {
5
relayClient.unsubscribeToRelayEvents(connectionId)
6
// or
7
relayClient.unsubscribeAll()
8
}
9
} catch (e: SudoDIRelayClient.DIRelayException) {
10
// Handle/notify user of exception
11
}
12
}
Copied!
This will ensure that the subscription is cancelled and system resources are freed.
In the Android Relay SDK, both postbox deletion and incoming message events are handled in the same subscription method.
Retrieving Postboxes
To provide the ability for a user to access previously created postboxes for their Sudo, the
listPostboxesForSudoId or listPostboxes API can be used.iOS
Android
To retrieve a list of postboxes for a given Sudo, the following routine is used:
listPostboxes(withSudoId:).
An example implementation is as follows:
1
// sudoId: String
2
3
do {
4
let postboxes = try await relayClient.listPostboxes(withSudoId: sudoId)
5
} catch {
6
// Handle error
7
}
Copied!
Postboxes for your user's Sudo can be listed using the
listPostboxesForSudoId method as shown below:1
// val sudoId: String // a User's Sudo ID
2
3
launch {
4
try {
5
val postboxes: List<Postbox> = withContext(Dispatchers.IO) {
6
relayClient.listPostboxesForSudoId(sudoId)
7
}
8
} catch (e: SudoDIRelayClient.DIRelayException) {
9
// Handle/notify user of exception
10
}
11
}
Copied!
Last modified 5d ago