How to integrate a Photo Editor into your iOS App

Felix — Wed, 10 Jul 2019 00:00:00 GMT

In this tutorial, we’re going to add a photo editor to an iOS app using the CreativeEditor SDK. We’re going to use Xcode, Swift Package Manager, and the Photo Editor starter kit, a complete Xcode project that opens straight into the editor. By the end we’ll have an app whose editor opens on the kit’s blank page, with crop, filters and a share sheet already wired up, and a dock button that pulls a photo in off the device.

Because the starter kit is an entire Xcode project, there are two ways in. We can clone it and run it as it stands, which is the quickest way to see the editor working. Or we can copy its files into an app we already have. We’ll do both, starting with the clone.

What we need

A Mac with a recent version of Xcode, and an app with a deployment target of iOS 16.0 or later. The IMGLYUI-swift package declares // swift-tools-version:6.3.1 on the first line of its manifest, which is the line Swift Package Manager reads before anything else, so an older toolchain refuses the package outright. Swift 6.3.1 is the floor.

We don’t need a license key to follow along. Without one, the editor runs in evaluation mode with a watermark.

Running the starter kit

The Photo Editor starter kit lives in its own repository, with a branch for the SDK release we want. That is 1.82.1 here:

git clone -b v1.82.1 https://github.com/imgly/starterkit-photo-editor-ios.git
cd starterkit-photo-editor-ios

Now we open the project in Xcode, select a simulator, and press Run. Xcode resolves the Swift package dependencies on the first build, and that first resolve takes a while: the engine framework is a compressed download of about 390 MB. The archive carries simulator and device slices along with debug symbols, so a shipped app doesn’t grow by anything like that much, and the Bundle Size guide has the numbers. It’s still a long first coffee.

The cloned project’s Secrets.swift ships an empty license key, which is what puts it in evaluation mode. That’s enough for everything below.

Adding the editor to an existing app

Most of the time we’re not starting from an empty project. Two steps get the editor into an app we already have: the package, then the starter kit files.

In Xcode, we use File > Add Package Dependencies... and paste this URL into the search field at the top right of the modal:

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

When the package information appears, we select version 1.82.1 and add the IMGLYEditor product to our app target. There’s also an umbrella library, IMGLYUI, which pulls in every UI module at once and is the convenient thing to add while we’re exploring. Before releasing, cut it back to the libraries we actually import, which helps conserve app space.

The second step is the starter kit itself. Its files live in our own codebase, which is what makes the editor’s behavior something we can edit. We pull the StarterKit folder out of the v1.82.1 branch archive:

repo="starterkit-photo-editor-ios"
version="1.82.1"
curl -L "https://codeload.github.com/imgly/${repo}/tar.gz/refs/heads/v${version}" | tar -xz --strip-components=1 "${repo}-${version}/StarterKit"

Then we drag the StarterKit folder into the Xcode project. Here it’s essential that “Copy items if needed” is checked, so the files are copied into the project instead of just being referenced, and that they’re added to the app target. photo-ui-empty.png comes along with them and has to show up under Copy Bundle Resources, because the editor looks it up in the app bundle at startup.

Here’s what the folder holds:

StarterKit/
├── PhotoEditorStarterKit.swift         # SwiftUI view that launches the editor
├── PhotoEditorConfiguration.swift      # Editor configuration (callbacks + UI components)
├── photo-ui-empty.png                  # The image the editor opens with
├── callbacks/
│   ├── OnCreate+Photo.swift            # Editor initialization logic
│   ├── OnExport+Photo.swift            # Export flow and handling
│   ├── OnLoaded+Photo.swift            # Post-load setup (crop behavior)
│   └── OnChanged+Photo.swift           # Edit mode change handling
├── components/
│   ├── CanvasMenu+Photo.swift          # Canvas menu configuration
│   ├── Dock+Photo.swift                # Dock configuration
│   ├── InspectorBar+Photo.swift        # Inspector bar configuration
│   └── NavigationBar+Photo.swift       # Navigation bar configuration
└── examples/
    └── ExampleForceCrop.swift          # Optional force-crop example

Putting the editor on screen

PhotoEditorStarterKit.swift is the view that shows the editor. It builds an EngineSettings value and hands it to the Editor view together with a configuration:

import IMGLYEditor
import IMGLYEngine
import SwiftUI

struct PhotoEditorStarterKit: View {
  // Provide `EngineSettings` with your license and an optional userId.
  let settings = EngineSettings(
    license: nil, // Use nil for evaluation mode with watermark
    userID: "<your unique user id>",
  )

  var body: some View {
    Editor(settings)
      .imgly.configuration {
        PhotoEditorConfiguration()
      }
  }
}

As the file ships, that license: line reads secrets.licenseKey. Secrets.swift lives in StarterKit-PhotoEditor/, which the extract above leaves behind, so the clone compiles and the copied folder does not until the line is replaced. Passing nil puts the editor in evaluation mode, which is where we want it until we’ve got a key of our own. The userID is optional and ties an editing session to our own user record, which is what makes the monthly active user count come out right when the same person uses the app on two devices.

