Search Docs
Loading...
Skip to content

Quickstart

This guide walks you through integrating the CE.SDK Engine into a brand-new macOS app. On macOS you host the engine’s canvas inside your own SwiftUI or AppKit view and drive it with the engine APIs — there is no prebuilt editor UI to drop in.

5 mins
estimated time
GitHub

Requirements#

To work with the SDK, you’ll need:

  • A Mac running a recent version of Xcode
  • A deployment target of macOS 12 or later
  • A valid CE.SDK license key (Get a free trial)

Creating a new Xcode Project#

1. Launch Xcode and use the File menu to select New -> Project....

2. Select the macOS tab, highlight the App template, and click Next.

3. Enter a product name and an organization identifier, and set the language to Swift. For the interface, choose SwiftUI or, for an AppKit app, Storyboard — which scaffolds an NSViewController (ViewController.swift) to build on. Match the hosting path you’ll follow in the Host the Canvas section below, then click Next.

4. Choose a location to save the project and click Create.

Add the CE.SDK Swift package#

1. With your Xcode project open, use the File menu to select Add Package Dependencies...

2. Copy the following package URL and paste it into the search field at the top right of the dialog:

https://github.com/imgly/IMGLYEngine-swift

3. Once the package resolves, click Add Package.

4. When Xcode presents the list of libraries, add the IMGLYEngine library to your app target, then click Add Package.

Host the Canvas#

The engine renders into a Metal view. Initialize the engine with try await Engine(...), then place its canvas in your view hierarchy. Pick the framework your app uses:

SwiftUI
AppKit

Import the SDK:

import IMGLYEngine
import SwiftUI

Canvas(engine:) adopts the engine’s Metal view into your SwiftUI hierarchy. The .metal render context is the default, so Engine(license:userID:) creates its own view. Start the engine in onAppear, hold it in @State, and seed a scene so the canvas shows content on launch:

struct IntegrateWithSwiftUI: View {
  @State private var engine: Engine?


  var body: some View {
    Group {
      if let engine {
        Canvas(engine: engine)
      } else {
        ProgressView("Starting the engine…")
      }
    }
    .onAppear {
      guard engine == nil else { return }
      Task {
        do {
          let engine = try await Engine(
            license: secrets.licenseKey, // pass nil for evaluation mode with watermark
            userID: "<your unique user id>",
          )
          let scene = try engine.scene.create()
          let page = try engine.block.create(.page)
          try engine.block.setWidth(page, value: 800)
          try engine.block.setHeight(page, value: 600)
          try engine.block.appendChild(to: scene, child: page)


          let text = try engine.block.create(.text)
          try engine.block.setString(text, property: "text/text", value: "Hello, CE.SDK!")
          try engine.block.setPositionX(text, value: 80)
          try engine.block.setPositionY(text, value: 260)
          try engine.block.setWidth(text, value: 640)
          try engine.block.appendChild(to: page, child: text)


          try await engine.scene.zoom(to: page, paddingLeft: 40, paddingTop: 40, paddingRight: 40, paddingBottom: 40)
          self.engine = engine
        } catch {
          print("Engine setup failed: \(error)")
        }
      }
    }
  }
}

Present IntegrateWithSwiftUI as your app’s root view: in the App file Xcode generated, replace ContentView() inside the WindowGroup with IntegrateWithSwiftUI().

The example reads the license from a small secrets helper the guides repository ships (source); replace secrets.licenseKey with your own CE.SDK license key string, or pass nil for evaluation mode with a watermark. Because Engine is @MainActor-isolated, the compiler enforces that every engine call runs on the main thread.

Now Build and Run. The engine renders your page with the “Hello, CE.SDK!” text on the canvas.

Using Your App#

The canvas displays the scene, but macOS has no built-in toolbar or panels — that part is yours to build. Pair the canvas with your own controls, add and configure blocks through the same engine.block and engine.scene APIs, and export the result with engine.block.export(_:mimeType:). The Build Your Own UI guide walks through wiring a toolbar, a property inspector, and export into a complete custom editor.

Troubleshooting#

If you run into issues, here are some common problems and solutions. For additional help, visit our support page.

Package Won’t Add to Your macOS Target#

Make sure you added the IMGLYEngine-swift package. The IMGLYUI-swift package (the prebuilt editor and camera) builds on iOS only and cannot link against a macOS target.

Import Errors: ‘Engine’ or ‘Canvas’ Not Found#

Every Swift file that uses the engine needs import IMGLYEngine before the first line of code. Confirm the IMGLYEngine library is listed under Frameworks, Libraries, and Embedded Content on your target’s General tab.

License Key Error at Runtime#

Double-check that the license value passed to Engine(license:userID:) is the exact key with proper capitalization. If you don’t have a license, register for a free trial to get a demonstration license. Pass nil to run in evaluation mode with a watermark.

Canvas Is Blank#

Canvas(engine:) and the .metalView(view:) context both require an engine created with a Metal context. Confirm engine.scene.create() ran and that you appended a page to the scene — an empty scene has nothing to render.

Next Steps#

  • Build Your Own UI — Wire the engine to your own SwiftUI or AppKit controls to build a complete custom editor.
  • Engine Interface — Explore the engine’s six API namespaces for scenes, blocks, assets, and more.
  • What is CE.SDK? — Understand the SDK’s architecture and where the engine fits.