⌘K

NativeblocksManager

A singleton class responsible for managing the Nativeblocks instance and its various components. The NativeblocksManager is used to initialize, provide blocks, actions, and loggers, and manage the lifecycle, configuration, type converters, frame data, localization, and global parameters of Nativeblocks.

NativeblocksEdition

Enum that defines the available editions for Nativeblocks.
The NativeblocksEdition can either be a cloud configuration or a community-based frame configuration.

  • NativeblocksEdition.cloud(endpoint: String, apiKey: String, developmentMode: Bool):
    Cloud-based configuration with an endpoint, API key, and development mode option.

    • endpoint: The API endpoint for fetching frames/resources.
    • apiKey: The API key for authentication.
    • developmentMode: Enable development features.

  • NativeblocksEdition.community(frameData: [String: String]):
    Community-based configuration using local frame data. The frame data is a dictionary where each key is a route and each value is the corresponding frame URL or path.

    • frameData: Dictionary of route keys to frame data URLs/paths.

NativeblocksManager

A singleton-class (per name/instance) responsible for managing Nativeblocks SDK configuration and component registration.

Initialization & Instance Management

initialize

Initializes the Nativeblocks framework for a given instance name. Supports multiple named instances for different configurations.

public static func initialize(
    name: String = "default",
    edition: NativeblocksEdition
) -> NativeblocksManager

Parameters:

  • name: Unique instance identifier. Must contain only A–Z, a–z, 0–9, _ or -. Defaults to "default"
  • edition: Cloud or Community edition configuration

Returns: The initialized NativeblocksManager instance

Throws: fatalError if name contains invalid characters

Multi-Instance Example:

// Initialize multiple instances
let mainManager = NativeblocksManager.initialize(
    name: "main",
    edition: .cloud(
        endpoint: NATIVEBLOCKS_API_URL,
        apiKey: NATIVEBLOCKS_API_KEY,
        developmentMode: true
    )
)

let secondaryManager = NativeblocksManager.initialize(
    name: "secondary",
    edition: .community(frameData: [...])
)

getInstance

Gets the shared instance of NativeblocksManager by name (default: "default").

public static func getInstance(name: String = "default") -> NativeblocksManager

Throws: fatalError if not initialized

isInitialized

Checks if a NativeblocksManager instance has been initialized.

public static func isInitialized(name: String = "default") -> Bool

Returns: true if the instance has been initialized, false otherwise

Wandkit Setup

wandkit

Configures the Wandkit components for the Nativeblocks manager.

func wandkit(_ wandkit: Wandkit...) -> NativeblocksManager

Parameters:

  • wandkit: Variadic parameter for passing one or more Wandkit instances

Returns: The current instance of NativeblocksManager for method chaining

Example:

NativeblocksManager.getInstance()
    .wandkit(CustomWandkit1(), CustomWandkit2())

Block Registration

provideBlock

Provides a block for the specified block key type.

func provideBlock(blockKeyType: String, block: @escaping (BlockProps) -> any View) -> NativeblocksManager

provideFallbackBlock

Sets the fallback block to be used when no matching block is registered or available. The fallback block will be displayed in place of unsupported or unrecognized blocks.

func provideFallbackBlock(block: @escaping (String, String) -> any View) -> NativeblocksManager

Action Registration

provideAction

Provides an action for the specified action key type.

func provideAction(actionKeyType: String, action: any INativeAction) -> NativeblocksManager

provideFallbackAction

Sets the fallback action to be used when no matching action is registered. The fallback action will be executed in place of unsupported or unrecognized actions.

func provideFallbackAction(action: @escaping (String, String) -> Void) -> NativeblocksManager

Logger Registration

provideEventLogger

Provides an event logger for the specified logger type.

func provideEventLogger(loggerType: String, logger: any INativeLogger) -> NativeblocksManager

Type Converter Registration & Retrieval

provideTypeConverter

Registers a type converter for a given type.

func provideTypeConverter<T>(_ type: T.Type, converter: INativeType<T>) -> NativeblocksManager

getTypeConverter

Retrieves the type converter for a given type.

func getTypeConverter<T>(_ type: T.Type) -> INativeType<T>

Frame Data Management

getScaffold

Retrieves the scaffold for the frames asynchronously.

func getScaffold() async -> (NativeScaffoldModel?, String?)

syncFrame

Synchronizes the frame for the specified route asynchronously.

func syncFrame(route: String) async -> NativeblocksManager

Parameters:

  • route: The route of the frame to synchronize

Returns: The current instance of NativeblocksManager for method chaining

clearAllFrames

Clears all frames from the cache.

func clearAllFrames() async -> NativeblocksManager

