Skip to main content

Cards

The Cards area in the Workbench is where you author and manage card templates.
This guide explains the different tabs in the Card editor, it also explains where to find Card Analytics and how to send test cards.

Content​

Creating a new card template and adding content (such as text, media and action buttons) is explained in detail in the Authoring cards tutorial. This tutorial also covers the possible states a card template can be in, and how to publish a template.

Variables​

Working with variables in your card templates is explained in detail in the Authoring cards tutorial.

Triggers​

You can view and manage the different triggers that are used to send cards in the Triggers tab of the Card template.

API start trigger​

This is a URL you can use when using API requests to send this card. Read more about making API requests in the Action Flow API guide.

Segment triggers​

You can send cards when customers enter or exit a segment. Read more about this in the Segment triggers section of the Sending cards tutorial.

Connector triggers​

You can send cards using the connector API endpoint. You can add mappings or scripts to connectors to change the incoming payload to a shape that Atomic can work with, making it easier to integrate with third party tools. Read more about this in the Connector triggers guide.

Notifications​

You can send a native notification to a mobile device: iOS, Android, React Native, Flutter or Cordova/Ionic.

Note: notifications are not currently supported in the Web SDK, except when embedded in a native mobile app. Contact us if you'd like us to support notifications for web.

Before using native notifications, you must first add push notification credentials to the workbench. We've added credentials for the Atomic demo apps, but if you would like to integrate with your own staging app, or when you move to production, you'll need to add your own apps' credentials

Add push notification credentials to the Workbench

You must have access to the 'Notification Platform' resource to be able to add notification credentials. See more in Workbench members

  1. Open the Atomic Workbench, navigate to 'Configuration' and under SDK select 'Notifications'.
  2. Click 'New platform', and select either 'iOS' or 'Android'.
  3. Enter the required information to register the corresponding platform:
  • For iOS,
    • Certificate Authentication: you require your app's bundle ID, a P12 export of your push notification certificate and private key, and the password for the P12 export if applicable.
    • Token Authentication: you require your apps bundle ID, a p8 export of your signing key, a signing key id and a team identifier.
  • For Android, you require your app's ID and your server key for push notifications.

You will also need to configure your host app for push notifications. For more information, see the relevant SDK documentation for Android and iOS.

Adding a notification to a card

Within the card, navigate to 'Notifications' and enable native notifications. In this section you can also configure the notification title and message.

Delivery​

The Delivery area is where you can set default delivery and/or expiration times for cards. You can also change card priority and assign the card to one or more streams.

You can schedule cards for a delivery time in the future, or set a time for the card to expire. Either:

  1. An absolute time/date, or
  2. A countdown timer e.g. 30 mins.

The delivery options can be overridden in the API request payload, as described in the Action Flow API guide.

Streams​

This section is where you can select the stream(s) the card will be sent to when using the Action Flow API. Read more about how to assign cards to streams in the Streams and containers guide.

Scheduling​

Read more about using the API to set delivery times in the Date and Time Reference.

Scheduling enables you to set a delivery time for the card at an exact date and time in the future. Specifying a time is done based on UTC time.

For example, if your timezone offset is +12:00 and you want the card to be sent at 8.15am in your timezone, then you would set the time to 8.15am and the offset to +12:00.

If a delivery time is scheduled in the past, then it will be ignored and the cards are sent immediately.

UTC offset and daylight savings

Specifying a time is done based on UTC time, so you need to allow for daylights savings changes, to match your target customers' timezone. New Zealand is UTC+12:00, but UTC+13:00 in daylights savings (from the last Sunday in September at 2.00am to the first Sunday in April at 3.00am). Victoria, Australia is UTC +10:00, but UTC+11:00 in daylights savings (from the first Sunday in October at 2.00am to the first Sunday in April at 3.00am).

Expiry​

If not yet actioned, expiry allows you to expire a card instance. You can add either an exact date and time, or a time relative to the delivery time (i.e. a countdown timer):

Expire at absolute date & time

