Local Resources

Bundle images, videos, and other media in your app for use in paywalls, enabling faster load times and offline support.

Local resources allow you to register media files bundled in your app (images, videos, audio) so that paywalls can reference them by ID instead of loading them from a remote URL. The SDK serves these files directly from disk, which means instant loading and no network dependency.

Local resources require iOS SDK v4.13.0+. Make sure you're on a compatible version before using this feature.

Registering local resources

Set the localResources property on SuperwallOptions before calling configure(). Each entry maps a resource ID (a string you choose) to a local file URL:

let options = SuperwallOptions()
options.localResources = [
  "hero-image": Bundle.main.url(forResource: "hero", withExtension: "png")!,
  "onboarding-video": Bundle.main.url(forResource: "onboarding", withExtension: "mp4")!
]

Superwall.configure(apiKey: "pk_your_api_key", options: options)

The resource IDs you choose here are the same IDs you'll select in the paywall editor when configuring an image or video component.

Local resources must be set before calling configure(). Resources added after configuration will not be available for paywalls that have already loaded.

Supported file types

The SDK supports a wide range of media formats:

Category	Formats
Images	PNG, JPEG, GIF, WebP, SVG, HEIC, HEIF, AVIF, BMP, TIFF
Videos	MP4, MOV, WebM, AVI, HEVC/H.265

Choosing resource IDs

Resource IDs are simple strings that act as the key between your app and the paywall editor. A few tips:

Use descriptive names like "hero-image" or "onboarding-video" rather than "img1".
Keep them stable. If you change a resource ID, you'll need to update any paywalls that reference it in the editor.
They're case-sensitive. "Hero-Image" and "hero-image" are different IDs.

Fallback behavior

In the paywall editor, you can set both a local resource and a remote URL on the same image or video component. If the local file can't be loaded (for example, the resource ID isn't registered or the file is missing from the bundle), the paywall automatically falls back to the remote URL. This ensures paywalls still work on older SDK versions or if a resource is accidentally removed from the app bundle.

Debugging

The SDK includes a built-in debug view for verifying your local resources are set up correctly. It shows each registered resource ID, its file path, and a preview of the content.

If a resource isn't showing up in the paywall editor dropdown, make sure your test device has opened a paywall (or otherwise triggered a device attributes event) after configuring localResources. The editor only shows resource IDs reported in the last 7 days.

Example: Onboarding paywall with a bundled video

A common use case is bundling an onboarding video so it loads instantly the first time a user sees your paywall:

// In your app's initialization
let options = SuperwallOptions()
options.localResources = [
  "onboarding-video": Bundle.main.url(forResource: "welcome", withExtension: "mp4")!,
  "app-logo": Bundle.main.url(forResource: "logo", withExtension: "png")!
]

Superwall.configure(apiKey: "pk_your_api_key", options: options)

Then in the paywall editor, select "onboarding-video" as the local resource for your video component and "app-logo" for the logo image. Set remote URLs as fallbacks for both.

SuperwallOptions: Full configuration reference.
Paywall Editor: Local Resources: How to use local resources in the paywall editor.