Usage

Start the SDK

The following code shows how to start the SDK (using your API key) and how to assign the delegate.

Android Manifest

Locate the AndroidManifest.xml file within your project. It is usually located in the "app" or "src/main" directory. Add the element as application element inside the component tag.

<manifest>

    <application>
        
        <meta-data
            android:name="com.bridgefy.sdk.API_KEY"
            android:value="..." />
        
    </application>
    
</manifest>

Bridgefy initialization

By default the SDK starts using the Standard propagation profile mode

    fun init(
        bridgefyApiKey: UUID,
        delegate: BridgefyDelegate?,
        priorityLogging: Int = Log.WARN,
    )

Parameters:

• bridgefyApiKey: (UUID) The license key registered on the Bridgefy developer site.

• delegate: (BridgefyDelegate) a delegate/listener to handle SDK activity and events.

• priorityLogging: (Int) (optional, default: Log.WARN) The logging priority level for SDK operations.

Throws: BridgefyException if there is an error during initialization

Start

Starts Bridgefy operations, allowing the SDK to participate in the Bridgefy network.

bridgefy.start(
       userId: UUID? = null,
       propagationProfile: PropagationProfile = PropagationProfile.Standard,
   )

• Parameters:

  • userId: (optional) - The ID used to identify the user in the Bridgefy network.

  • propagationProfile: PropagationProfile (optional, default: PropagationProfile.Standard) A profile that defines a series of properties and rules for the propagation of messages.

Stop

To stop it, use the following code:

/**
 * Stop bridgefy sdk operations
 *
 */
bridgefy.stop()

License

    bridgefy.licenseExpirationDate() : Result<Date?>

Description: Retrieves the expiration date of the Bridgefy license. Returns: A Result containing the expiration date as a Date object or null if the license information is not available.

    bridgefy.updateLicense()

Description: Updates the Bridgefy license, if necessary.

Bridgefy Session

Bridgefy SDK, providing various methods and properties for managing connections and secure communication.

Properties:

bridgefy.isStarted: Boolean Indicates whether the Bridgefy SDK is currently started.

Bridgefy Methods

   bridgefy.destroySession()

Description: Destroys the current session, terminating any active connections and cleaning up resources.

    bridgefy.currentUserId() : Result<UUID>

Description: Retrieves the UUID of the current Bridgefy user. Returns: A Result containing the UUID of the current user or an error message.

Nearby peer detection

The following method is invoked when a peer has established connection:

    val delegate: BridgefyDelegate = object : BridgefyDelegate {

    override fun onConnected(peerID: UUID) {
        ...
    }

}

peerID: Identifier of the user that has established a connection.

When a peer is disconnected(out of range), the following method will be invoked:

    val delegate: BridgefyDelegate = object : BridgefyDelegate {

    override fun onDisconnected(peerID: UUID) {
        ...
    }

}

peerID: Identifier of the disconnected user.

When a device is detected, notifies the list of connected users:

    val delegate: BridgefyDelegate = object : BridgefyDelegate {

    /**
     * On connected peers
     *
     * @param connectedPeers
     */
    fun onConnectedPeers(connectedPeers: List<UUID>) {
        ...
    }

}

connectedPeers: List of identifiers of the connected user.

Bridgefy method

bridgefy.connectedPeers() : Result<List<UUID>?>

Description: Retrieves a list of UUIDs representing the connected peers in the current session. Returns: A Result containing a list of UUIDs of connected peers or null if the service is not started.

Send data

The following method is used to send data using a transmission mode. This method returns the message ID (messageID) to the client.

import me.bridgefy.commons.TransmissionMode
// Bridgefy instance
val bridgefy: Bridgefy

// After start sdk, send ByteArray
val messageId = bridgefy.send(
    "Sample text!".toByteArray(Charsets.UTF_8),
    TransmissionMode.P2P(peerID)
)

messageID: Unique identifier related to the message.

Transmission Modes:

open class TransmissionMode {
    /**
     * Broadcast type propagate message on mesh network
     */
    data class Broadcast(val sender: UUID) : TransmissionMode()

    /**
     * Mesh type propagate message and find receiver on mesh network
     *
     */
    data class Mesh(val receiver: UUID) : TransmissionMode()

    /**
     * Direct type allow direct message and if receiver isn't connected,
     * the SDK change and propagate message with Mesh type
     *
     */
    data class P2P(val receiver: UUID) : TransmissionMode()
}

There are several modes for sending packets:

P2P(val receiver: String): Sends the packet only when the receiver is in range. Mesh(val receiver: String): Sends the packet using mesh to only once receiver. It doesn't need the receiver to be in range. Receiver can be in range of a third receiver located within range of both sender and receiver at the same time, or receiver can be out of range of all other nodes, but eventually come within range of a node that at some point received the packet. Mesh messages can be received my multiple nodes, but can only be read by the intended receiver. Broadcast: Sends a packet using mesh without a defined receiver. The packet is broadcast to all nearby users that are in range, who then broadcast it to all receivers that are in their range, and so on. If a user isn't in range, the packet will be delivered the next time said user comes within range of another user who did receive the packet. Broadcast messages can be read by all nodes that receive it.

If there is no error when sending the message, will be received with the message id (messageID)

    val delegate: BridgefyDelegate = object : BridgefyDelegate {
    /**
     * On send
     *
     * @param messageID
     */
    override fun onSend(messageID: UUID) {
        ...
    }

}

otherwise, the following method will be received

    val delegate: BridgefyDelegate = object : BridgefyDelegate {
     /**
     * This function is called when the message could not be sent
     *
     * @param messageID The id of the message that was tried to be sent
     * @param error Error reason.
     */
    override fun onFailToSend(messageID: UUID, error: BridgefyException) {
        ...
    }
}

Direct and Mesh transmission

Direct transmission is a mechanism used to deliver packets to a user that is nearby or visible (a connection has been detected). Mesh transmission is a mechanism used to deliver offline packets even when the receiving user isn’t nearby or visible. It can be achieved taking advantage of other nearby peers; these receive the package, hold it, and forward to other peers trying to find the receiver.

Receive Data

When a packet has been received, the following method will be invoked:

val delegate: BridgefyDelegate = object : BridgefyDelegate {
    /**
     * On receive
     *
     * @param data
     * @param messageID
     * @param transmissionMode
     */
    override fun onReceiveData(
        data: ByteArray,
        messageID: UUID,
        transmissionMode: TransmissionMode,
    ) {
        ...
    }
}

data: Received Data object messageID: Unique identifier related to the message. transmissionMode: The transmission mode used when sending the message

Propagation Profiles

/**
 * Propagation profile
 */
enum class PropagationProfile {
    Standard,
    HighDensityEnvironment,
    SparseEnvironment,
    LongReach,
    ShortReach
}

Profile	Hops limit	TTL(s)	Sharing Time	Maximum Propagation	Track list limit
Standard	100	86400 (1 d)	15000	200	50
High Density Environment	50	3600 (1 h)	10000	50	50
Sparse Environment	100	302400 (3.5 d)	10000	250	50
Long Reach	250	604800 (7 d)	15000	1000	50
Short Reach	50	1800	10000	50	50

• Hops limit: The maximum number of hops a message can get. Each time a message is forwarded, is considered a hop.

• TTL: Time to live, is the maximum amount of time a message can be propagated since its creation.

• Sharing time: The maximum amount of time a message will be kept for forwarding.

• Maximum propagation: The maximum number of times a message will be forwarded from a device.

• Track list limit: The maximum number of UUID’s stored in an array to prevent sending the message to a peer which already forwarded the message.