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.
- Add the SDK as a dependency. You have two options available:
AtomicSDK
: the Atomic SDK distributed as anxcframework
, 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'
- Run
pod install
.
Swift Package Manager
- Open your Xcode project, and choose File > Add Packages.
- Enter
https://github.com/atomic-app/action-cards-ios-sdk-releases
in the upper right text field 'Search or Enter Package URL'. - Select option "Branch" from the dropdown list of "Dependency Rule" and enter "beta" in the right text input.
- 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.
- Open your Xcode project.
- Select your project in the Project Navigator (the left-hand side panel).
- In the main editor area, select your target under the "PROJECT" section.
- Go to the "Package Dependencies" tab.
- Double-click the item "action-cards-ios-sdk-releases".
- Set the branch name to "master" and click "Done".
Manual Installation
- You can download beta releases of the SDK from the Releases page on Github. Beta releases are labelled with "Pre-release".
- Once you've downloaded the version you need, navigate to your project in Xcode and select the "General" settings tab.
- Drag either
AtomicSDK.xcframework
orAtomicSDK.framework
from the directory where you unzipped the release, to theEmbedded Binaries
section. - When prompted, ensure that "Copy items if needed" is selected, and then click "Finish".
- If you chose AtomicSDK.framework above, you will also need to run the
strip-frameworks.sh
script (downloadable from this repository) as part of aRun 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.
- Swift
- Objective-C
AACSession.observeSDKEvents { event in
// Do something with the event.
}
[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
// 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 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
- Objective-C
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
}
}
[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
- Objective-C
AACSession.observeSDKEvents { event in
let rawData = event.getRawContents()
// Inspect the raw data for more details.
}
[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]
[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
- Objective-C
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
}
}
[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
- Objective-C
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
}
}
[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
- Objective-C
let config = AACSingleCardConfiguration()
config.enabledUiElements = .cardListToast
let singleCardView = AACSingleCardView(frame: self.view.frame, containerIdentifier: "1234", configuration: config)
self.view.addSubview(singleCardView)
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
- Objective-C
let config = AACSingleCardConfiguration()
config.enabledUiElements = []
AACSingleCardConfiguration *configuration = [[AACSingleCardConfiguration alloc] init];
config.enabledUiElements = AACUIElementNone;