Serve Assets From Your Server

import Foundation
import IMGLYEngine

private let serveAssetsDefaultSourceIDs = [
  "ly.img.sticker",
  "ly.img.vector.shape",
  "ly.img.filter",
  "ly.img.color.palette",
  "ly.img.effect",
  "ly.img.blur",
  "ly.img.typeface",
  "ly.img.crop.presets",
  "ly.img.page.presets",
  "ly.img.text",
  "ly.img.text.styles",
  "ly.img.text.curves",
  "ly.img.text.components",
]

private let serveAssetsDemoSourceIDs = [
  "ly.img.image",
  "ly.img.video",
  "ly.img.audio",
  "ly.img.templates",
  "ly.img.templates.premium",
]

@MainActor
func serveAssets(engine: Engine) async throws {
  let baseURL = try engine.guidesBaseURL

  for id in serveAssetsDefaultSourceIDs {
    _ = try await engine.asset.addLocalAssetSourceFromJSON(
      baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
    )
  }

  try engine.editor.setSettingString("basePath", value: baseURL.absoluteString)
}

// Register the sample content sources (images, videos, audio, templates). These
// ship in the same archive and load the same way — replace them with your own
// content sources in production.
@MainActor
func serveAssetsSampleContent(engine: Engine) async throws {
  let baseURL = try engine.guidesBaseURL

  for id in serveAssetsDemoSourceIDs {
    _ = try await engine.asset.addLocalAssetSourceFromJSON(
      baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
    )
  }
}

// Variations showing where to host the assets. These are compile-only
// demonstrations — the test runs `serveAssets` against the bundled assets.

@MainActor
func serveAssetsFromRemoteServer(engine: Engine) async throws {
  let baseURL = URL(string: "https://cdn.your.custom.domain/assets")!
  for id in serveAssetsDefaultSourceIDs {
    _ = try await engine.asset.addLocalAssetSourceFromJSON(
      baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
    )
  }
}

@MainActor
func serveAssetsFromAppBundle(engine: Engine) async throws {
  guard let baseURL = Bundle.main.url(forResource: "IMGLYAssets", withExtension: "bundle") else {
    return
  }
  for id in serveAssetsDefaultSourceIDs {
    _ = try await engine.asset.addLocalAssetSourceFromJSON(
      baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
    )
  }
}

The engine serves all assets from the IMG.LY CDN by default, which is convenient while you are getting started. For production you should serve them from your own location so your app doesn’t depend on the IMG.LY CDN at runtime — it gives you control over performance and availability and keeps you within your own compliance boundary.

Download the Assets#

The assets are versioned alongside the SDK, so always download the archive that matches your engine version — content from a different version may not be compatible. Asset versions are platform-specific: the iOS and Android archives are usually aligned, but the web SDK can move at a different pace, so download from the cesdk-swift path that matches your engine version.

Or download and extract it from the command line:

curl -O https://cdn.img.ly/packages/imgly/cesdk-swift/1.78.0/imgly-assets.zip
unzip imgly-assets.zip -d IMGLYAssets.bundle

The archive contains one ly.img.* directory per asset source, the fonts/ and emoji/ directories, and thumbnail directories such as ly.img.animation that serve preview images for the engine’s built-in animation presets. Those thumbnail directories have no content.json and aren’t registered as asset sources — keep them at your baseURL so the previews resolve. To ship the assets inside your app, add the extracted .bundle folder to your app target — this produces a nested Bundle your app can resolve at runtime. Alternatively, upload the extracted folders to your own server or CDN to serve them remotely.

Register the Default Asset Sources#

Each asset source is described by a content.json manifest. Register a source by pointing engine.asset.addLocalAssetSourceFromJSON(_:) at its manifest URL; the engine resolves the asset files relative to that URL. Loop over the default source IDs and load each manifest from a single baseURL that points at your asset location:

