Skip to main content

Android Jetpack Compose SDK (25.3.0-beta1)

Introduction​

The Atomic Jetpack Compose SDK is an Android SDK for integrating an Atomic stream container into your Android app, presenting cards from a stream to your users. Built with Jetpack Compose at its core and written entirely in Kotlin, it delivers a seamless integration experience for Jetpack Compose apps.

The latest beta release of the SDK is 25.3.0-beta1.

Beta

The Jetpack Compose SDK is available as an early beta, not all features available in the Android SDK have been implemented, and there may be differences in behaviour from the existing SDK.

We encourage you to try it out and contact us with any feedback or issues that you experience.

Supported Android versions​

The SDK targets a minimum SDK version of 24.

Installation​

The SDK can be installed as a Gradle dependency.

Gradle​

The SDK is hosted on our public Maven repository. You'll need to add the following repository to your root build.gradle or settings.gradle file depending on how your project is set up:

    repositories {
      maven {
        url  "https://downloads.atomic.io/android-sdk/maven"
      }
    }

Then, add the following to your app’s build.gradle

dependencies {
    implementation 'io.atomic.actioncards:aaccore:25.3.0-beta1'
    implementation 'io.atomic.actioncards:aaccompose:25.3.0-beta1'
}

Initializing the SDK​

Before using the SDK, you must log in by providing your environmentId, apiKey, and apiHost. These can be found in the Atomic Workbench.

info

You may call this method only when the user has authenticated in your app. But be careful to ensure it is called in all cases before showing the Atomic Stream Container. For example, check that it is called when opening the app after process death, or from a notification intent.

The SDK uses a JSON Web Token (JWT) to perform authentications.

The SDK Authentication guide provides step-by-step instructions on how to generate a JWT and add a public key to the Workbench.

You must also provide an authentication token delegate to provide the JWT token. If a token cannot be provided, return an empty string.

The complete code snippet for initializing the SDK is:

AACCore.shared.login(environmentId, apiKey, apiHost) { onTokenReceived ->
  // Fetch your token here
  // Then return it by calling onTokenReceived(token)
  onTokenReceived(token)
}

Log out​

Logout will effectively end the user's session. It will clear theme and card caches, send any pending analytics events to the platform, and then log out the current user. The session delegate will also be reset and SDK settings cleared, which will cease any network traffic.

info

You must call logout() before switching users in your application, even if there are no other changes to the configuration.

To log out, call:

val result = AACCore.shared.logout()

Displaying containers​

StreamContainerConfiguration is a central configuration class used to customize the behavior and appearance of all Atomic containers in the SDK. By creating and modifying a StreamContainerConfiguration instance, you can control a wide range of options such as UI elements, refresh intervals, card styling, custom strings, and event handling.

You typically create a StreamContainerConfiguration object in your view model or view, set its properties or call its methods to adjust the container's features, and then pass it to the container you are displaying. Each container type accepts a configuration object as an optional parameter. If omitted, the container will use default settings.

Below are the main configuration options available in StreamContainerConfiguration:

Style and presentation​

  • interfaceStyle: The interface style (light, dark, or automatic) to apply to the stream container (default: InterfaceStyle.Automatic).
  • toastMessagesEnabled: Show toast messages at the bottom of the screen (default: true).
  • cardListHeaderEnabled: Show a header at the top of the vertical card list (default: true).

Custom strings​

Set custom strings by setting the following keys on the StreamContainerConfiguration to a non-empty string. Set to null to revert to the SDK default.

  • cardListTitle: The title to display at the top of the card list (default: "Cards").
  • cardSnoozeTitle: The title to display for the card snooze functionality (default: "Remind me").
  • votingFeedbackTitle: Title displayed at the top of the screen where users can provide feedback on why they found a card useful or not useful (default: "Send feedback").
  • noInternetMessage: Error message for no internet (default: "No internet connection").
  • toastCardDismissMessage: Toast for card dismissed (default: "Card dismissed").
  • toastCardCompletedMessage: Toast for card completed (default: "Card completed").
  • toastCardSnoozeMessage: Toast for card snoozed (default: "Snoozed until X").
  • toastCardFeedbackMessage: Toast for card feedback (default: "Feedback received").
  • thumbnailImageActionLinkText: CTA for thumbnail images (default: "View").
  • votingFeedbackValidationMessage: Validation message shown when the user reaches the 280 character limit while providing feedback on the feedback page (default: "Feedback is limited to 280 characters").

You will find usage examples for StreamContainerConfiguration throughout this guide, in the context of each container type.

Displaying a vertical container​

The Atomic SDK provides support for rendering a vertical stream container within your host application. The vertical container displays cards arranged from top to bottom.

To use this feature, in your Composable function, call the StreamContainer composable, supplying the following arguments:

  1. modifier: A Compose modifier to specify the layout of the container, you must specify a width either .fillMaxWidth() or an explicit width.
  2. container ID: Identifier for the stream container you wish to display.
  3. Configuration (optional): Defines the desired appearance and behavior of the stream container.
  4. Handlers (optional): Defines some callbacks for calling your own code based on events or actions within the stream container.

The following code snippet displays a vertical container using default configurations:

