Deep Linking

Navigate users directly to specific content — a video, playlist, search results, or sub-channel.

Navigation State

All channel navigation is represented by BBNavigationState:

struct BBNavigationState {
    let page: String          // "main", "detail", "overview", "search"
    let clipId: String?
    let clipListId: String?
    let query: String?
    let subChannelId: String?
}

Initial Navigation State

Open the channel at a specific location:

// Open on a video detail page
BBChannelView(
    channelUrl: "https://demo.bbvms.com/ch/channel_name.json",
    initialNavigationState: BBNavigationState(
        page: "detail", clipId: "12345"
    ),
    viewModel: viewModel,
    callbacks: callbacks
)

// Open on a playlist overview
BBChannelView(
    channelUrl: "https://demo.bbvms.com/ch/channel_name.json",
    initialNavigationState: BBNavigationState(
        page: "overview", clipListId: "678"
    ),
    viewModel: viewModel,
    callbacks: callbacks
)

// Open with search results
BBChannelView(
    channelUrl: "https://demo.bbvms.com/ch/channel_name.json",
    initialNavigationState: BBNavigationState(
        page: "search", query: "highlights"
    ),
    viewModel: viewModel,
    callbacks: callbacks
)

Programmatic Navigation

After the channel is loaded, use view model methods:

// Navigate to a specific entity
viewModel.navigateToEntity(entityType: "mediaclip", entityId: "12345")
viewModel.navigateToEntity(entityType: "mediacliplist", entityId: "678")

// Search
viewModel.search("highlights")

// Navigate to a sub-channel
viewModel.navigateToSubChannel(subChannelId: "sports")

// Go back or reset
viewModel.goBack()
viewModel.navigateTo(page: "main")

warning

Programmatic navigation only works after the channel is ready. Wait for the onReady callback.

Handling Incoming Deep Links

Use SwiftUI's onOpenURL to handle deep links:

@main
struct MyApp: App {
    @StateObject private var viewModel = BBChannelViewModel()
    @State private var initialState: BBNavigationState?

    var body: some Scene {
        WindowGroup {
            BBChannelView(
                channelUrl: "https://demo.bbvms.com/ch/channel_name.json",
                initialNavigationState: initialState,
                viewModel: viewModel,
                callbacks: BBChannelCallbacks()
            )
            .onOpenURL { url in
                if let state = parseDeepLink(url) {
                    viewModel.navigateTo(
                        page: state.page,
                        clipId: state.clipId,
                        query: state.query
                    )
                }
            }
        }
    }

    func parseDeepLink(_ url: URL) -> BBNavigationState? {
        let path = url.pathComponents
        guard path.count >= 2 else { return nil }
        switch path[1] {
        case "video":
            return BBNavigationState(page: "detail", clipId: path[safe: 2])
        case "search":
            return BBNavigationState(page: "search", query: path[safe: 2])
        default:
            return nil
        }
    }
}

URL Scheme Examples

URL	Navigation State
myapp://channel	page: "main"
myapp://channel/video/12345	page: "detail", clipId: "12345"
myapp://channel/playlist/678	page: "overview", clipListId: "678"
myapp://channel/search/highlights	page: "search", query: "highlights"

Configure these in your Info.plist as URL schemes or Universal Links.