The card expires at an exact date and time.

Expire relative to delivery

Select the time in days, hours and/or minutes you wish the card to remain available to the customer for, relative to the delivery time (i.e. a countdown timer).

Absolute time prevails

If both relative and absolute times are completed, Atomic will respect absolute times.

Expiring cards using the API

If using the API, use ISO86001 formatting to specify relative expiry durations. See more: Duration formats.

Prioritization​

Adding prioritization to a card enables you to show the most relevant and urgent cards at the top of the feed.

Default priority

By default cards are ordered by the recency of the card being sent to the customer (or coming out of snooze), with the most recent cards shown on the top of the feed.

There are two ways to configure priority: in the Workbench within a card template, or in the payload of an API request. Any value provided in the Workbench can be overridden via API, as described in the Action Flow API guide.

The priority value can be any number between 1 and 10, with 1 being the highest priority, and 10 being the lowest priority. Cards with higher priority appear higher in the card feed.

For example a card with priority 2 will be ordered above a card with priority 4. If no priority is supplied, the default priority is 5.

An individual customer can be sent a unique prioritization value, so you can set card priority depending on your customer.

Add priority in the Workbench​

Within the card, select the 'Delivery' tab.

Platforms​

By default, cards will be displayed on all platforms: Web, Android & iOS. With this setting it is possible to configure cards to be displayed on only a subset of these platforms. If no platforms are selected, or all platforms are selected then the card will be displayed on all platforms.

The platform options can be overridden in the API request payload, as described in the Action Flow API guide.

Webhooks​

Webhooks can be configured for any of the events listed in the analytics events section, for example card-dismissed or card-published. The payload data of these webhooks is very similar to the analytics data. An important difference is that environment analytics data preferences affect API responses, but not webhooks.

Webhooks get the full analytics payload by default, this can be changed by selecting the "edit mapping" option after creating a webhook subscription, as explained in the webhooks mapping section below.

To create a webhook subscription:

  1. Click the "add webhook subscription" button in the webhooks tab of the card template.
  2. Select the events the webhook subscription should listen to, what request method should be used and what the webhook endpoint (URL) is. All of these details are mandatory.
  3. Optionally, you can give the webhook subscription a name, you can specify headers and add credentials to use when making requests to the webhook endpoint.

The Webhooks API section has more information about webhook delivery retries.

Webhook mappings (beta)​

Beta Feature

This feature is still in Beta.

Webhook payloads are identical to the full analytics payload by default. You might want to map the default payload to match the required format of an integration backend. The mapping editor can be used to view an example payload and to test custom payloads.

You can access the mapping editor by selecting the "edit mapping" option after creating a webhook subscription as described in the webhooks section above.

You can select the Load sample script button to give you an example of how you can map the payload. The raw payload section shows the full analytics payload; the available properties section repeats this in JSON dot notation. The result section shows the payload as it will look like after applying the script.

You can use the Send test button to send a payload as shown in the result section, to the URL you provided when creating the webhook.

Once you've finalized the payload mapping, click the Save button.

The screenshot below shows an example where the analytics payload for a card-completed event is mapped to a payload containing just 3 properties.

Log​

The card 'log' tab presents information on the cards sent. For example, the status of cards sent.

Note: Live data (API request payloads or customer responses) are not presented within the Workbench.

  • There are two possible sources:
    • 'Live': cards sent to customers.
    • 'Test': cards sent to test users (in the 'Customers' area these users have a 'test' label against their name).
  • The 'status' of the card can be either:
    • 'active': sent to the customer, but not yet actioned.
    • 'completed': actioned by the customer.
    • 'dismissed': the customer has dismissed the card.
    • 'canceled': the card was canceled by the sending of a cancel request to the Atomic API.

Read more about the 'status' of a card instance in the Card lifecycle model guide.

Card analytics​

This feature is currently in 'Beta' - read more about it in the Insights section.

Send Test Cards​

The Send cards tutorial offers a detailed explanation on how to send test cards.

Last updated on