Before completing this authoring cards tutorial, we highly recommend you complete the prerequisite Introduction to the workbench tutorial.
Product managers, product owners, and client engineers can also explore SDK configuration options in: Integrating the SDKs
Designers can also explore: The Theme Editor
Your Atomic account (known as an Organization) comes with a default Sandbox Environment.
It is preloaded with sample cards that showcase Atomic features and functionality.
- Navigate to the Cards section of the Workbench:
- Then select the the card you wish to edit:
Duplicate a card by selecting the overflow menu (3 vertical dots) on the right of the card's name, and then
- Or to create a new card from scratch, select
By default you land in the
Content section of the Card. This is where you add elements, such as text, images, and buttons.
The Content area has an intuitive interface for designing and managing cards:
The card editor is on the left, and the card preview is on the right.
- Use the
Previewdropdown to change the preview of the card to use a different theme.
Learn more about editing and configuring themes in our Theme Editor tutorial.
There are 6 states a card template can be in:
Draft: New cards are in Draft state by default. Atomic automatically saves any changes to card templates as you make them. When testing, you can send test data from within the Card Editor to draft cards, and see what they look like on a testing app, however Live Data is not processed by draft cards.
Awaiting approval: Card templates that are pending approval cannot be edited unless the approval request is cancelled.
Approved: Once approvals are given, the card can be published by anyone with admin permission to the Card template resource.
Published: When Published, data payloads result in customer cards. If you make any changes to a published card, it automatically reverts to the draft state. Once you’re happy with the updated card, you can then republish the card to update it.
Archived: An archived card template can’t be used to send cards containing live data. However, you can continue to send Test Data to archived cards.
Discarded: Deleted forever.
ℹ️ Note: if you make a change to an archived card, it is automatically put into draft state.
Top level and subview elements
Our Card design principles guide provides insights and recommendations on how to craft well designed cards.
Top-level is how we refer to the default view of a card - the card content a customer sees in their stream container.
Each card needs some top level content and usually has at least one action button.
Most elements can be re-ordered by dragging and dropping in the editor.
The Card element reference guide outlines the details for each of the content elements.
Use the card-builder interface to add content elements (such as a category, headlines, text, images, videos, and lists), and actions buttons.
A Subview is a secondary card view, where you can display additional information, and collect response data from the customer.
To create a Link button leading to a subview, first add a Link button element on the top level, then configure the button's behaviour to open a subview.
If no subviews exist yet, create a new subview:
Most of the text, input and media elements described below are also available in the subview. The Card element reference details for each element what view they are available in.
Subviews can only have one type of action button (
submit), and not more than one
submit button per subview.
Categoryelement is added by default to a new card. If left blank, no category is presented. Only one headline is allowed per card.
Headlineelement is a title intended as the main heading for a card. Only one headline is allowed per card.
Text blockelements provide a body of text, supports Markdown formatting and an optional icon on its left.
Listelement provides a list of values.
Any Media you'd like to display in cards needs to be either referenced as a URL or uploaded into the
The Media Library is where you can upload media to your account, which can then be referenced in card content. Note: you can also reference it by absolute URL.
Atomic supports mp4, png, jpeg, and GIF image formats (Note: animated GIFs are currently not supported on all platforms).
Images can be displayed as a banner, or as they are, or as a thumbnail with accompanying text within the body of a card.
See a full list of the image formats supported in our help docs: Media formats.
To upload images to your Atomic account, go:
To reference images from the Media library or External URL, add an
Video element, and then select its source.
As captured in the table below, many form elements can have validation added. For example, if the input is a required field and/or if the customer’s response needs to be a minimum or maximum length. All validation criteria have corresponding error messages that are displayed to customers when the validation criteria are not met.
Validation for form elements can be added by clicking the
Add button at the bottom of the form element. The dialogue window shown depends on the type of form element.
The screenshot below shows how to add validation for a number input element.
|Date picker||Allowing the customer to select a day, month and year from a platform-specific picker UI.||Maximum date, Minimum date, Required||Default value, Label, Placeholder, Stacked | Inline, Thumbnail|
|Dropdown||A dropdown in the chosen format, allowing the customer to select from a list of pre-defined values.||Required||Default value, Label, Placeholder, Stacked | Inline, Thumbnail|
|Stepper||Allows the customer to step up and down between a minimum and maximum value.||Maximum value, Minimum value, Required||Default value, Label, Maximum value, Minimum value, Step value, Thumbnail|
|Switch||Allows a customer to provide a binary response.||Label, Thumbnail, default, on /off|
|Text block||A body of text, supporting Markdown formatting and an optional icon on its left.||Icon, Text|
|Text input||Allows a customer to provide a single or multi-line text response.||Maximum length, Minimum length, Regular expression, Required||Default value, Label, Number of lines,Stacked | Inline,Thumbnail|
|Number input||Renders a single line input that allows only numeric values (integer or decimal).||Maximum value, Minimum value, Required||Default value, Label, Thumbnail|
Inputs can be displayed in multiple formats such as on a single line, stacked with a floating label, or placed alongside an optional image.
Learn more about supported properties in our Card Element Reference.
Using form elements in toplevel and subview: do's and don'ts
It is possible to add multiple subviews to one toplevel card, and have multiple input elements on the toplevel as well as the different subviews.
Overloading a card (and a customer) with this many navigation and input options is not a good idea for a number of reasons. Most importantly, input values can get lost when customers navigate between different card views before finally submitting the card.
To avoid confusion and ensure input values being sent correctly, we have the following suggestions:
- Ensure each input element has a unique name. You can also change the name each of your input elements to something meaningful (you can edit the automatically generated
input namein the overflow menu of each input element).
- Think about where you want to collect the input from: toplevel or subview? Only add input elements to one of these levels.
- Make sure you have a
submitaction button in that view of the card you added your input elements to.
When you would like to validate a customers response in a text input, beyond the length of the response, Atomic provides support of Regular Expressions (Regex).
Contact one of your developers to write a Regex to meet your needs. For example, if you required an email address you could use the Regex:
Once you have configured a card, and are proficient sending it from the Workbench, you may like to explore triggering cards using the Atomic API and a third party tool (e.g. Insomnia).
Check out: Using Insomnia with Atomic’s API.
Each card typically will have at least one action button.
There are six types of action buttons, which are explained in detail in the Card element reference guide:
Submit: the card is submitted when the customer taps or clicks it.
Link: the card persists when the customer taps or clicks it. A subview is triggered, or an external URL is launched.
Dismiss: the card is dismissed when the customer taps or clicks it.
Snooze: the card is snoozed when the customer taps or clicks it, which means it is no longer visible in the card stream.
Vote up: the card persists when the customer taps or clicks it. A corresponding analytics event (
card-voted-up) is sent for that card.
Vote down: the card persists when the customer taps or clicks it. The button redirects to a secondary screen to provide further feedback. An analytics event containing this feedback is sent (
Regardless of the button type, Atomic can be configured to direct your customers to the appropriate place, and return the relevant information to your systems.
|Values||Sent with the response when a submit button is triggered.||Submit|
|Subview||Where additional information is displayed and can be collected.||Link|
|URL||Where the customer is navigated to when submission completes.||Link,Submit|
|Payload||Used for any custom action that is handled by the host app.||Link,Submit|
These actions take place when a submit button is selected (on either the top view view or a subview), or when a customer selects a link button:
URLthat the customer is redirected to when submission completes (not currently exposed in the Workbench). For example,
- To direct to a callable link (e.g. phone number), use the prefix
- To direct to a callable link (e.g. phone number), use the prefix
Payloadis used for any custom action that is handled by the host app. Atomic passes this payload data directly to the host app, for it to determine what course of action to take. The structure of this payload is entirely up to you, and as such, the way it is interpreted is also dependent on adding custom code to your app. For example, you could use this payload to:
- navigate to a screen, including a different URL in web
- display a message
Subview(only on a 'Link' button). See below.
When submitting a card, a value field is optionally sent as part of the response body.
Values are sent with the response when a submit button is triggered. For example, you may like to update your marketing CRM with useful information recording the customer activity on the card:
Add icons next to the button text
Icons can be placed to the left of button text. We support the Free Font Awesome collection. Note: icons are not displayed on subviews.
Within the card editor, the blue text indicates placeholders for variables.
A card instance can be individually tailored to each target recipient. For example, a variable
When defining a card template, you can add variable placeholders. When the card is sent, that placeholder will be populated with the correct value, as specified in the Atomic customer profile or the request payload.
Conditional variables allow you to specify a dynamic value which depends on the value of another variable. For example, this allows you to manage pluralization of text within a card. Any string variable can be assigned a conditional value based on a comparison of another variable or string.
Check out the variables sample card in your
Sandbox environment for a card example using conditional variables to manage localization.
value for a variable will be presented in the card unless the API request payload overrides it.
If you don't want the value to be overridden by an API request payload, toggle the
Allow request payload to overwrite to
Required variables is currently in beta. Please contact us to provide feedback.
Allow request payload to overwrite is set to
on an additional option is shown to make the variable required in request payloads.
A required variable means any requests to send the card will require that variable to be included in the payload, otherwise the request will fail.
A runtime variable is a specific type of variable that is resolved at runtime by your host app every time the card is loaded.
The SDK will request that your host app resolve the variable. If the variable is not resolved before the timeout (defined in your SDK integration), the default value you define in the Workbench will be used.
Read more about runtime variables in our Android SDK, iOS SDK, and Web SDK.
See the Sending a card tutorial to learn about sending cards, and customising the advanced options available.