Skip to main content

Authoring cards

Before you start

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

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.

  1. Navigate to the Cards section of the Workbench:

cards_section.png

  1. Then select the the card you wish to edit:

open_card.jpg

Duplicate a card

Duplicate a card by selecting the overflow menu (3 vertical dots) on the right of the card's name, and then Duplicate card.

  1. Or to create a new card from scratch, select New card:

new_card.jpg

By default you land in the Content section of the Card. This is where you add elements, such as text, images, and buttons.

editor.png

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.

  1. Use the Preview dropdown to change the preview of the card to use a different theme.
Learn more

Learn more about editing and configuring themes in our Theme Editor tutorial.

Publishing cards

There are 6 states a card template can be in:

  1. 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.
  2. Awaiting approval : Card templates that are pending approval cannot be edited unless the approval request is cancelled.
  3. Approved: Once approvals are given, the card can be published by anyone with admin permission to the Card template resource.
  4. 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.
  5. 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.
  6. 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

Card design principles

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.

Learn more

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:

new_subview.png

Subview content

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.

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

media_element.jpg

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.

Atomic supports 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.

Image formats

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.

validation.png

ElementDescriptionValidation optionsViews
Date pickerAllowing the customer to select a day, month and year from a platform-specific picker UI.Maximum date, Minimum date, RequiredDefault value, Label, Placeholder, Stacked | Inline, Thumbnail
DropdownA dropdown in the chosen format, allowing the customer to select from a list of pre-defined values.RequiredDefault value, Label, Placeholder, Stacked | Inline, Thumbnail
StepperAllows the customer to step up and down between a minimum and maximum value.Maximum value, Minimum value, RequiredDefault value, Label, Maximum value, Minimum value, Step value, Thumbnail
SwitchAllows a customer to provide a binary response.Label, Thumbnail, default, on /off
Text blockA body of text, supporting Markdown formatting and an optional icon on its left.Icon, Text
Text inputAllows a customer to provide a single or multi-line text response.Maximum length, Minimum length, Regular expression, RequiredDefault value, Label, Number of lines,Stacked | Inline,Thumbnail
Number inputRenders a single line input that allows only numeric values (integer or decimal).Maximum value, Minimum value, RequiredDefault 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

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 name in 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 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-]+

regex.png

Using our API

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

action_button.png

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:

  1. Submit: the card is submitted when the customer taps or clicks it.
  2. Link: the card persists when the customer taps or clicks it. A subview is triggered, or an external URL is launched.
  3. Dismiss: the card is dismissed when the customer taps or clicks it.
  4. Snooze: the card is snoozed when the customer taps or clicks it, which means it is no longer visible in the card stream.
  5. Vote up: the card persists when the customer taps or clicks it. A corresponding analytics event (card-voted-up) is sent for that card.
  6. 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 actions

ActionDescriptionSupported button
ValuesSent with the response when a submit button is triggered.Submit
SubviewWhere additional information is displayed and can be collected.Link
URLWhere the customer is navigated to when submission completes.Link,Submit
PayloadUsed 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.

icons.png

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 .

variables.png

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.

conditional.png

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.

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.

Learn more

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 customising the advanced options available.