private let serveAssetsDefaultSourceIDs = [
  "ly.img.sticker",
  "ly.img.vector.shape",
  "ly.img.filter",
  "ly.img.color.palette",
  "ly.img.effect",
  "ly.img.blur",
  "ly.img.typeface",
  "ly.img.crop.presets",
  "ly.img.page.presets",
  "ly.img.text",
  "ly.img.text.styles",
  "ly.img.text.curves",
  "ly.img.text.components",
]

for id in serveAssetsDefaultSourceIDs {
  _ = try await engine.asset.addLocalAssetSourceFromJSON(
    baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
  )
}

baseURL points at your hosting location — set it to your own server or app bundle as shown below. The default sources are:

• ly.img.sticker — Stickers.
• ly.img.vector.shape — Shapes and arrows.
• ly.img.filter — LUT and duotone color filters.
• ly.img.color.palette — Default color palette.
• ly.img.effect — Effects.
• ly.img.blur — Blurs.
• ly.img.typeface — Typefaces.
• ly.img.crop.presets — Crop presets.
• ly.img.page.presets — Page resize presets.
• ly.img.text, ly.img.text.styles, ly.img.text.curves — Text style presets.
• ly.img.text.components — Text design component library.

Register Sample Content Sources#

The archive also ships sample content — images, videos, audio, and templates — registered the same way. These are meant for development and prototyping; replace them with your own content sources in production.

private let serveAssetsDemoSourceIDs = [
  "ly.img.image",
  "ly.img.video",
  "ly.img.audio",
  "ly.img.templates",
  "ly.img.templates.premium",
]

for id in serveAssetsDemoSourceIDs {
  _ = try await engine.asset.addLocalAssetSourceFromJSON(
    baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
  )
}

The sample content sources are:

• ly.img.image — Sample images.
• ly.img.video — Sample videos.
• ly.img.audio — Sample audio.
• ly.img.templates — Sample design templates.
• ly.img.templates.premium — Premium sample design templates.

Point the Base URL at Your Assets#

Set baseURL to wherever you copied the assets, then register the sources exactly as above.

For assets on your own server or CDN, use an absolute URL pointing at the folder that contains the per-source directories:

let baseURL = URL(string: "https://cdn.your.custom.domain/assets")!
for id in serveAssetsDefaultSourceIDs {
  _ = try await engine.asset.addLocalAssetSourceFromJSON(
    baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
  )
}

For assets bundled with your app, resolve the .bundle URL you added to your app target:

guard let baseURL = Bundle.main.url(forResource: "IMGLYAssets", withExtension: "bundle") else {
  return
}
for id in serveAssetsDefaultSourceIDs {
  _ = try await engine.asset.addLocalAssetSourceFromJSON(
    baseURL.appendingPathComponent(id).appendingPathComponent("content.json"),
  )
}

Customize Which Assets Load#

To register only a subset of a source’s assets, pass ID patterns to the matcher: parameter of addLocalAssetSourceFromJSON(_:matcher:). Patterns support the * wildcard, and an asset is included if it matches any pattern — for example, matcher: ["ly.img.sticker.emoji.*"] registers only the emoji stickers.

For deeper changes — curating your own collection, renaming assets, or adjusting their metadata — edit the content.json manifests directly. See the Asset Content JSON Schema guide for the manifest format.

Configure Engine-Level Assets#

The engine also loads font fallback files (for Unicode character coverage) and the emoji font separately from the asset sources. Point the basePath setting at your location so they load from there too:

try engine.editor.setSettingString("basePath", value: baseURL.absoluteString)

This setting affects:

• Font fallback files — Used when text contains characters not covered by the selected font. Located at {basePath}/fonts/font-{index}.ttf.
• Emoji font — The default emoji font (NotoColorEmoji.ttf). Located at {basePath}/emoji/NotoColorEmoji.ttf.

Both the fonts/ and emoji/ directories are included in the imgly-assets.zip download, so once the assets are at your basePath location the engine resolves them automatically.

API Reference#

Methods#

Next Steps#

• Configuration — Pass baseURL to EngineSettings so the editor initializes basePath for you before onCreate runs.
• Assets — How asset sources and assets fit together.
• Insert Shapes or Stickers — Query and apply assets from a registered source.