Skip to main content

Configuration

SDK​

Streams​

A Stream is a collection of card templates, curated by the workbench member. Atomic is designed to collate multiple cards into a single stream - that stream can include multiple instances of the same card, as well as multiple instances of different cards. In the end, they are all combined into a stream and presented to customers.

You can have many stream containers in your application, and a single card template can also be associated with more than one stream.

Assigning cards to streams is explained in more detail in the Streams and containers guide.

Stream containers​

A Container is embedded in one or more of your apps, rendering a single stream of cards. Containers provide a way for the Atomic SDKs to fetch a particular stream of cards for display. To create a container:

Create a Stream container
  1. From the Configuration section in the workbench sidebar menu, choose 'Stream containers' in the 'SDK' section, then click 'New container'.
  2. Create a name for your container e.g. Homepage Container.
  3. Select the card limit for the container. This defaults to 50.
  4. Select the Stream to present in the container.
  5. Select the theme to style the container.
  6. (optional) Select the dark mode theme to style the container.
  7. Take note of the container ID, you'll need this during SDK installation.
  8. Finally, click on the menu icon at the end of the row displaying your container, and select 'Manage client keys' then select the Client key you configured earlier.

Notifications​

Add and manage notification platforms here, so your customers can receive native mobile notifications on iOS and Android.

Add push notification credentials

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.

Container themes​

Add customizable style across streams, cards, and card elements.

Add a Container theme
  1. From the Configuration section in the workbench sidebar menu, choose 'Container themes'.
  2. Click the 'SDK' tab
  3. Click 'Add theme' button.

API host​

Where you can configure your SDK integration to interact with Atomic.

API keys​

When you install Atomic's SDKs, you'll need to setup a way of generating signed authentication tokens (JWTs) to Atomic. Atomic needs to verify these tokens, using a public key you save into the Workbench.

Before continuing the below steps to add an API key, make sure you have completed Steps 1 & 2 of Getting Started in the Authentication section.

Add an API Key
  1. From the Configuration section in the workbench sidebar menu, choose 'API Keys'.
  2. Click 'New Key'
  3. Add the name, type, JWKS config, then select 'Add'.

API​

Base URL endpoint​

The base URL for interacting with your Environment via the Atomic API.

Authentication controls​

Here you can manage your client ID and client secret API Credentials.

  1. From the Configuration section in the workbench sidebar menu, choose 'Authentication controls'.
  2. Click 'New Credential'.
  3. Add the role (Workbench, Events, Auth). Which role is needed, depends on the API request you're making. This is explained in API credential roles.
  4. Give it a name that reflects who is making the API request. This could be people (e.g. QA engineers) or systems you're integrating with (e.g. Salesforce-staging). Atomic does not impose any restrictions on the name and you can always edit the name later.
  5. Select 'Add' - you now have access to the client ID and client secret that is required to authenticate your API requests.

When an API credential is no longer required, you can delete it in this same view. Any API requests using a deleted credential, will fail.

API credentials are available to every workbench member in the environment with the right permissions.

Permission required

Access to this workbench resource is controlled with a specific "API Authentication control" permission. See the Permissions guide to configure this permission for your workbench members.

Card templates​

Approvals​

Beta release

Approvals is currently in beta. Please contact us to provide feedback.

Approvals is an optional configuration that requires cards to be approved before they can be published. If Approvals are not configured, then card templates can be published by any workbench member who has admin permissions on the card template resource.

To set up approvals, you need to do the following:

  1. Create an approval group and assign workbench members to it.
  2. Configure the approval process

Any subsequent publishing of the new draft versions will be subject to the current approval requirements.

Create an approval group and assign workbench members to it​

Creating groups is explained in detail in the Group section of the preferences page.

You first need to create one or more roles that you can then assign to the group of approvers.

Add the role​

Card Template Edit

First add a role that gives permission to view card templates.

Click your avatar in the top right corner > Workbench members > Roles, then select ‘Create a new role’.

Name the role, and give it a clear description. For example:

  • Title: Card Approvers
  • Role description: Role access for card approvers to be able to see card templates

Give it access to the Card template resource, with View level of access.

Select ‘Create role’.

Add the role to a group​

Now create a workbench member group for each unique area of your business that needs to approve a card before publishing. For example, legal, data, and product teams.

Click your avatar in the top right corner > Workbench members > Groups, then select ‘Create a new group’.

Name the first group, and give it a clear description. For example:

  • Title: Card Approvers — Legal
  • Group description: A group for members of our legal team who can approve cards

