Direct Device-to-Device Sharing in Rork Max Apps — The Local Network Permission Trap That Makes MultipeerConnectivity Fail Silently

The first wall: Local Network permission fails silently

MultipeerConnectivity uses Bonjour (mDNS) internally to find peers. Since iOS 14, any Bonjour-based communication requires the Local Network permission, and this is the single biggest gotcha because it only kicks in on real devices.

The structure of the trap looks like this:

• If you forget the usage string (NSLocalNetworkUsageDescription) in Info.plist, the permission dialog never appears at all. With no dialog, nothing is ever denied or granted, and the browser finds nothing.
• If you forget to list the Bonjour service types in NSBonjourServices, you can advertise but the discovery side is filtered out — again, silently nothing.
• Once the user picks "Don't Allow," your app can never re-prompt. From then on the browser returns empty forever.

None of these throw an exception or fire an error callback, so it looks like "the code is right but it won't run." First, confirm these two entries are in your Info.plist. The NSBonjourServices values register both _servicetype._tcp and _servicetype._udp, matching the serviceType you actually use.

<!-- Info.plist -->
<key>NSLocalNetworkUsageDescription</key>
<string>We look for devices on your local network to share presets directly with people nearby.</string>
<key>NSBonjourServices</key>
<array>
  <string>_dolicoshare._tcp</string>
  <string>_dolicoshare._udp</string>
</array>

The framework won't explicitly tell you whether permission was denied. In practice I treat it as a rule: "if nothing shows up after searching for a while, suspect the permission or Info.plist." To make isolation possible, log each of discovery start, invitation send, and state change to os.Logger so you can see at a glance what is not happening on device.

import os
 
let shareLog = Logger(subsystem: "net.rorklab.share", category: "multipeer")
// usage: shareLog.info("browser: found peer \(peerID.displayName, privacy: .public)")

The way Local Network permission works is continuous with offline detection and reconnection design. Monitoring the network state itself is covered in designing offline detection and reconnection in Rork Max.

A working minimal implementation: a thin wrapper around MCSession

Because the responsibilities split three ways, the raw API tends to scatter callbacks. So we fold advertiser, browser, and session into one class and expose state to SwiftUI through @Published. Here is a minimal setup that works as-is.

import MultipeerConnectivity
import os
 
@MainActor
final class NearbyShareManager: NSObject, ObservableObject {
    // serviceType: 1-15 chars, lowercase letters/digits/hyphen only (see the traps below)
    private let serviceType = "dolicoshare"
    private let myPeerID = MCPeerID(displayName: UUID().uuidString.prefix(8).description)
 
    private lazy var session: MCSession = {
        let s = MCSession(peer: myPeerID, securityIdentity: nil,
                          encryptionPreference: .required)
        s.delegate = self
        return s
    }()
 
    private lazy var advertiser = MCNearbyServiceAdvertiser(
        peer: myPeerID, discoveryInfo: nil, serviceType: serviceType)
    private lazy var browser = MCNearbyServiceBrowser(
        peer: myPeerID, serviceType: serviceType)
 
    private let log = Logger(subsystem: "net.rorklab.share", category: "multipeer")
 
    @Published private(set) var foundPeers: [MCPeerID] = []
    @Published private(set) var connectedPeers: [MCPeerID] = []
 
    func start() {
        advertiser.delegate = self
        browser.delegate = self
        advertiser.startAdvertisingPeer()
        browser.startBrowsingForPeers()
        log.info("start advertising and browsing")
    }
 
    func stop() {
        advertiser.stopAdvertisingPeer()
        browser.stopBrowsingForPeers()
        session.disconnect()
        foundPeers.removeAll()
        connectedPeers.removeAll()
    }
 
    func invite(_ peerID: MCPeerID) {
        // Invite the peer into our session. Too short a timeout drops connections.
        browser.invitePeer(peerID, to: session, withContext: nil, timeout: 20)
    }
 
    func send(_ data: Data) {
        guard !session.connectedPeers.isEmpty else { return }
        do {
            try session.send(data, toPeers: session.connectedPeers, with: .reliable)
        } catch {
            log.error("send failed: \(error.localizedDescription, privacy: .public)")
        }
    }
}

Implement the delegates split across four protocols. By reflecting the state transitions into @Published, the SwiftUI side can list them plainly.

extension NearbyShareManager: MCNearbyServiceBrowserDelegate {
    nonisolated func browser(_ browser: MCNearbyServiceBrowser,
                             foundPeer peerID: MCPeerID,
                             withDiscoveryInfo info: [String: String]?) {
        Task { @MainActor in
            if !foundPeers.contains(peerID) { foundPeers.append(peerID) }
            log.info("found peer \(peerID.displayName, privacy: .public)")
        }
    }
    nonisolated func browser(_ browser: MCNearbyServiceBrowser,
                             lostPeer peerID: MCPeerID) {
        Task { @MainActor in foundPeers.removeAll { $0 == peerID } }
    }
}
 
