Customers (Beta)

beta release

The Customers feature is currently in beta. Contact us to provide feedback.

Our Customers area is where you can view and manage customers so you can send targeted and personalized messages.

You can access it by selecting 'Customers' in the left hand sidebar.

There are three types of fields associated with each customer:

1. Profile: e.g. name, email address, and location.
2. Custom fields: any other fields you would like to add. E.g. a “churn risk” score, or their preferred name.
3. Analytics fields: e.g. when the customer was last seen, when the customer last completed a card, and the customer’s operating system.

The only required field for a customer is their unique customer ID. All other fields are optional.

Once added to Atomic, analytics fields will automatically be populated, including things such as the timezone they were last seen in, their operating system, and the time they last completed a card.

Managing customers

Customers can be managed via API or manually in the Workbench.

Add or update customers via CSV

CSV file limits

Make sure your CSV file:

• is smaller than 128MB in size
• has less than 100 columns
• has less than 50,000 rows

From the Customers screen, follow these steps:

1. Click the Import button in the top right. This will open the Upload customers from CSV file dialogue window.
2. Click the information icon next to the title. This opens an information panel.
3. Click the Download a sample csv file. This csv file contains all of your environment's custom profile fields.

4. Update the sample csv file with actual customer data. The only required property in the CSV file is the id column, but you can provide any other profile or custom fields. Where a customer already exists (with a matching user ID), the properties of that customer will be updated with the data provided by the CSV.
5. Upload the file and check the if the fields match your data correctly. If they do not, you can select the correct field from the column header dropdown.

6. You can edit the name of the tag that will applied to all customers in this upload. You can prevent it being added before uploading by toggling the tag records switch to off. You can also select 1 or more existing tags to be applied. Read more about using tags in the Tags section.

7. Once you've configured the fields that will be imported and the tag(s) that will be applied, you click the import records button. This will open the Processing your import dialogue window, which gives you the option to go to the Customer data importer to track progress of the upload.

Manage customers via API

Using our API you can add new customers, update or delete existing customers, or retrieve a list of all customers.

Before you can begin using the Users API, ensure you have an ‘Events’ credential role.

Learn about the different credential roles and how to add them at: API Credential Roles

Pass customer data via auth token

Preview release

Passing customer data via auth token is currently in preview release. Contact us for access or to provide feedback.

Rather than hitting the customer API separately to update customers, you can pass information with the auth token. To use it go:

1. Configuration > API Keys > New key | edit an existing key
2. Note the box at the bottom: Map JWT claims data to profile fields (custom fields must be registered in customer settings).
3. This is where you map the fields you wish to add. e.g. {"city":"city", "ph":"phone"}. This maps the token data to custom fields. i.e. ph in the token here is mapped to the customer field phone.

Tags

A tag creates a way for you to manually group your customers. For example, customers that became customers following a specific promotion, those that are VIPs, customers uploaded in a specific batch, or those who attended an event.

Unlike Segments, tags are not automated for you: the only way a user can have a tag added or removed is manually or through API.

You can add new tags directly in the Workbench when adding a tag to a user, or add a new user tag in preparation for applying them to customers.

Once a tag exists, you can manually add it to a user in the Workbench or via API.

Add a Tag

1. Go to: Configuration > > Customer profiles > Tags > New Tag

2. Give the tag a name.

3. Select ‘Save’.

Tags can also be added within the Customers area:

Add a Tag to a user in Customers

1. Select the user(s) you wish to Tag

2. Select ‘Tag user’, and select the tag you wish to add (or name a new tag) and select ‘Save’.

User tags can be added, removed, or retrieved via API. See Users API.

Segments

A Segment creates a shortcut for targeted messaging of user groups. The segment is defined by filters that you select.

Unlike Tags where customers are added to the group either manually or via API, customers enter and leave a Segment dynamically based on the filter conditions being met (or not). For example, if a user was last seen in a specific country or if they have not completed any cards for a specified time period.

You can set up segments based on any customer field, including custom fields. The table below offers an overview of the customer profile and user analytics fields that can be used.

