Skip to main content

iOS SDK (23.3.0-beta2)


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 23.3.0-beta2.

The current stable release is 23.3.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.


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


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 => '', :branch => 'beta'


pod 'AtomicSDK-framework', :git => '', :branch => 'beta'
  1. Run pod install.

Swift Package Manager

  1. Open your Xcode project, and choose File > Add Packages.
  2. Enter 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

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. Double-click the item "action-cards-ios-sdk-releases".
  6. Set the branch name to "master" and click "Done".

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 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.

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

SDK event observer (introduced in 23.3.0-beta1)

The Atomic iOS SDK provides functionality to observe SDK events that symbolise identifiable SDK activities such as card feed changes or user interactions with cards. The following code snippet shows how to observe SDK events.

AACSession.observeSDKEvents { event in
// Do something with the event.

Only one SDK event observer can be active at a time. If you call this method again, it will replace the previous observer.

The SDK provides all observed events in the base class AACSDKEvent. To access more specific information about a particular event, you can cast it to its corresponding event class. The table below lists all currently supported events, including some that are part of Atomic analytics. For detailed information about these events, please refer to Analytics reference.

Event nameEvent classAnalyticsDescription
card-dismissedAACSDKEventCardDismissedYESThe user dismisses a card.
card-snoozedAACSDKEventCardSnoozedYESThe user snoozes a card.
card-completedAACSDKEventCardCompletedYESThe user submits a card.
card-feed-updatedAACSDKEventCardFeedUpdatedNOA card feed has been updated
card-displayedAACSDKEventCardDisplayedYESA card is displayed in a container.
card-voted-upAACSDKEventCardVotedUpYESThe user taps on the “This is useful” option.
card-voted-downAACSDKEventCardVotedDownYESThe user taps the “Submit” button on the card feedback screen.
runtime-vars-updatedAACSDKEventRuntimeVarsUpdatedYESOne or more runtime variables are resolved.
stream-displayedAACSDKEventStreamDisplayedYESA stream container is first loaded or returned to.
user-redirectedAACSDKEventUserRedirectedYESThe user is redirected by a URL or a custom payload.
snooze-options-displayedAACSDKEventSnoozeOptionsDisplayedYESThe snooze date/time selection UI is displayed.
snooze-options-canceledAACSDKEventSnoozeOptionsCanceledYESThe user taps the “Cancel” button in the snooze UI.
card-subview-displayedAACSDKEventCardSubviewDisplayedYESA subview of card is opened.
card-subview-exitedAACSDKEventCardSubviewExitedYESThe user leaves the subview.
video-playedAACSDKEventVideoPlayedYESThe user hits the play button of a video.
video-completedAACSDKEventVideoCompletedYESA video finishes playing.
sdk-initializedAACSDKEventSDKInitializedYESAn instance of the SDK is initialized, or the JWT is refreshed.
request-failedAACSDKEventRequestFailedYESAny API request to the Atomic client API fails within the SDK, or a failure in WebSocket causes a fallback to HTTP polling.
Note: Network failure and request timeout does not trigger this event.
notification-receivedAACSDKEventNotificationReceivedYESA push notification is received by the SDK.

Accessing a specific SDK event

To access the unique properties of each event, you need to cast the base class AACSDKEvent passed in the callback to the specific event classes. You can determine the type of the event using either the eventType or eventName property. It is recommended to use eventType as it benefits from the code-completion system.

The following code snippet shows how to retrieve the attributes of a card's subview when its being displayed.

AACSession.observeSDKEvents { event in
switch event.eventType {
case .cardSubviewDisplayed:
if let event = event as? AACSDKEventCardSubviewDisplayed {
print("The subview \(event.subviewTitle) of card \(event.cardInstanceId) has been displayed.")

Accessing the raw contents

You can access the raw value of an event by calling the method getRawContents on the SDK event object. It will return a NSDictionary object containing all the data available to this event. Raw contents are only for debugging purposes and are subject to change. Please do not rely on it in production code.

AACSession.observeSDKEvents { event in
let rawData = event.getRawContents()
// Inspect the raw data for more details.

Stopping the observation

To stop the observation, call either [AACSession stopObservingSDKEvents] or [AACSession observeSDKEventsWithCompletionHandler:nil].

More examples

Fetching unseen card number in realtime

The unseen card number can be retrieved from user metrics. But it's a one-off call, so we had to repeatedly call the method to keep the unseen card number updated. By observing SDK events, you can retrieve the unseen card number whenever the seen status of a card changes. The following code snippet shows how to get the unseen card number of a container in these scenarios.

AACSession.observeSDKEvents { event in
switch event.eventType {
case .cardDisplayed, .cardFeedUpdated:
AACSession.userMetrics { metrics, error in
if let metrics = metrics {
let containerId = "1234"
let unseenCardsForContainer = metrics.unseenCardsForStreamContainer(withId: containerId)
print("The unseen cards for container \(containerId) is \(unseenCardsForContainer)")

Capturing the voting-down event

The following code snippet shows how to capture an event when the user votes down for a card.

AACSession.observeSDKEvents { event in
switch event.eventType {
case .cardVotedDown:
if let event = event as? AACSDKEventCardVotedDown {
print("The user has voted down for the card \(event.cardInstanceId)")
switch event.reason {
case .notRelevant:
print("The reason is it's not relevant.")
case .tooOften:
print("The reason is it's displayed too often.")
case .other:
print("The user provided some other reasons.")
if let message = event.otherMessage {
print("Other reason: \(message)")
@unknown default:
print("The reason is unknown.")

Toast for single card view (introduced in 23.3.0-beta2)

You can now display toast messages for a single card view, just like with other container types. Use enabledUiElements in AACSingleCardConfiguration to choose if you want to show these toast messages.

enabledUiElements is a bitmask indicating which UI elements are active in the stream container. By default, toast messages are displayed. For a single card view, the possible values are:

  • AACUIElementNone: Don't display any UI elements. This shouldn't be mixed with other values.
  • AACUIElementCardListToast: Toast messages will show at the screen's bottom. These messages pop up when cards are submitted, dismissed, snoozed, voted up/down, or if an error happens during these actions.
let config = AACSingleCardConfiguration()
config.enabledUiElements = .cardListToast
let singleCardView = AACSingleCardView(frame: self.view.frame, containerIdentifier: "1234", configuration: config)

To disable the toast, simply set enabledUiElements to AACUIElementNone, or [] in Swift.

let config = AACSingleCardConfiguration()
config.enabledUiElements = []