clearFrame

Clears a specific frame from the cache.

func clearFrame(route: String) async -> NativeblocksManager

Parameters:

  • route: The route of the frame to clear

Returns: The current instance of NativeblocksManager for method chaining

Localization & Global Parameters

setLocalization

Sets the localization language for the Nativeblocks instance.

func setLocalization(languageCode: String) -> NativeblocksManager

setGlobalParameters

Sets global parameters for the Nativeblocks instance.

func setGlobalParameters(_ parameters: (String, String)...) -> NativeblocksManager

func setGlobalParameters(_ parameters: [String: String]) -> NativeblocksManager

Experiment

getExperiment

Fetches an experiment value for the given key with type-safe conversion. The method validates the server-returned variable type against the expected type and returns the default value on any error or type mismatch.

Supported types:

  • String: maps to STRING or JSON variable type
  • Int, Float, Double: map to NUMBER variable type
  • Bool: maps to BOOLEAN variable type
func getExperiment<T>(
    key: String,
    defaultValue: T,
    cacheTTL: TimeInterval? = 86400
) async -> T

Parameters:

  • key: The experiment key to fetch
  • defaultValue: The default value to return if the experiment is not found or on error. This also determines the expected return type
  • cacheTTL: Optional time-to-live for the cached experiment value in seconds. Defaults to 24 hours (86400 seconds). Pass 0 for no caching (always fetch fresh), or nil for no expiration

Returns: The experiment value converted to the appropriate type, or the default value on error

Examples:

// Use default cache (24 hours)
let showNewUI = await getExperiment(key: "show_new_ui", defaultValue: false)

// No cache - always fetch fresh
let criticalFlag = await getExperiment(key: "payment_enabled", defaultValue: false, cacheTTL: 0)

// Custom cache TTL (1 hour)
let feature = await getExperiment(key: "feature_flag", defaultValue: true, cacheTTL: 3600)

// Different types
let maxRetries = await getExperiment(key: "max_retries", defaultValue: 3)
let apiEndpoint = await getExperiment(key: "api_url", defaultValue: "https://api.default.com")

Cleanup & Destroy

destroy

Destroys the NativeblocksManager instance and releases all associated resources.

func destroy()

NativeblocksFrame

SwiftUI view for rendering a Nativeblocks frame. Supports multi-instance rendering by specifying the instance name.

struct NativeblocksFrame: View {
    var instance: String = "default"
    var route: String
    var routeArguments: [String: String]
    var loading: () -> AnyView
    var error: (String) -> AnyView
    var body: some View
}

Parameters:

  • instance: The name of the NativeblocksManager instance to use. Defaults to "default"
  • route: The route path of the frame to render
  • routeArguments: Dictionary of route arguments to pass to the frame
  • loading: Closure that returns an AnyView to show while the frame is loading
  • error: Closure that receives an error message and returns an AnyView to display

Example:

// Using default instance
NativeblocksFrame(
    route: "/home",
    routeArguments: ["userId": "123"],
    loading: { AnyView(NativeblocksLoading()) },
    error: { message in AnyView(NativeblocksError(message: message)) }
)

// Using named instance
NativeblocksFrame(
    instance: "secondary",
    route: "/settings",
    routeArguments: [:],
    loading: { AnyView(ProgressView()) },
    error: { message in AnyView(Text("Error: \(message)")) }
)

NativeblocksLoading

SwiftUI view for rendering a loading indicator.

struct NativeblocksLoading: View {
    var body: some View
}

NativeblocksError

SwiftUI view for rendering error messages.

struct NativeblocksError: View {
    let message: String
    var body: some View
}

NativeblocksResourceManager

Handles resources such as font families.

provideFontFamily

Registers a custom font family by name.

func provideFontFamily(fontName: String, fontFamily: FontFamily) -> NativeblocksResourceManager

NativeScaffoldModel

Represents the scaffold model for Nativeblocks, containing metadata about frames and their routes.

  • frames: List of frame route models ([NativeFrameRouteModel]).

NativeFrameRouteModel

Represents a frame route model, which defines a specific UI element and its associated metadata.

  • id: Unique identifier (String?)
  • name: Display name (String?)
  • type: Frame type (FrameTypeModel?)
  • route: Route path (String?)
  • isStarter: Is starter frame (Bool?)
  • routeArguments: List of route arguments ([NativeRouteArgumentsModel]?)

NativeRouteArgumentsModel

Represents an argument for a route.

  • name: Argument name (String?)

FrameTypeModel

Enum of supported frame types:

  • frame (FRAME)
  • bottomSheet (BOTTOM_SHEET)
  • dialog (DIALOG)