Authoring cards
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
Overview
Watch the video below to learn the basics about creating action cards.
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 Duplicate card.
- Or to create a new card from scratch, select New card:
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 Preview dropdown to change the preview of the card to use a different theme.
Learn more about editing and configuring themes in our Theme Editor tutorial.
Publishing cards
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.
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), input elements, and link and actions buttons.
A Subview is a secondary card view, where you can display additional information.
To create a Link button leading to a subview, first add a Link button element on the top level, then configure the button's behavior to open a subview.
If no subviews exist yet, create a new subview:
Subview content
All 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.
Text
The Category element is added by default to a new card. If left blank, no category is presented. Only one headline is allowed per card.
The Headline element is a title intended as the main heading for a card. Only one headline is allowed per card.
The Text block elements provide a body of text, supports Markdown formatting and an optional icon on its left.
The List element provides a list of values.
Media
Any Media you'd like to display in cards needs to be either referenced as a URL or uploaded into the Media library.
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.
Media uploads have a size limit of 40 MB. All uploaded media files are scanned for viruses before they can be used in card templates.
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: Cards > Media library.
To reference images from the Media library or External URL, add an Image or Video element, and then select its source.
Form validation
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.
| Element | Description | Validation options | Views |
|---|---|---|---|
| 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. You can have input elements either on:
- the toplevel
- one or more 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 name in the overflow menu of each input element).
- Think about where you want to collect the input from: toplevel or subview? You can only add input elements to one of these levels. Only the input from the subview where the submit action button was clicked, will be submitted.
- Make sure you have a submit action button in that view of the card you added your input elements to.
Regex validation
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: [\w-]+@([\w-]+\.)+[\w-]+
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.
Action buttons
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 (card-voted-down).
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.
Button styles (beta)
As of SDK version 23.4.0 any button can be styled as a primary or secondary type. By default existing buttons are considered primary. From the card editor choose the overflow menu on a button to toggle between primary and secondary styles. The styles for each button type are configured in the theme editor under 'Top-level card' and 'Subview' 'Button' settings.
Button actions
| Action | Description | Supported button |
|---|---|---|
| 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:
- A URL that the customer is redirected to when submission completes (not currently exposed in the Workbench). For example, https://www.google.com/.
- To direct to a callable link (e.g. phone number), use the prefix tel: . e.g. tel:0123456789
- Payload is 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:
{
"actionDetail": "special-offer",
"activityType": "card-completed"
}
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.
Variables
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 first_name or invoice_number .
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
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.
Variable value
The 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 off.
Required variables
Required variables is currently in beta. Please contact us to provide feedback.
When 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.
Script variables
Script variables is currently in beta. Please contact us to provide feedback.
Be aware of current limitations (such as timestamps being determined server-side at runtime in the UTC timezone). We suggest using simple scripts that are thoroughly tested before using this feature in production.
When creating a variable you can choose to create a 'script' type variable.
Script variables evaluate JavaScript expressions during card assembly. You can use profile variables or any other variable inside this script:
- reference profile variables by using the keyword 'profile', e.g. profile.name.
- reference other variables by using the keyword 'variables', e.g. variables.foo.
- reference data about the card instance that the variable is in by using the keyword 'cardInstance', available data in 'cardInstance' is:
- publishedAt: ISO string date that the card was sent (string)
- expires: ISO string date of the card expiry, present only if the card has been set to expire (string)
- firstSeen: ISO string date that the card was first seen, present only if the card has been seen (string)
- priority: priority of the card (number)
- isTest: true or false, depending on whether the card is a test card or a live card (boolean)
The card feed will automatically refresh once every 60 seconds when WebSockets are in use and a script variable in any of the cards in the feed uses any of the following variables:
- cardInstance.publishedAt
- cardInstance.expires
- cardInstance.firstSeen
This is so that dynamic, time-based variables will automatically update. This makes it possible to create a card that has, for example, text that says "This card was sent 5 minutes ago" which automatically updates as time passes to "This card was sent 6 minutes ago" etc.
You can add script variables exactly like any other variable in the workbench. Select 'script' as type and paste a JS script in the text field. There is a preview to verify the script, as shown in the screenshot below.
Watch the video below to learn:
- how to add a script variable to a card template
- where you can see the script evaluation preview
- how a script variable is shown in a card template
We've collated some sample scripts for inspiration:
Customize a greeting
if (profile.country === 'New Zealand') {
return 'Kia Ora'
}
return variables.defaultGreeting
Get the current day of the week
const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
return days[new Date().getDay()]
Apply formatting conventions based on locale
This example assumes you have already created a variable 'sentCount' containing the number of sent cards. If you want to separate the thousands using a . character and have a decimal comma, you can achieve this using this script:
return Number(variables.sentCount).toLocaleString('de-DE')
Runtime variables
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.
Next steps
See the Sending a card tutorial to learn about sending cards, and customizing the advanced options available.