2. Attributes API

Manage dynamic, changing state during app usage to provide context to the LFM.

Context is Everything

While Session data remains completely static, Attributes describe the rapidly changing runtime context of your application.

When the Large Feelings Model (LFM) processes raw kinematic telemetry (like rapid screen tapping), it desperately needs to know what the user is experiencing to label the behavior correctly. Rapid tapping while playing an embedded mini-game indicates high engagement. Rapid tapping on a frozen payment processing screen indicates severe frustration. The Attributes API provides this context.

How it works under the hood

The Nx10 backend architecture requires a complete snapshot of the current state whenever context changes, rather than incremental diffs.

To save you from manually constructing and passing a massive dictionary every time a single variable updates, the Nx10 iOS SDK maintains a local state cache. You simply tell the SDK what specifically changed using our convenience methods, and the SDK automatically merges it, batches it, and syncs the full state snapshot to the cloud in the background.

The API Surface

The SDK exposes several Quality of Life (QoL) methods to make managing this state as frictionless as possible within standard UIViewController or SwiftUI lifecycles.

1. Setting Individual Attributes

Use setAttribute to add a new key or overwrite an existing one. This is ideal for isolated state changes, like a user toggling a filter or completing a step in a form.

CheckoutViewController.swift

import UIKit
import Nx10Core

class CheckoutViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        // The SDK updates its local cache and fires a snapshot to the backend
        Nx10Core.shared.attributes.setAttribute(key: "currentScreen", value: "checkout_step_1")
    }

    @IBAction func paymentMethodSelected(_ sender: Any) {
        Nx10Core.shared.attributes.setAttribute(key: "paymentMethod", value: "apple_pay")
    }
}

2. Bulk Updates

When a user loads into a deeply nested view, dozens of contextual parameters might change at once. Use setAttributes to merge a dictionary of values into the current state. The SDK will update its cache and dispatch a single network request for the bulk update.

WorkoutTrackerView.swift

import SwiftUI
import Nx10Core

struct WorkoutTrackerView: View {
    var body: some View {
        VStack {
            Text("Workout in Progress")
        }
        .onAppear {
            let workoutContext: [String: Any] =[
                "currentScreen": "active_workout",
                "workoutType": "HIIT",
                "difficultySetting": "hard",
                "isMusicPlaying": true
            ]
            Nx10Core.shared.attributes.setAttributes(workoutContext)
        }
    }
}

3. Removing Attributes

Sometimes state becomes irrelevant. For example, if a user leaves the checkout flow, keeping paymentMethod in the state dictionary might confuse the telemetry tagging. Use removeAttribute to strip specific keys out of the active state.

CheckoutViewController.swift

import Nx10Core

class CheckoutViewController: UIViewController {
    
    @IBAction func cancelCheckout() {
        Nx10Core.shared.attributes.setAttribute(key: "currentScreen", value: "cart")
        
        // Clean up temporary variables specific to this flow
        Nx10Core.shared.attributes.removeAttribute("paymentMethod")
        Nx10Core.shared.attributes.removeAttribute("discountCodeApplied")
        
        self.dismiss(animated: true)
    }
}

4. Clearing State

When transitioning back to a Root View Controller or Home Screen, you usually want to wipe the slate completely clean to avoid deep-link variables bleeding into main menu telemetry. clearAttributes instantly empties the local cache.

HomeViewController.swift

import Nx10Core

class HomeViewController: UIViewController {

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        
        // Wipes all active attributes
        Nx10Core.shared.attributes.clearAttributes()
        
        // Set the new baseline state for the home screen
        Nx10Core.shared.attributes.setAttribute(key: "currentScreen", value: "home")
    }
}

Data Constraints

Supported Value Types

String (e.g., "checkout", "settings")
Int / Int64 (e.g., 5, 1000)
Float / Double (e.g., 98.5)
Bool (true, false)

Unsupported Types

Like the Session initialization, the Attributes API enforces a flat structure.

No nested Dictionary or structs
No Array types
No custom classes