iOS SDK - Beta (24.1.0-beta1)

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

The current stable release is 24.1.3.

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

Maximum card width (Introduced in 24.1.0-beta1)

You can now specify a maximum width for each card within the vertical stream container or a single card view, with center alignment for the cards.

To set this, use the cardMaxWidth property in AACConfiguration to define the desired width, and apply this configuration when initializing the stream container.

The default value for cardMaxWidth is 0, which means the card will automatically adjust its width to match that of the stream container.

However, there are a few considerations for using this property:

• It's advised not to set the cardMaxWidth to less than 200 to avoid layout constraint warnings due to possible insufficient space for the content within the cards.

• Any negative values for this property will be reset to 0.

• If the specified cardMaxWidth exceeds the width of the stream container, the property will be ignored.

• In horizontal stream containers, the cardMaxWidth property behaves the same as the cardWidth property.

The following code snippet sets the maximum card width to 500.

Swift

let config = AACConfiguration()
config.cardMaxWidth = 500

let streamContainer = AACStreamContainerViewController(identifier: "1234", configuration: config)
present(streamContainer, animated: true)

Objective-C

AACConfiguration *config = [[AACConfiguration alloc] init];
config.cardMaxWidth = 500;

AACStreamContainerViewController *streamContainer = [[AACStreamContainerViewController alloc] initWithIdentifier:@"1234" configuration:config];
[self presentViewController:streamContainer animated:YES completion:nil];

Image linking (Introduced in 24.1.0-beta1)

This is currently a preview feature in Workbench.

You can now use images for navigation purposes, such as directing to a web page, opening a subview, or sending a custom payload into the app, as if they were buttons. This functionality is accessible in Workbench, where you can assign custom actions to images on your cards.

The updated analytics event 'user-redirected'

Redirection initiated by images also trigger the user-redirected analytics event. To accurately identify the origin of this event, a new detail property has been added, with four distinct values:

• image: The event was activated by an image.
• submitButton: The redirection was initiated via a submit button.
• linkButton: A link button was the source of the event.
• textLink: The trigger was a link embedded within markdown text.

See Analytics or Analytics reference for more details of the event user-redirected.

In iOS SDK, you can also capture the new detail property via SDK event observer. The following code snippet shows how to parse this property.

Swift

AACSession.observeSDKEvents { event in
    switch event.eventType {
    case .userRedirected:
        if let userRedirectedEvent = event as? AACSDKEventUserRedirected {
            switch userRedirectedEvent.detail {
            case .image:
                print("Event triggered by an image.")
            case .linkButton:
                print("Event triggered by a link button.")
            case .submitButton:
                print("Event triggered by a submit button.")
            case .textLink:
                print("Event triggered by a markdown link text.")
            @unknown default:
                print("Event triggered by a unknown component.")
            }
        }
    default:
        break
    }
}

Objective-C

[AACSession observeSDKEventsWithCompletionHandler:^(AACSDKEvent *sdkEvent) {
    switch (sdkEvent.eventType) {
        case AACSDKEventTypeUserRedirected: {
            AACSDKEventUserRedirected *userRedirectedEvent = (AACSDKEventUserRedirected *)sdkEvent;
            switch (userRedirectedEvent.detail) {
                case AACSDKEventRedirectDetailTypeImage:
                    NSLog(@"Event triggered by an image.");
                    break;
                case AACSDKEventRedirectDetailTypeLinkButton:
                    NSLog(@"Event triggered by a link button.");
                    break;
                case AACSDKEventRedirectDetailTypeSubmitButton:
                    NSLog(@"Event triggered by a submit button.");
                    break;
                case AACSDKEventRedirectDetailTypeTextLink:
                    NSLog(@"Event triggered by a markdown link text.");
                    break;
            }
        }
            break;
        default:
            break;
    }
}];

See the SDK event observer for more details on the event observer feature.

Capture image-triggered custom payload

In the Atomic Workbench, the functionality for custom payload has expanded. Initially, you could create a submit or link button with a custom action payload. Now, this capability extends to images, allowing the use of an image with a custom payload to achieve similar interactive outcomes as you would with buttons.

When such an image is tapped, the streamContainerDidTapLinkButton:withAction: method is called on your action delegate.

Unified Handling Approach for Images and Link Buttons

In this scenario, an image is treated similarly to a link button, meaning the same delegate method used for link buttons is applied to images as well.

This approach streamlines the handling of user interactions with both elements, ensuring a concise behavior across the UI.

The second parameter to this method is an action object, containing the payload that was defined in the Workbench for that button. You can use this payload to determine the action to take, within your app, when the image is tapped.

The action object also contains the card instance ID and stream container ID where the custom action was triggered.

The following code snippet navigates the user to the home screen upon receiving a specific payload.

Swift

// 1. Assign the action delegate
let config = AACConfiguration()
config.actionDelegate = self

// 2. Implement the callbacks
func streamContainerDidTapLinkButton(_ streamContainer: AACStreamContainerViewController, with action: AACCardCustomAction) {
    if let screenName = action.actionPayload["screen"] as? String, screenName == "home-screen" {
        // Perform an action
        self.navigateToHomeScreen()
    }
}

Objective-C

// 1. Assign the action delegate
AACConfiguration *config = [[AACConfiguration alloc] init];
config.actionDelegate = self;

// 2. Implement the callbacks
- (void)streamContainerDidTapLinkButton:(AACStreamContainerViewController*)streamContainer withAction:(AACCardCustomAction*)action {
    if([action.actionPayload[@"screen"] isEqualToString:@"home-screen"]) {
        // Perform an action
        [self navigateToHomeScreen];
    }
}