extension NearbyShareManager: MCNearbyServiceAdvertiserDelegate {
    nonisolated func advertiser(_ advertiser: MCNearbyServiceAdvertiser,
                                didReceiveInvitationFromPeer peerID: MCPeerID,
                                withContext context: Data?,
                                invitationHandler: @escaping (Bool, MCSession?) -> Void) {
        // Ideally you show a confirmation prompt here. The minimal setup auto-accepts.
        Task { @MainActor in invitationHandler(true, session) }
    }
}
 
extension NearbyShareManager: MCSessionDelegate {
    nonisolated func session(_ session: MCSession, peer peerID: MCPeerID,
                             didChange state: MCSessionState) {
        Task { @MainActor in
            switch state {
            case .connected:
                if !connectedPeers.contains(peerID) { connectedPeers.append(peerID) }
            case .notConnected:
                connectedPeers.removeAll { $0 == peerID }
            case .connecting:
                break
            @unknown default:
                break
            }
        }
    }
    nonisolated func session(_ session: MCSession, didReceive data: Data,
                             fromPeer peerID: MCPeerID) {
        // Handle received data (e.g. decode image Data)
    }
    nonisolated func session(_ s: MCSession, didReceive stream: InputStream,
                             withName n: String, fromPeer p: MCPeerID) {}
    nonisolated func session(_ s: MCSession, didStartReceivingResourceWithName n: String,
                             fromPeer p: MCPeerID, with progress: Progress) {}
    nonisolated func session(_ s: MCSession, didFinishReceivingResourceWithName n: String,
                             fromPeer p: MCPeerID, at localURL: URL?,
                             withError error: Error?) {}
}

I set encryptionPreference to .required. Nearby or not, there's no reason to put plaintext on the air. Setting it to .none makes connections faster, but I recommend defaulting to .required.

Dropping it into Rork Max's generated code with a minimal diff

Because Rork Max generates native Swift, you can keep the UI and the broad data model as they are. What the generated code usually can't finish, though, are the "only bite you on device and in App Store review" areas: permissions, Info.plist, and background constraints. Splitting the integration into three steps keeps it from getting confusing.

1. Fill in Info.plist by hand: add NSLocalNetworkUsageDescription and NSBonjourServices. These never appear in generated code, so you always add them yourself.
2. Hold NearbyShareManager as a @StateObject on the screen: from the generated share button's action, just call start() and invite(), and push the networking logic into the wrapper.
3. Match the send/receive data format to your existing model: turn presets and images into Data via Codable and pass them to send(_:). On the receiving side, decode back to the original type in didReceive data:.

The general approach to shaping generated Swift for production is broken out in refactoring Rork Max's generated Swift for production, which pairs well here for how to land the diff.

The SwiftUI side stays surprisingly short.

struct NearbyShareView: View {
    @StateObject private var share = NearbyShareManager()
 
    var body: some View {
        List {
            Section("Connected") {
                ForEach(share.connectedPeers, id: \.self) { Text($0.displayName) }
            }
            Section("Nearby devices") {
                ForEach(share.foundPeers, id: \.self) { peer in
                    Button(peer.displayName) { share.invite(peer) }
                }
            }
        }
        .onAppear { share.start() }
        .onDisappear { share.stop() }
    }
}

Traps that catch you in practice, and how to handle them

Here are the spots most likely to snag you on device, roughly in the order I hit them.

Break the serviceType naming rule and everything dies. serviceType must be 1-15 characters, lowercase letters, digits, and hyphens only, and cannot start or end with a hyphen. Include an uppercase letter or underscore like Dolico_Share and you get a silent no-op, not an exception. Keep it short with lowercase ASCII and hyphens only.

MCPeerID displayName is capped at 63 bytes. Pass an overly long name or a device name with emoji as-is and it gets rejected. I use a safe value like the first few characters of a UUID, and manage the display name separately inside the app.

Don't shrink the invitation timeout too far. Trim invitePeer's timeout down to a few seconds and it gives up before connecting whenever reception is slightly weak. Keeping it around 20 seconds visibly cut my dropped connections.

It isn't kept alive in the background. MultipeerConnectivity assumes the app is in the foreground. Close or lock the screen mid-share and the session drops. Even just adding a line to the UI — "keep this in front until the transfer finishes" — makes the experience steadier.

Don't trust the simulator's results. Nearby discovery can only be verified correctly on two real devices. The failure I opened with started right here. A list appearing in the simulator does not guarantee real-device Bonjour behavior. Always test on hardware.

What to check before production

Nearby sharing, when it works, has a genuine satisfaction to it: no server, and you just hand the data to the person in front of you. At the same time, most of the failures hide in the dull places — permissions and Info.plist — and they happen silently, which is what makes them tricky.

As your next step, put a build with NSLocalNetworkUsageDescription and NSBonjourServices on two real devices, and just check whether the Local Network permission dialog actually appears on first launch. Once that passes, the wrapper in this article should run nearly as-is. I hope it helps anyone stuck at the same spot narrow it down.