Core Concepts

Understand the architecture of the Vio Kotlin SDK before diving into advanced usage.

Modular Design

The SDK is organized into independent modules that you can mix and match based on your app’s needs:

VioCore          ← Required: configuration, models, base managers
VioUI            ← Compose UI components (products, checkout, cart)
VioEngagementSystem  ← Polls, contests logic and repositories
VioEngagementUI  ← Engagement Compose overlays and cards
VioLiveShow      ← Live streaming models and managers
VioLiveUI        ← Live streaming Compose components

Configuration & VioSDK

VioSDK is the primary entry point for the SDK. It simplifies synchronization between local configuration and remote settings fetched from the Vio Dashboard.

// Initialize once in Application.onCreate
VioSDK.configure(context = this, apiKey = "...")
 
// Set content context (e.g. broadcast ID)
VioSDK.setContent(contentId = "match-123")

The SDK uses a single-source-of-truth pattern where CampaignManager coordinates all real-time interactions based on the active campaign discovered for the current content.

Reactive State with StateFlow

The SDK uses Kotlin’s StateFlow for reactive state management, making it easy to observe changes in your Compose UI:

val configState by VioConfiguration.shared.state.collectAsState()

This means SDK configuration changes (e.g. theme, market availability) automatically update all rendered components.

Coroutines

All network operations are suspend functions and should be called from a CoroutineScope or a ViewModel:

class ProductViewModel : ViewModel() {
    fun loadProducts(channelId: String) {
        viewModelScope.launch {
            // SDK calls are suspend functions
            val products = productRepository.getProducts(channelId)
        }
    }
}

Environments

The SDK supports three environments controlled by VioEnvironment:

The graphQLUrl is automatically derived from the base URL.

WebSocket & Real-time Parity

The Kotlin SDK maintains full parity with the Swift SDK’s WebSocket implementation. This ensures:

• Instant Synchronization: Polls, contests, and sponsor moments appear in real-time.
• Context Awareness: The connection automatically resyncs when calling setContent(id) to stay in sync with the current broadcast.
• Race Condition Handling: Internal logic handles late-arriving messages and ensures the UI always reflects the current server state.

Sponsor Moments

Sponsor Moments are real-time triggers that control the visibility of UI components like VioSponsorMomentCard. When a moment is triggered via WebSocket:

1. CampaignManager receives the event.
2. The relevant component state is updated.
3. The UI reactively shows or hides the promotional content.

Error Handling

Configuration errors are thrown as ConfigurationError sealed class instances:

sealed class ConfigurationError : IllegalStateException {
    object NotConfigured  // SDK not initialized
    object MissingApiKey  // apiKey is blank
    object InvalidEnvironment
    object InvalidTheme
    class FileNotFound(val fileName: String)
    object InvalidJSON
    object InvalidPlist
}

Market Availability

The SDK supports multi-market scenarios. You can restrict access based on the user’s country:

// Call after fetching available markets from your backend
VioConfiguration.setMarketAvailability(
    available = true,
    userCountryCode = "NO",
    availableMarkets = availableMarketsFromApi
)

The language is automatically resolved from the country code (e.g. NO → no, DE → de).