Usage

Initialization

The init method initializes the Bridgefy SDK with an API key. The delegate parameter is required and should be an object that conforms to the BridgefyDelegate protocol. The verboseLogging parameter is optional and enables more detailed logging if set to true.

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

do {
      bridgefy = try Bridgefy(withApiKey: apiKey,
                              delegate: BridgefyDelegate,
                              verboseLogging: Bool)
} catch {
    // Handle the error
}

The string apiKey represents a valid API key. An Internet connection is needed, at least for the first time to validate the license. The delegate is the class that will implement all the delegate methods from the BridgefySDK.

Start

After initializing the SDK, you should call the start() function to have the SDK's services running.

bridgefy.start(withUserId: UUID?,
               andPropagationProfile: PropagationProfile)

The optional UUID userId is the id that the SDK will use to identify the user. If a nil value is passed, the SDK will randomly assign a UUID. The propagationProfile value is the profile the SDK will use to propagate messages through the mesh.

Once the service is started, the following delegate function is called:

func bridgefyDidStart(with userId: UUID)

The userId is the id used to identify the current user/device in the BridgefySDK.

In the case an error occurs while starting the BridgefySDK, the following delegate function is called:

func bridgefyDidFailToStart(with error: BridgefyError)

Propagation Profiles

enum PropagationProfile {
    case standard
    case highDensityNetwork
    case sparseNetwork
    case longReach
    case shortReach
}

Profile	Hops limit	TTL(s)	Sharing Time	Maximum Propagation	Tracklist 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.

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

Stop

To stop the SDK, use the following function:

  func stop()

After the service is stopped, the following delegate function is called:

func bridgefyDidStop()

Destroy Session

Call this method when you want to terminate the current Bridgefy session and destroy all related data:

  func destroySession()

After the session is destroy, the following delegate function is called:

func bridgefyDidDestroySession()

Nearby peer detection

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

func bridgefyDidConnect(with userId: UUID)

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

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

func bridgefyDidDisconnect(from userId: UUID)

userId: Identifier of the disconnected user.

Sending data

The following method is used to send data using a transmission mode. This method returns a UUID to identify the message sent.

do {
    let messageID = try bridgefy.send(Data,
                                 using: TransmissionMode)
            
} catch {
    // Handle the error
}

messageId: Unique identifier related to the message.

If the message was successfully sent, the following delegate method is called:

func bridgefyDidSendMessage(with messageId: UUID)

messageId: The unique identifier of the message sent.

Note: It Is important to notice that the call of this delegate method doesn't mean the message was delivered. This is due to the nature of how the messages travel through the mesh network created by the BridgefySDK. The ONLY scenario where you can assume that the message was delivered is when it was sent using the p2p transmission mode; otherwise, it only means that there's no pre-validation error, and the SDK will start propagating the message.

If an error occurs while sending a message, the following delegate method is called:

func bridgefyDidFailSendingMessage(with messageId: UUID,
                                   withError error: BridgefyError)

Receiving Data

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

func bridgefyDidReceiveData(_ data: Data,
                            with messageId: UUID,
                            using transmissionMode: TransmissionMode)

data: Received data.

messageId: The id of the message that was received

transmissionMode: The transmission mode used to propagate a message

Transmission Modes:

public enum TransmissionMode {
    case p2p(userId: UUID)
    case mesh(userId: UUID)
    case broadcast(senderId: UUID)
}

The mode used to propagate a message through nearby devices:

p2p(userId: UUID): Sends the message data only when the receiver is in range; otherwise an error is reported. mesh(userId: UUID)): Sends the message data using the mesh created by the SDK. It doesn’t need the receiver to be in range. broadcast(senderId: UUID): Sends a packet using mesh without a defined receiver. The packet is broadcast to all nearby users that are or aren’t in range.

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 by taking advantage of other nearby peers; these receive the package, hold it, and forward it to other peers trying to find the receiver.