warning

The iOS SwiftUI SDK is currently in preview and does not include a full feature set. Major features supported.

iOS SwiftUI SDK (24.3.0)

Introduction

info

This guide only includes features introduced in the SwiftUI SDK. For a full SDK guide of the latest stable version, see iOS SDK guide.

The Atomic iOS SwiftUI SDK is a dynamic framework for integrating an Atomic stream container into your SwiftUI app, presenting cards from a stream to your end users.

The SwiftUI SDK is written in Swift and supports iOS 16.0 and above.

The latest stable release of the SwiftUI SDK is 24.3.0

Installation

The SDK can be installed using CocoaPods, Swift Package Manager, or manually.

CocoaPods

1. Add the path to the SDK spec repo to your Podfile, along with the default specs repo:

source 'https://github.com/atomic-app/action-cards-ios-sdk-specs.git'
source 'https://github.com/CocoaPods/Specs.git'

2. Add the SDK as a dependency.

pod 'AtomicCards', '24.3.0'

3. Run pod update.

Alternative way to install Atomic SwiftUI SDK

Alternatively, you can install Atomic SDK directly through a git path. This will install the latest Atomic SwiftUI SDK.

pod 'AtomicCards', :git => 'https://github.com/atomic-app/action-cards-swiftui-sdk-releases.git'

Note: Currently you may face a known issue of a "Sandbox: rsync" failing message after integration. You can update your Xcode project build option ENABLE_USER_SCRIPT_SANDBOXING to 'No' to resolve this issue.

Swift Package Manager

1. Open your Xcode project, and choose File > Add Packages.
2. Enter https://github.com/atomic-app/action-cards-swiftui-sdk-releases in the upper right text field 'Search or Enter Package URL'.
3. Set the dependency rule and click 'Add Package'.
4. Add both AtomicSDK and AtomicSwiftUISDK to your target.

Manual Installation

1. You can download releases of the SDK from the Releases page on Github.
2. Once you've downloaded the version you need, navigate to your project in Xcode and select the "General" settings tab.
3. Drag both AtomicSDK.xcframework and AtomicSwiftUISDK.xcframework from the directory where you unzipped the release, to the Embedded Binaries section.
4. When prompted, ensure that "Copy items if needed" is selected, and then click "Finish".

Initializing the SDK

As per the standard iOS SDK you need to initialise the SDK before you can do anything else. With SwiftUI you can place it in the init function of your App subclass. For example:

import AtomicSDK

@main
struct SwiftUIBoilerplateApp: App {
    
    init() {
        AACSession.login(withEnvironmentId: "<your envid>", apiKey: "<your api key>", sessionDelegate: <your session delegate>, apiBaseUrl: <your api base URL>)
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Displaying containers

Displaying a vertical container

To display a vertical Stream Container in your view, call StreamContainer within your views body by specifying the flag indicating its presence in a navigation stack, and providing the container Id. StreamContainer also accepts a configuration object that can be ignored by default.

For example:

    var body: some View {
        NavigationStack {
            VStack {
                NavigationLink {
                    ZStack {
                        StreamContainer(isInNavigationStack: true, containerId: "<stream container id>")
                            .navigationTitle("Atomic Stream")
                    }
                } label: {
                    Text("Messages")
                }
            }
            .padding()
            .navigationTitle("Atomic Boilerplate")
            .navigationBarTitleDisplayMode(.large)
        }
    }

NavigationStack Presence

Properly setting the isInNavigationStack flag is crucial. In SwiftUI, nested navigation stacks can lead to unexpected behaviors. As such, the container will not attempt to generate its own navigation stack if indicated that it is already within an existing navigation stack.

The configuration object is of type ContainerConfiguration and inherits most of the properties from AACConfiguration. The options have been adapted to align with SwiftUI conventions.

For example to set your configuration object in your view model you could do something like:

    var config = ContainerConfiguration()
    
    init() {
        config.setCustomValue("test", for: .cardListTitle)
    }

This example sets the stream header title to "test".

To use the configuration you could pass it into the StreamContainer instance:

StreamContainer(isInNavigationStack: true, containerId: "1234", configuration: viewModel.config)

Displaying a single card container

The Atomic SwiftUI SDK also supports rendering a single card in your host app.

To create an instance of SingleCardContainer, which is configured in the same way as a vertical stream container, you supply the following parameters on instantiation:

1. The ID of the stream container to render in the single card container. The single card container renders only the first card that appears in that stream container;
2. A configuration object, which provides initial styling and presentation information to the SDK for the single card container.

The configuration options, supplied using the configuration object above, are the same as those for a stream container. But some properties are not applied to the single card container. For more details see the configuration section.

NavigationStack Presence

It's crucial to place SingleCardContainer within a NavigationStack hierarchy. While it's common to put a single card container in a ScrollView, placing NavigationStack inside ScrollView can lead to unexpected behaviour. Therefore, SingleCardContainer won't generate its own navigation stack.

The code snippet below shows how to display a single card container with some configuration.

var body: some View {
    var config = ContainerConfiguration()
    config.enabledUIElements = [.cardListToast]
    config.cardListRefreshInterval = 10
    return NavigationStack {
        ScrollView  {
            VStack {
                Text("Header view")
                SingleCardContainer(containerId: "1234", configuration: config)
                Text("Footer view")
            }
        }
    }
}

Configuration options for the single card container

The single card container uses the same ContainerConfiguration definition as the stream container. However, some properties are not applicable to the single card container. The following options DO NOT apply to single card containers:

- presentationStyle
- launchBackgroundColor
- launchLoadingIndicatorColor
- launchButtonColor
- launchTextColor
- CustomString.cardListTitle
- CustomString.awaitingFirstCard
- CustomString.allCardsCompleted
- CustomString.cardListFooterMessage
- CustomString.noInternetConnectionMessage
- CustomString.dataLoadFailedMessage
- CustomString.tryAgainTitle
- UIElements.cardListFooterMessage
- UIElements.cardListHeader

Third-party dependencies

Atomic iOS SwiftUI SDK contains one third-party dependency:

• Font Awesome Free 5.15.4, an icon font that is used for card icons. This is distributed as an OTF font.

Atomic iOS SwiftUI SDK does not use any dependency managers, all dependencies are integrated manually.

The standard Atomic iOS SDK is also included within SwiftUI SDK. For more information on its third-party dependencies, see the iOS SDK Guide.

Major features supported in this version

• Vertical stream container and single card container
  • including subviews and feedback options
• Markdown support
• Theming containers
• Card actions via buttons, including links and payload options
• Headline, Image, Text block and List controls
• Category and Image banners
• Custom fonts
• Swipe to snooze and dismiss
• Overflow menu, including snoozing, dismissing and voting
• Text input element (Note: Keyboard avoidance is not yet fully implemented.)
• Number input element
• Switch element
• Video element
• Full support for button styles