Skip to main content

iOS SDK - Beta (24.2.0-beta2)

Introduction​

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

The latest beta release is 24.2.0-beta2.

The current stable release is 24.2.0.

Accessing the demo App​

The Atomic Demo App is where you can view test cards. To run the latest beta version of Atomic Demo app, join the Atomic Connect beta - TestFlight.

There are also Android and Web versions of Atomic Demo apps. Read more in the Introduction to the workbench.

Installation​

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

CocoaPods​

Beta versions of Atomic SDK can only be retrieved from the beta branch of the release repo.

  1. Add the SDK as a dependency. You have two options available:
  • AtomicSDK: the Atomic SDK distributed as an xcframework, with support for Apple Silicon (requires Cocoapods 1.9 or above);
  • AtomicSDK-framework: the Atomic SDK distributed as a fat framework, with slices for arm64 and x86_64.
pod 'AtomicSDK', :git => 'https://github.com/atomic-app/action-cards-ios-sdk-releases', :branch => 'beta'

or

pod 'AtomicSDK-framework', :git => 'https://github.com/atomic-app/action-cards-ios-sdk-releases', :branch => 'beta'
  1. Run pod install.

Swift Package Manager​

  1. Open your Xcode project, and choose File > Add Packages.
  2. Enter https://github.com/atomic-app/action-cards-ios-sdk-releases in the upper right text field 'Search or Enter Package URL'.
  3. Select option "Branch" from the dropdown list of "Dependency Rule" and enter "beta" in the right text input.
  4. Click 'Add Package'.

Switching back to the stable version (Applicable for Xcode 15; steps may vary in previous versions)​

Do the following steps if later you want to switch the version back to the latest stable version.

  1. Open your Xcode project.
  2. Select your project in the Project Navigator (the left-hand side panel).
  3. In the main editor area, select your target under the "PROJECT" section.
  4. Go to the "Package Dependencies" tab.
  5. From the "Dependency Rule" dropdown, select "Up to Next Major Version".
  6. Note that the version field might automatically be filled with "1.0.0", indicating the 1.x.x version will be used. To use a different version, change "1.0.0" to the version you need, such as "23.0.0".

Manual Installation​

  1. You can download beta releases of the SDK from the Releases page on Github. Beta releases are labelled with "Pre-release".
  2. Once you've downloaded the version you need, navigate to your project in Xcode and select the "General" settings tab.
  3. Drag either AtomicSDK.xcframework or AtomicSDK.framework 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".
  5. If you chose AtomicSDK.framework above, you will also need to run the strip-frameworks.sh script (downloadable from this repository) as part of a Run Script phase in your target, to get around an App Store submission bug, caused by iOS simulator architectures being present in the fat framework.
info

Note: AtomicSDK.xcframework includes support for Apple Silicon, but requires Xcode 11 or higher, while AtomicSDK.framework is a fat framework.

Custom Icons (Introduced in 24.2.0-beta1)​

This is currently a preview feature in Workbench.

Requires iOS 13+

The SDK now supports the use of custom icons in card elements. When you are editing a card in the card template editor of the Workbench you will notice that for card elements that support it the properties panel will show an "Include icon" option. From this location you can select an icon to use, either from the Media Library or Font Awesome.

Choosing to use an icon from the Media Library you have the ability to provide an SVG format icon and an optional fallback icon to be used in case the SVG fails to load. The "Select icon" dropdown will present any SVG format assets in your media library which can be used as a custom icon. To add an icon for use you can press the "Open Media Library" button at the bottom of the dropdown.

Custom icon colors​

The Workbench theme editor now provides the ability to set a color and opacity value for icons in each of the places where an icon may be used. The SDK will apply the following rules when determining what color the provided icon should be displayed in:

  • All icons will be displayed with the colors as dictated in the SVG file.
  • Black is used if no colors are specified in the SVG file.
  • Where a currentColor value is used in the SVG file, the following hierarchy is applied:
    1. Use the icon theme color if this has been supplied.
    2. Use the color of the text associated with the icon.
    3. Use a default black color.

Note: Opacity is currently not supported for currentColor.

Custom icon sizing​

The custom icon will be rendered in a square icon container with a width & height in pixels equal to the font size of the associated text. Your supplied SVG icon will be rendered centered inside this icon container, at its true size until it is constrained by the size of container, at which point it will scale down to fit.

Fallback Rules​

There are two scenarios where a fallback could occur for an SVG icon:

  1. If the provided SVG image is inaccessible due to a broken URL or network issues, such as those caused by certificate pinning.
  2. If the SVG icon is not supported on iOS. Currently, SVG features are not fully supported in the iOS SDK, so please check with our support team for details on supported SVG images.

In these scenarios, the following fallback rules apply:

  1. The fallback FontAwesome icon is used if it is set in Atomic Workbench for this custom icon.
  2. Otherwise, a default placeholder image is displayed.

Button name property in API-driven card actions (Introduced in 24.2.0-beta1)​

Note: This is a breaking change to API-driven card actions.

Atomic cards now include button names when they are submitted. The name will be added to analytics to enable referencing the triggering button in an Action Flow. According to this change, you now need to provide a button name when submitting cards via API-driven card actions.

The button name of a submit button can be acquired when receiving cards through API-driven cards. The following code snippet shows how to obtain button name(s) from the top-level of the first card.

AACSession.observeStreamContainer(identifier: "1", configuration: nil) { cards in
    if let card = cards?.first {
        // Pass `nil` for top-level buttons, or a subview ID for subview buttons.
        let buttons = card.buttons(withSubviewId: nil)
        for button in buttons {
            if let submitButton = button as? AACCardNodeSubmitButton, let buttonName = submitButton.buttonName {
                print("The button name of submit button \(submitButton.text) is \(buttonName)")
            }
        }
    }
}

Submitting a card​

The following code snippet shows how to submit a card via API-driven card actions.

let action = AACSessionCardAction(submitActionWithContainerId: "1", cardId: "card-id", submitButtonName: "button-name", submitValues: [
    "submit-key": "submitted values",
    "submit-key2": 999
])
AACSession.onCardAction(action) { error in
    if let error = error {
        print("An error happened when submitting the card.")
    } else {
        print("Card submitted.")
    }
}

Multiple display heights for banner and inline media components (Introduced in 24.2.0-beta2)​

This is currently a preview feature in Workbench.

You can now specify different display heights in Atomic Workbench for banner and inline media components. There are four options, each of which defines how the thumbnail cover of that media is displayed.

  • Tall The thumbnail cover is 200 display points high, spanning the whole width and cropped as necessary. This is the default value and matches existing media components.
  • Medium The same as "Tall", but only 120 display points high.
  • Short The same as "Tall" but 50 display points high. Not supported for inline or banner videos.
  • Original The thumbnail cover will maintain its original aspect ratio, adjusting the height dynamically based on the width of the card to avoid any cropping.

Note: For older version of the SDK, all options will fall back to "Tall".

Last updated on