Now give this group access to the Role created in stage one: the 'Card Approvers' role.

Configure approval permission to only some environments using Permissions

Repeat this step for each group of Workbench members who need to approve cards. For example, you may like to add a group called 'Card Approvers — Data' and 'Card Approvers — Product' also.

Add workbench members to approval group(s)​

When inviting new members into the workbench, you’ll now be able to add them to any of the new approver groups.

If you already have workbench members in your environment, you can now add them to the appropriate group.

Click your avatar in the top right corner > Workbench members, and in the ‘Workbench members’ tab select the member you wish to edit, and then check the box next to the appropriate Group from step 2. See more at Preferences

2. Configure the approval process​

Go to Configuration > Card Templates > Approvals, and toggle 'Require card approvals' on.

Approvals configuration

Next select all of the groups who are required to approve cards, and select ‘Update’.

The approvals configuration screen enables you to specify one or more groups that need to approve the card before it can be published. If you select multiple groups, each of these groups needs to approve the card template. If a workbench member belongs to multiple approval groups, they can select on behalf of which group(s) they are approving.

Optional configuration setting: Add card approval override capability​

It is possible to give someone permission to approve card templates without having all necessary approvals in place, so cards can be approved in a time of extreme urgency.

This can be done by giving Admin permissions on the Approval Override permission.

Approval Override

Customer profiles​

Read more about Customers.

Custom fields​

Create custom fields that match your Customer's data. These fields will be available to view, edit, and filter.

Add a Custom field
  1. From the Configuration section in the workbench sidebar menu, choose 'Custom fields'.
  2. Click 'New Field'
  3. Add the label, name, and type, and select 'Add'.

Tags​

Edit tags which are available when filtering customers.

Add a Tag
  1. Go to: Configuration > > Customer profiles > Tags > New Tag
  2. Give the tag a name.
  3. Select ‘Save’.

Webhooks​

Subscriptions​

View and manage all webhook subscriptions for your application.

Note: individual card webhook subscriptions can also be see managed within each card editor.

Webhook request log​

Beta feature

The Webhook request log is currently in beta.

In the overflow menu of the webhook subscriptions list there is an option to view the subscription's "Request log". Clicking this option will open a new tab showing details of the requests triggered by this webhook subscription. Selecting one of the log entries will populate the screen with information including the target URL and the request and response data. Request and response data is redacted for requests that are not marked as being a test (triggered by the "Send test" button).

Webhook credentials​

Manage credentials used to authenticate outgoing webhook requests.

There are three credential types which are currently supported, AWS signed request, OAuth client credentials and basic auth.

Add webhook authentication credentials
  1. Go to: Configuration > Webhooks > Webhook credentials.
  2. Select 'New credential'.
  3. Add details for the new credential.
  4. Select ‘Save’.

OAuth client credentials​

The OAuth client credentials flow supports two request schemes:

Body parameters

Example of an equivalent request using curl. Credentials are urlencoded and sent in the request body.

curl --location --request POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_secret=MY_CLIENT-SECRET' \
    --data-urlencode 'client_id=MY_CLIENT_ID' \
    --data-urlencode 'scope=MY_SCOPE'
URL query parameters

Example of an equivalent request using curl. Credentials are encoded using query parameters.

curl -request GET 'http://my.auth.com/oauth2/v2.0/token?grant_type=client_credentials&client_secret=MY_CLIENT-SECRET&client_id=MY_CLIENT_ID&scope=MY_SCOPE'

AWS Signed Request​

Authenticate a request with AWS IAM, this allows webhooks to interact with AWS services. We recommend creating a bot user in AWS with IAM policy access granted only as-required for use with this credential-type.

  • Access key ID: the ID of the access key associated with the AWS IAM user.
  • Secret access key: the secret access key associated with the AWS IAM user.
  • Sign query: optionally sign the request query instead of adding an Authorization header.
  • Session token: optionally provide the session token to use IAM STS temporary credentials.

Basic auth​

Adds an Authorization header containing the provided username and password encoded as per the standard pattern.

Analytics export settings​

Configure the data included in analytics exports:

  • Test cards
  • Request payload
  • Card response data

These settings are explained in detail in the Analytics data preferences section of the Analytics guide.

Testing​

Test accounts​

Create and manage test accounts for your SDK integrations.

You may also want to add test accounts in order to test the look and feel of your Cards on your own devices. For more information, see the Testing a card section.

Read more about adding test accounts in the sending cards tutorial.

Last updated on