StreamContainer(
  modifier = Modifier.fillMaxWidth(),
  containerId = "ABC1234",
  configuration = StreamContainerConfiguration(),
  handlers = StreamContainerHandlers()
)

To modify your configuration object, either set the values using the data class initializer. For example,

val configuration = StreamContainerConfiguration(
    toastMessagesEnabled = false,
    cardListTitle = "Notifications"
)

Or make a copy of an existing configuration, passing the new values.

val newConfiguration = configuration.copy(
    cardListTitle = "My messages"
)

Passing a new configuration class is required to update the UI, mutating the variables in place will not update them.

Displaying a single card container​

The Atomic SDK also supports rendering a single card in your host app. The single card container displays a single card at a time, and collapses to take up no space when there are no cards to display in the stream.

Single card containers will expand vertically to take up the space required by the card. You should not set an explicit height with the modifier. Unlike the vertical container which is designed to take up the whole view, you may place a single card container inside of a scrollable column.

To display a SingleCardView, which is configured in the same way as a vertical stream container, you supply the following arguments to the SingleCardView composable:

  1. modifier: A Compose modifier to specify the layout of the container, you must specify a width either .fillMaxWidth() or an explicit width.
  2. container ID: Identifier for the stream container you wish to display.
  3. Configuration (optional): Defines the desired appearance and behavior of the stream container.
  4. Handlers (optional): Defines some callbacks for calling your own code based on events or actions within the stream container.

The following code snippet displays a single card container using default configurations:

SingleCardView(
  modifier = Modifier.fillMaxWidth(),
  containerId = "ABC1234",
  configuration = StreamContainerConfiguration(),
  handlers = StreamContainerHandlers()
)

In the Atomic Workbench, you can create a submit or link button with a custom action payload.

  • When such a Link button is tapped, the linkButtonWithPayloadActionHandler callback is invoked.
  • When such a Submit button is tapped, and after the card is successfully submitted, the submitButtonWithPayloadActionHandler callback is invoked.

These callbacks are passed a custom 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 submit or link button is tapped.

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

val handlers = StreamContainerHandlers(
  linkButtonWithPayloadActionHandler = { aacCardCustomAction ->
    println(aacCardCustomAction.streamContainerId)
    println(aacCardCustomAction.cardInstanceId)
    println(aacCardCustomAction.payload)
  },
  submitButtonWithPayloadActionHandler = { aacCardCustomAction ->
    println(aacCardCustomAction.streamContainerId)
    println(aacCardCustomAction.cardInstanceId)
    println(aacCardCustomAction.payload)
  }
)

Card snoozing​

The Atomic SDKs provide the ability to snooze a card from a stream container or single card view. Snooze functionality is exposed through the card’s action buttons, overflow menu and the quick actions menu (exposed by swiping a card to the left).

Tapping on the snooze option from either location brings up the snooze date and time selection screen. The user selects a date and time in the future until which the card will be snoozed. Snoozing a card will result in the card disappearing from the user’s card list or single card view, and reappearing again at the selected date and time. A user can snooze a card more than once.

When a card comes out of a snoozed state, if the card has an associated push notification, and the user has push notifications enabled, the user will see another notification, where the title is prefixed with Snoozed:.

You can customize the title of the snooze functionality, as displayed in a card’s overflow menu and in the title of the card snooze screen. The default title, if none is specified, is Remind me.

On the StreamContainerConfiguration class, set cardSnoozeTitle to your own custom value.

StreamContainerConfiguration(cardSnoozeTitle = "My title")

Dependencies​

Version 25.3.0-beta1 uses these top-level runtime dependencies.

  • io.atomic.actioncards:aaccore:25.3.0-beta1

  • org.jetbrains.kotlin:kotlin-stdlib:1.9.24 -> 2.0.0

  • com.squareup.moshi:moshi-kotlin-codegen:1.15.1

  • androidx.core:core-ktx:1.15.0

  • androidx.lifecycle:lifecycle-runtime-ktx:2.8.7

  • androidx.activity:activity-compose:1.10.0

  • androidx.compose:compose-bom:2025.01.00

  • androidx.compose.ui:ui -> 1.7.6 (*)

  • androidx.compose.ui:ui-graphics -> 1.7.6 (*)

  • androidx.compose.ui:ui-tooling-preview -> 1.7.6

  • androidx.compose.material3:material3 -> 1.3.1

  • androidx.navigation:navigation-compose:2.8.5

  • androidx.constraintlayout:constraintlayout-compose:1.1.0

  • androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7 (*)

  • com.squareup.moshi:moshi-kotlin:1.15.0

  • org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3 (*)

  • androidx.compose.foundation:foundation:1.7.6 (*)

  • io.coil-kt:coil:2.7.0

  • io.coil-kt:coil-compose:2.7.0

  • io.coil-kt:coil-svg:2.7.0

  • com.google.android.libraries.places:places:4.1.0

  • androidx.core:core-i18n:1.0.0-alpha01

  • com.caverock:androidsvg-aar:1.4

  • androidx.media3:media3-exoplayer:1.5.1

  • androidx.media3:media3-exoplayer-dash:1.5.1

  • androidx.media3:media3-ui:1.5.1

  • com.jakewharton.threetenabp:threetenabp:1.4.6

  • com.squareup.moshi:moshi:1.15.1 (*)

Last updated on