iOS SDK (23.3.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 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.

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'

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

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

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.

Swift

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

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    // Do something with the event.
}];

info

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 name	Event class	Analytics	Description
card-dismissed	AACSDKEventCardDismissed	YES	The user dismisses a card.
card-snoozed	AACSDKEventCardSnoozed	YES	The user snoozes a card.
card-completed	AACSDKEventCardCompleted	YES	The user submits a card.
card-feed-updated	AACSDKEventCardFeedUpdated	NO	A card feed has been updated
card-displayed	AACSDKEventCardDisplayed	YES	A card is displayed in a container.
card-voted-up	AACSDKEventCardVotedUp	YES	The user taps on the “This is useful” option.
card-voted-down	AACSDKEventCardVotedDown	YES	The user taps the “Submit” button on the card feedback screen.
runtime-vars-updated	AACSDKEventRuntimeVarsUpdated	YES	One or more runtime variables are resolved.
stream-displayed	AACSDKEventStreamDisplayed	YES	A stream container is first loaded or returned to.
user-redirected	AACSDKEventUserRedirected	YES	The user is redirected by a URL or a custom payload.
snooze-options-displayed	AACSDKEventSnoozeOptionsDisplayed	YES	The snooze date/time selection UI is displayed.
snooze-options-canceled	AACSDKEventSnoozeOptionsCanceled	YES	The user taps the “Cancel” button in the snooze UI.
card-subview-displayed	AACSDKEventCardSubviewDisplayed	YES	A subview of card is opened.
card-subview-exited	AACSDKEventCardSubviewExited	YES	The user leaves the subview.
video-played	AACSDKEventVideoPlayed	YES	The user hits the play button of a video.
video-completed	AACSDKEventVideoCompleted	YES	A video finishes playing.
sdk-initialized	AACSDKEventSDKInitialized	YES	An instance of the SDK is initialized, or the JWT is refreshed.
request-failed	AACSDKEventRequestFailed	YES	Any 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-received	AACSDKEventNotificationReceived	YES	A 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.

Swift

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.")
        }
    default:
        break
    }
}

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    switch(sdkEvent.eventType) {
        case AACSDKEventTypeCardSubviewDisplayed: {
            AACSDKEventCardSubviewDisplayed *subviewDisplayed = (AACSDKEventCardSubviewDisplayed *)sdkEvent;
            if(subviewDisplayed != nil) {
                NSLog(@"The subview %@ of card %@ has been displayed.", subviewDisplayed.subviewId, subviewDisplayed.cardInstanceId);
            }
        }
            break;
        default:
            break;
    }
}];

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.

Swift

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

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    NSDictionary *rawData = [sdkEvent 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.

Swift

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)")
            }
        }
    default:
        break
    }
}

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    switch (sdkEvent.eventType) {
        case AACSDKEventTypeCardDisplayed:
        case AACSDKEventTypeCardFeedUpdated: {
            // Fetch the user metrics.
            [AACSession userMetricsWithCompletionHandler:^(AACUserMetrics *response, NSError *error) {
                if(response != nil) {
                    NSString *containerId = @"1234";
                    NSInteger unseenCardsForContainer = [response unseenCardsForStreamContainerWithId:containerId];
                    NSLog(@"The unseen cards for container %@ is %ld", containerId, unseenCardsForContainer);
                }
            }];                
        }
            break;
        default:
            break;
    }
}];

Capturing the voting-down event

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

Swift

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.")
            }
        }
    default:
        break
    }
}

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    switch (sdkEvent.eventType) {
        case AACSDKEventTypeCardVotedDown: {
            AACSDKEventCardVotedDown *votedDown = (AACSDKEventCardVotedDown *)sdkEvent;
            NSLog(@"The user has voted down for the card %@", votedDown.cardInstanceId);
            switch (votedDown.reason) {
                case AACSDKEventVoteDownReasonNotRelevant:
                    NSLog(@"The reason is it's not relevant.");
                    break;
                case AACSDKEventVoteDownReasonTooOften:
                    NSLog(@"The reason is it's displayed too often.");
                    break;
                case AACSDKEventVoteDownReasonOther:
                    NSLog(@"The user provided some other reasons: %@.", votedDown.otherMessage);
                    break;
            }
        }
            break;
        default:
            break;
    }
}];

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.

Swift

let config = AACSingleCardConfiguration()
config.enabledUiElements = .cardListToast
let singleCardView = AACSingleCardView(frame: self.view.frame, containerIdentifier: "1234", configuration: config)
self.view.addSubview(singleCardView)

Objective-C

AACSingleCardConfiguration *configuration = [[AACSingleCardConfiguration alloc] init];
config.enabledUiElements = AACUIElementCardListToast;

AACSingleCardView *singleCardView = [[AACSingleCardView alloc] initWithFrame:self.view.frame containerIdentifier:@"1234" configuration:config];
[self.view addSubview:singleCardView];

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

Swift

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

Objective-C

AACSingleCardConfiguration *configuration = [[AACSingleCardConfiguration alloc] init];
config.enabledUiElements = AACUIElementNone;