Field name	Description	Customer profile	User analytics
External ID	optional free text field	X
Name	optional free text field	X
Email	optional free text field	X
Phone	optional free text field	X
City	optional free text field	X
Country	optional free text field	X
Region	optional free text field	X
User type	customers can either be "test" or "live" depending on whether they are an internal workbench test user or not	X
ID	Atomic ID; each customer is assigned one when created in Atomic		X
Atomic created	time when customer profile was created in Atomic		X
Timezone	timezone where the customer was last seen from any of the SDKs		X
First seen at	time when customer first interacted with any of the SDKs, based on time of first analytic event received or first successful authentication		X
Last seen at	time of last customer activity based on most recent analytics and successful authentication with the SDK		X
card-published last seen at	time when customer was last sent a card		X
card-dismissed last seen at	time when customer last dismissed a card		X
card-completed last seen at	time when customer last completed a card		X
card-cancelled last seen at	time when customer last cancelled a card		X
card-embargoed last seen at	time when customer was last sent an embargoed card		X
card-expired last seen at	time when a card last expired for the customer		X
card-snoozed last seen at	time when customer last snoozed a card		X
card-unsnoozed last seen at	time when a card was unsnoozed last		X
notification-sent last seen at	time when customer was last sent a notification		X
notification-received last seen at	time when customer last received a notification		X
stream-displayed last seen at	time when a stream was displayed last		X
card-displayed last seen at	time when a card was displayed last		X
card-voted-up last seen at	time when a customer last voted up a card		X
card-voted-down last seen at	time when a customer last voted down a card		X
runtime-vars-updated last seen at	time when runtime variables were updated last for this customer		X
snooze-options-cancelled last seen at	time when customer last cancelled a card's snooze options		X
snooze-options-displayed last seen at	time when customer last displayed a card's snooze options		X
subview-displayed last seen at	time when a card's subview was displayed last		X
user-redirected last seen at	time when a customer was redirected from a card last		X
video-completed last seen at	time when a customer last played a video in a card		X
video-played last seen at	time when a customer last started a video in a card		X
Last android sdk version	version of the Atomic Android sdk the customer last interacted with		X
Last android device	Android version and device model		X
Last android os version	Android version		X
Last android device name	Android device name		X
android-seen last seen at	time when customer last interacted with the Android sdk		X
Last ios sdk version	version of the Atomic iOS sdk the customer last interacted with		X
Last ios device	iOS version and device model		X
Last ios os version	iOS version		X
Last ios device name	iOS device name		X
ios-seen last seen at	time when customer last interacted with the iOS sdk		X
Last browser sdk version	version of the Atomic web sdk the customer last interacted with		X
Last browser	the user agent string of the last browser used		X
Last browser name	browser name of the last browser used		X
Last browser version	browser version of the last browser used		X
Last browser os	the operating system the last browser used		X
Last browser os version	the operating system version the last browser used		X
browser-seen last seen at	time when customer last interacted with the web sdk		X
card-published first seen at	time when customer was first sent a card		X
card-dismissed first seen at	time when customer first dismissed a card		X
card-completed first seen at	time when customer first completed a card		X
card-cancelled first seen at	time when customer first cancelled a card		X
card-embargoed first seen at	time when customer was first sent an embargoed card		X
card-expired first seen at	time when a card first expired for the customer		X
card-snoozed first seen at	time when customer first snoozed a card		X
card-unsnoozed first seen at	first time when a card was unsnoozed		X
notification-sent first seen at	time when customer was first sent a notification		X
notification-received first seen at	time when customer first received a notification		X
stream-displayed first seen at	first time when a stream was displayed		X
card-displayed first seen at	time when a card was first displayed to a customer		X
card-voted-up first seen at	time when a customer first voted up a card		X
card-voted-down first seen at	time when a customer first voted down a card		X
runtime-vars-updated first seen at	first time when runtime variables were updated for this customer		X
snooze-options-cancelled first seen at	time when customer first cancelled a card's snooze options		X
snooze-options-displayed first seen at	time when customer first displayed a card's snooze options		X
subview-displayed first seen at	first time when a card's subview was displayed		X
user-redirected first seen at	first time when a customer was redirected from a card		X
video-completed first seen at	time when a customer first played a video in a card		X
video-played first seen at	time when a customer first started a video in a card		X

Timestamps for user analytics fields

Timestamps are shown in the workbench member's local timezone. When creating a segment based on time, it gets converted to UTC time in the backend. This means that even organisations with workbench members in different timezones will have consistent segments.

When a customer exits or enters a segment the segment-entered or segment-exited events are emitted. These events are available in the analytics data. It is also possible to configure webhooks to send the event payload data to a URL you specify when the events are emitted.

Create a Segment

1. From the list of customers, filter customers based on either:

• A profile field, including advanced filtering such as equals, contains, greater than etc.
• A tag

2. Then select Save segment, and give the segment a name.

When customers are updated through API or CSV, customers will automatically enter the new segment if they meet the criteria specified.

Once created, existing Segments are easily accessed by selecting the tab in the primary Customers view.

The GET /v1/:environmentId/user API response includes the list of segments a customer belongs to. More information can be found in the Atomic API section of the documentation.

Delete a Segment

1. In the Customers area, select the segment you would like to delete.

2. Then select Segment, then select Delete.

Custom fields

Custom fields let you add other fields to customers' profiles not contained in user or analytics fields.

Add a Custom field

1. Go to: Configuration > > Customer profiles > Custom fields > New Field

2. Give the Field a label (the name will automatically be generated).

3. Give the field a type: either text or a date.

4. Select ‘Save’.

5. The Field is now created, and so customer profiles can have the field updated manually or via API.

You can retrieve and delete custom fields via API. See Users API.

Multiple values in custom fields

A custom field of the type text can have more than 1 value, separated by commas. These values can be used to filter on, and create segments.

Create a segment based on multiple values in a custom field

1. Create a custom field as described in the custom fields section.
   Example: a custom field describing a customer's shopping interests.

   

2. Update the relevant customers' profile with comma-separated values for this field.
   Example: a customer is interested in arts, music and books.

   

3. Create a filter based on the custom field by using the contains condition and one keyword.
   Example: a filter for all customer interested in music.

   

4. If you want to include multiple keywords in your segment, you can combine multiple filters using the match any or match all dropdown menu.
   Example: a segment containing all customers interested in music or art.

   

Limitations of applying filters to multiple values custom fields

• When you filter on a value that contains (part of) another value, both get returned. When you have two values, men and women, filtering on men will also include all values for women. This happens because the text string men is found within the text string women.
• If you use multiple keywords in 1 filter, the results will be limited to cutomers with those values in that exact order. A filter for books, art will not return the same results as art, book. Using a combination of multiple filters (as described in the section above) is the recommended approach.

Send a card

Before you send a card to customers you will need to have a card configured. See creating a card template for how to do this.

The Sending cards tutorial describes in detail how to send cards, while the Sending cards advanced guide describes the different card delivery options.