Skip to main content

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.

upload-customers-from-csv.png

  1. 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.
  2. 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.

map-fields-and-tag.png

  1. 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.

  2. 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 nameDescriptionCustomer profileUser analytics
External IDoptional free text fieldX
Nameoptional free text fieldX
Emailoptional free text fieldX
Phoneoptional free text fieldX
Cityoptional free text fieldX
Countryoptional free text fieldX
Regionoptional free text fieldX
User typecustomers can either be "test" or "live" depending on whether they are an internal workbench test user or notX
IDAtomic ID; each customer is assigned one when created in AtomicX
Atomic createdtime when customer profile was created in AtomicX
Timezonetimezone where the customer was last seen from any of the SDKsX
First seen attime when customer first interacted with any of the SDKs, based on time of first analytic event received or first successful authenticationX
Last seen attime of last customer activity based on most recent analytics and successful authentication with the SDKX
card-published last seen attime when customer was last sent a cardX
card-dismissed last seen attime when customer last dismissed a cardX
card-completed last seen attime when customer last completed a cardX
card-cancelled last seen attime when customer last cancelled a cardX
card-embargoed last seen attime when customer was last sent an embargoed cardX
card-expired last seen attime when a card last expired for the customerX
card-snoozed last seen attime when customer last snoozed a cardX
card-unsnoozed last seen attime when a card was unsnoozed lastX
notification-sent last seen attime when customer was last sent a notificationX
notification-received last seen attime when customer last received a notificationX
stream-displayed last seen attime when a stream was displayed lastX
card-displayed last seen attime when a card was displayed lastX
card-voted-up last seen attime when a customer last voted up a cardX
card-voted-down last seen attime when a customer last voted down a cardX
runtime-vars-updated last seen attime when runtime variables were updated last for this customerX
snooze-options-cancelled last seen attime when customer last cancelled a card's snooze optionsX
snooze-options-displayed last seen attime when customer last displayed a card's snooze optionsX
subview-displayed last seen attime when a card's subview was displayed lastX
user-redirected last seen attime when a customer was redirected from a card lastX
video-completed last seen attime when a customer last played a video in a cardX
video-played last seen attime when a customer last started a video in a cardX
Last android sdk versionversion of the Atomic Android sdk the customer last interacted withX
Last android deviceAndroid version and device modelX
Last android os versionAndroid versionX
Last android device nameAndroid device nameX
android-seen last seen attime when customer last interacted with the Android sdkX
Last ios sdk versionversion of the Atomic iOS sdk the customer last interacted withX
Last ios deviceiOS version and device modelX
Last ios os versioniOS versionX
Last ios device nameiOS device nameX
ios-seen last seen attime when customer last interacted with the iOS sdkX
Last browser sdk versionversion of the Atomic web sdk the customer last interacted withX
Last browserthe user agent string of the last browser usedX
Last browser namebrowser name of the last browser usedX
Last browser versionbrowser version of the last browser usedX
Last browser osthe operating system the last browser usedX
Last browser os versionthe operating system version the last browser usedX
browser-seen last seen attime when customer last interacted with the web sdkX
card-published first seen attime when customer was first sent a cardX
card-dismissed first seen attime when customer first dismissed a cardX
card-completed first seen attime when customer first completed a cardX
card-cancelled first seen attime when customer first cancelled a cardX
card-embargoed first seen attime when customer was first sent an embargoed cardX
card-expired first seen attime when a card first expired for the customerX
card-snoozed first seen attime when customer first snoozed a cardX
card-unsnoozed first seen atfirst time when a card was unsnoozedX
notification-sent first seen attime when customer was first sent a notificationX
notification-received first seen attime when customer first received a notificationX
stream-displayed first seen atfirst time when a stream was displayedX
card-displayed first seen attime when a card was first displayed to a customerX
card-voted-up first seen attime when a customer first voted up a cardX
card-voted-down first seen attime when a customer first voted down a cardX
runtime-vars-updated first seen atfirst time when runtime variables were updated for this customerX
snooze-options-cancelled first seen attime when customer first cancelled a card's snooze optionsX
snooze-options-displayed first seen attime when customer first displayed a card's snooze optionsX
subview-displayed first seen atfirst time when a card's subview was displayedX
user-redirected first seen atfirst time when a customer was redirected from a cardX
video-completed first seen attime when a customer first played a video in a cardX
video-played first seen attime when a customer first started a video in a cardX
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
  1. 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.

    shopping_interests.png

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

    customer_custom_field.png

  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.

    segment_multivalue_field.png

  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.

    books_or_art.png

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.