The editor puts its close button in the leading slot of a navigation bar, and undo, redo, a preview toggle and export in the trailing one, so the view has to sit inside a navigation container. The sample app’s ContentView does that and nothing else:

import SwiftUI

struct ContentView: View {
  var body: some View {
    NavigationStack {
      PhotoEditorStarterKit()
    }
  }
}

That file sits in StarterKit-PhotoEditor/, so it is not one of the twelve we extracted. In an app we already have, we write the same wrapper ourselves, or push PhotoEditorStarterKit() onto a navigation stack that is already on screen.

Without a NavigationStack or some other navigation context somewhere above it, the toolbars come up missing.

The tools the user gets

The dock along the bottom of the canvas is the list of tools, and it’s spelled out in components/Dock+Photo.swift:

builder.items { _ in
  Dock.Buttons.adjustments() // Image adjustments
  Dock.Buttons.filter() // Filters
  Dock.Buttons.effect() // Effects
  Dock.Buttons.blur() // Blur
  Dock.Buttons.crop() // Crop tool
  Dock.Buttons.textLibrary() // Text tools
  Dock.Buttons.shapesLibrary() // Shapes
  Dock.Buttons.stickersLibrary() // Stickers
}

items sets the contents of the dock, replacing whatever was there, so this list is the dock. Delete a line and that tool’s gone. Adding a line is how the photo roll button arrives further down.

The image the editor opens

callbacks/OnCreate+Photo.swift decides what’s on the canvas when the editor appears. Its defaultCreateScene callback loads the blank placeholder PNG that travels with the kit:

#if SWIFT_PACKAGE
  let bundle = Bundle.module
#else
  let bundle = Bundle(for: PhotoEditorConfiguration.self)
#endif
let imageURL = bundle.url(forResource: "photo-ui-empty", withExtension: "png")!
try await engine.scene.create(fromImage: imageURL)

The Bundle(for:) branch is the one that applies when the kit has been added to an app target the way we did it; Bundle.module applies when it compiles inside a Swift package. To open one of our users’ own photos, point engine.scene.create(fromImage:) at that file instead.

A second callback in the same file, defaultLoadAssetSources, registers the device’s photo library as an asset source. That registration is its last line:

try engine.asset.addSource(PhotoRollAssetSource(engine: engine))

Registering the source is half the job. Nothing in the editor opens the library until the dock carries a button for it, and the eight buttons we printed above don’t include one, so we add a ninth line to Dock+Photo.swift:

Dock.Buttons.photoRoll() // Photos from the device

A tap on that button now opens the system photos picker, and the chosen photo goes into the design. The picker runs out of process and the user grants access one selection at a time, so no permission prompt of ours appears and the kit needs no privacy keys in Info.plist.

To let people browse their whole library inside the editor, register the source with full library access. The button stays as it is, and only the mode changes:

try engine.asset.addSource(PhotoRollAssetSource(engine: engine, mode: .fullLibraryAccess))

That mode reads the library directly, so iOS does want a usage description. Without this key in Info.plist, the system terminates the app the first time the library is touched:

<key>NSPhotoLibraryUsageDescription</key>
<string>Grant access to your photo library to add photos and videos to your designs.</string>

Getting the picture back out

callbacks/OnExport+Photo.swift runs when the user taps export. It writes a PNG to a temporary file and hands that file to the system share sheet:

guard let scene = try engine.scene.get() else {
  throw EditorError("No scene was found.")
}
let data = try await engine.block.export(scene, mimeType: .png) { engine in
  try engine.scene.getPages().forEach {
    try engine.block.setScopeEnabled($0, key: "layer/visibility", enabled: true)
    try engine.block.setVisible($0, visible: true)
  }
}
let url = FileManager.default.temporaryDirectory.appendingPathComponent("Export", conformingTo: .png)
try data.write(to: url, options: [.atomic])
eventHandler.send(.shareFile(url))

This is the callback to rewrite when the edited photo should go somewhere else, up to our own backend, say, or straight back to the screen the user came from. By that point the encoded image is already in data, so a share sheet is only one of the options.

Before we ship it

Three things are still sitting on their development defaults.

The first is the license. Passing nil keeps the watermark, so a production build needs a real key in EngineSettings. Trial keys are available through the CE.SDK iOS guide.

The second is the userID, which still reads <your unique user id>. That string compiles, so every user of a shipped app reports the same id. Pass a stable identifier for the signed-in user, or leave the parameter out, since it defaults to nil.

The third is where the assets come from. Filters, typefaces, stickers, and shapes load from https://cdn.img.ly/packages/imgly/cesdk-swift/1.82.1/assets, the default baseURL, and that CDN is for development. Self-hosting is required for a production deployment: download the asset archive, put it somewhere we control, and pass our own baseURL to EngineSettings. Serve Assets From Your Server walks through the hosting side. That’s also the moment to drop the sources we never load, which shortens the editor’s startup.

Where to go next

The Photo Editor starter kit guide documents the parts of the kit we skipped, and the iOS documentation covers the rest of the platform. The same editor goes into a website and into an Android app.

Swift Package Manager – IMG.LY Blog