Customers (Beta)
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:
- Profile: e.g. name, email address, and location.
- Custom fields: any other fields you would like to add. E.g. a “churn risk” score, or their preferred name.
- 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
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:
- Click the
Import
button in the top right. This will open theUpload customers from CSV file
dialogue window. - Click the
information
icon next to the title. This opens an information panel. - Click the
Download a sample csv file
. This csv file contains all of your environment's custom profile fields.
- 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. - 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.
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.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 theProcessing your import
dialogue window, which gives you the option to go to theCustomer 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
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:
- Configuration > API Keys > New key | edit an existing key
- Note the box at the bottom: Map JWT claims data to profile fields (custom fields must be registered in customer settings).
- 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 fieldphone
.
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
Go to: Configuration > > Customer profiles > Tags > New Tag
Give the tag a name.
Select ‘Save’.
Tags can also be added within the Customers area:
Add a Tag to a user in Customers
Select the user(s) you wish to Tag
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 | |
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 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
- 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
- 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
In the Customers area, select the segment you would like to delete.
Then select
Segment
, then selectDelete
.
Custom fields
Custom fields let you add other fields to customers' profiles not contained in user or analytics fields.
Add a Custom field
Go to: Configuration > > Customer profiles > Custom fields > New Field
Give the Field a label (the name will automatically be generated).
Give the field a type: either text or a date.
Select ‘Save’.
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
Create a custom field as described in the custom fields section.
Example: a custom field describing a customer's shopping interests.Update the relevant customers' profile with comma-separated values for this field.
Example: a customer is interested in arts, music and books.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.If you want to include multiple keywords in your segment, you can combine multiple filters using the
match any
ormatch all
dropdown menu.
Example: a segment containing all customers interested in music or art.
- When you filter on a value that contains (part of) another value, both get returned. When you have two values,
men
andwomen
, filtering onmen
will also include all values forwomen
. This happens because the text stringmen
is found within the text stringwomen
. - 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 asart, 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.