iOS - Access Filemap Assets

New in Mobile SDK iOS 26.5.0

Filemap asset access through ModuleDataSource is available starting in 26.5.0.

Modules can download and decode filemap assets hosted on the CDN using the ModuleDataSource protocol. This is useful for retrieving dynamic configuration or content files that are managed outside of the app bundle.

Download Raw Data

Fetching a Filemap Asset as Data

do {
    let data = try await moduleDataSource?.getFilemapAsset(
        forKey: "resources/my-config.json",
        forceCache: false
    )
    // Process raw data
} catch {
    // Handle FilemapAssetError
}

Download and Decode

Use the generic variant to download and decode a filemap asset directly to a Decodable type:

Fetching and Decoding a Filemap Asset

struct MyConfig: Decodable {
    let featureEnabled: Bool
    let version: String
}

do {
    let config: MyConfig = try await moduleDataSource?.getFilemapAsset(
        forKey: "resources/my-config.json",
        forceCache: false
    )
    // Use decoded config
} catch {
    // Handle FilemapAssetError
}

Cache-Only Access

Set forceCache: true to return only previously cached data without making a network request. This is useful when you need a fast, offline-safe read and can tolerate stale data.

Cache-Only Filemap Access

do {
    let data = try await moduleDataSource?.getFilemapAsset(
        forKey: "resources/my-config.json",
        forceCache: true
    )
} catch FilemapAssetError.cacheUnavailable {
    // No cached data exists for this key
}

Error Handling

The FilemapAssetError enum provides specific error cases:

Case	Description
downloadFailed(statusCode:)	Network request failed (includes HTTP status code)
cacheUnavailable	forceCache was true but no cached data exists
decodingFailed(underlying:)	Data was retrieved but could not be decoded
invalidAssetPath(_:)	The asset key could not form a valid URL

Handling Specific Errors

do {
    let data = try await moduleDataSource?.getFilemapAsset(
        forKey: "resources/footer-links.json",
        forceCache: false
    )
} catch FilemapAssetError.downloadFailed(let statusCode) {
    print("Download failed with status: \(statusCode)")
} catch FilemapAssetError.cacheUnavailable {
    print("No cached version available")
} catch FilemapAssetError.decodingFailed(let underlying) {
    print("Decoding error: \(underlying)")
} catch FilemapAssetError.invalidAssetPath(let path) {
    print("Invalid path: \(path)")
}

Available Asset Keys

The complete list of available filemap asset keys can be obtained by calling the /Q2Config endpoint on your environment.