Developer guide

Bring your app to SwiftDeck.

Choose a simple URL action or a connected SDK integration.

This guide shows you how to add SwiftDeck integration to your own app and define controls that people can place in SwiftDeck to operate its features.

Choose the Integration that suits your needs

Choose your app language

The page shows only the instructions for your choice.

SDK Free Integration

The lite path is useful for simple, one-shot commands such as opening a document or choosing a tool. Your app handles a custom URL that a SwiftDeck user adds as a URL Scheme Action. It needs no SwiftDeckKit package, developer account or persistent connection, but it cannot publish controls automatically or provide live state and rich interactions. For those features, .

Choose and register a URL scheme

In your Mac app target, open Info → URL Types. Add a unique URL scheme owned by your app. The example below uses example-hello; replace it with your own scheme in both the app and SwiftDeck.

A URL scheme is a public entry point. Other apps may open it, and a scheme name alone does not identify the sender. Only expose actions that are safe to invoke this way.

Handle the incoming URL in your app

Connect this helper to the URL-open callback your app already uses. With SwiftUI, call it from onOpenURL; with an AppKit lifecycle, call it from your app delegate's URL-open handler. The helper accepts only the exact route shown here and rejects unexpected query data.

Example URL handlerSwift

import AppKit

// Call this from your app's existing URL-open callback.
func handleSwiftDeckURL(_ url: URL) {
    guard url.scheme == "example-hello",
          url.host == "swiftdeck",
          url.path == "/hello",
          URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems?.isEmpty != false
    else { return }

    let alert = NSAlert()
    alert.messageText = "Hello World"
    alert.runModal()
}

The alert is sample app behaviour. Replace it with your own safe command once the route works.

Test the URL before opening SwiftDeck

Build and run your Mac app. Paste this command into Terminal on the same Mac. Replace the example scheme if you chose a different one.

Open the test URLTerminal

open "example-hello://swiftdeck/hello"

The Hello World alert should appear. If it does not, check the URL Types entry and that your app's URL-open callback calls the helper.

Create the action in SwiftDeck

In SwiftDeck, add a button to a deck and choose URL Scheme Action. Enter example-hello://swiftdeck/hello, then set a clear title such as Hello World. Press it on your connected device while the Mac app is installed.

Lite actions are configured by the SwiftDeck user. Registering a URL scheme does not automatically publish a control in App Controls or provide live state, completion feedback, sliders or lists. for those features.