Local Resources
Bundle images, videos, and other media in your app for use in paywalls, enabling faster load times and offline support.
Local resources let your paywalls load bundled assets directly from the device instead of fetching them over the network. This is useful for hero images, onboarding videos, and other media that should appear immediately even when the connection is slow.
Local resources require iOS SDK v4.13.0+.
Registering local resources
Choose a stable resource ID for each asset you want to serve locally. That same ID is what you'll select in the paywall editor when configuring image or video components.
On iOS, local resources are configured on SuperwallOptions.localResources before calling configure().
let options = SuperwallOptions()
options.localResources = [
"hero-image": Bundle.main.url(forResource: "hero", withExtension: "png")!,
"onboarding-video": Bundle.main.url(forResource: "welcome", withExtension: "mp4")!
]
Superwall.configure(
apiKey: "pk_your_api_key",
options: options
)Set localResources before calling configure(). Resources added later will not be available to
paywalls that already loaded.
Supported source types
iOS maps each resource ID to a local file URL:
| Type | Use for |
|---|---|
URL | Files in your app bundle or sandbox that can be loaded directly from disk |
Choosing resource IDs
Resource IDs are the contract between your app and the paywall editor. A few guidelines:
- Use stable, descriptive names like
"hero-image"and"onboarding-video". - Keep the casing consistent.
"Hero-Image"and"hero-image"are different IDs. - If you rename an ID, update any paywalls that reference it.
Referencing local resources in a paywall
In the paywall editor, set a local resource on an image or video component and select the resource ID you registered in the SDK. You can still provide a remote URL as a fallback.
Under the hood, paywalls load these resources through swlocal:// URLs. For example:
<video src="swlocal://onboarding-video" autoplay muted playsinline></video>If the SDK cannot resolve a local resource, the paywall can fall back to the remote URL configured in the editor.
Debugging
If a resource ID does not appear in the editor or fails to load:
- Make sure the app is running a compatible SDK version.
- Confirm the resource ID in your paywall exactly matches the key you registered in the SDK.
- Open a paywall on a test device after configuring local resources so the editor can discover recently used IDs.
- Keep a remote fallback URL on critical media so older builds still render correctly.
Related
localResources: SDK reference for the property on supported platforms.- Paywall Editor: Local Resources: How to assign local resource IDs in the dashboard.
How is this guide?