Universal data connector API

Public API credentials This API allows you to send your own segmentation data directly in AB Tasty for its usage in our platform. If you are a partner and want to build a program with AB Tasty, please contact us at [email protected]

Introduction

Using our Universal Data Connector API, you will be able to send AB Tasty segmentation data. This data can come from a DMP, a CDP, a CRM, a datawarehouse, a database or a one time file extract. This data can be used to create a custom segment using our targeting engine. This allows the AB Tasty tag to trigger the custom personalization campaigns you have created.

The sent data will be stored for 30 days in our system once received by default.

Quick Start

Here are the steps:

• get an access with the dedicated role from our Public API (contact the administrator of your AB Tasty account)

• setup the recurring call to our API with the appropriate file format as described below

• that's all, everything else is already in AB Tasty!

Authentication

Create a user for the public API in your AB Tasty account with at least the "Send and get third party segments" role.

This will give you your credentials. Use these credentials each time you want to authentify to the Public API to get a token.

Upload segments information

To upload the file containing all segmentation information, use this route:

POST https://api-data-connector.abtasty.com/accounts/{account_identifier}/segments/{partner_name}

Curl template:

curl -v -X POST --data-binary "{file_location}" \
  -H 'Authorization: Bearer {public_api_oauth_token}' \
  -H 'Content-Type: {content_type}' \
  "https://api-data-connector.abtasty.com/accounts/{account_identifier}/segments/{partner_name}"

Requirements

Name	Requirements	Type	Description	Accepted Values
file_location	\s+	string	Name of the file to be posted
account_identifier	\s+	string	Identifier of the account
public_api_oauth_token	\s+	string	Valid public API Oauth token
content_type	\s+	string	Content-type of the uploaded file	text/csv, application/json
partner_name	\s+	string	ID of the account	best3rdparty, awesomeTool, ...

The "parter name" can also be your own brand name if you're not getting the segments from a third party. This field is customizable and only serve the purpose of identify a data source for your segments.

File format

Name	Required	Validation Regex	Type	Description
visitor_id	true	(?i)^[a-z0-9-]{1,32}$	string	Visitor ID, as provided by the client
value	false	(?i)^([[:alnum:]]|[$€£\[\]{}&(§!)\-_%=+:/.?<>@#]|[À-ÿ]){1,100}$	string	Segment value
segment	true	(?i)^([[:alnum:]]|[$€£\[\]{}&(§!)\-_%=+:/.?<>@#]|[À-ÿ]){1,100}$	string	Segment name
expiration	false	\d+	timestamp	Time at which this segment information will be deleted by ABTasty, default and maximum is 30days. The -1 value will delete the record.

Example request:

curl -v -X POST --data-binary "@segments.csv" \
  -H 'Authorization: Bearer 0MWQ4MjRlMNzY5ODFjODYwNTU2YTBkMThiMjk2NzNlYzNiOAMTJkOTEyZjNhYzQzTE0YzRkM2UyNDk4NWE1MTY' \
  -H 'Content-Type: text/csv' \
  "https://api-data-connector.abtasty.com/accounts/83cb13aabbfc8e879084f3a0bcdcb4f3/segments/partnerName"

Example segments.csv file content

visitor_id;value;segment;expiration
19102009415591439;SEGMENT_1_VALUE_1;SEGMENT_1;1609136172230
j73xvgwb5yz9re9f;SEGMENT_1_VALUE_2;SEGMENT_1;1609136172230
19051217151193693;SEGMENT_2_VALUE_1;SEGMENT_2;1609136172230

You can also send the content directly in the body of your request.

The request will return a 200 json response if successful with a link to a Public API route to check the upload state

Example response

{
    "success":true,
    "state_link":"https//api.abtasty.com/v1/accounts/83cb13aabbfc8e879084f3a0bcdcb4f3/dmp-files/42"
}

calling the "state link" requires a valid Public API Oauth token

Status Codes

Status code	Description
202	Returned when the upload was succesful
400	Returned when the file is empty or invalid
403	Returned when the token is either invalid or doesn't have the proper permissions
404	Returned when the route was malformed (missing required parameter)
413	Returned when the request is too large, file should be maximum 20 * 1024 * 1024 Bytes
415	Returned when the content type is wrong, only application/json and text/csv files are accepted

Get a visitor's segment list from the web

To get a specific visitor's segment in JavaScript, you can call the following URL:

https://api-data-connector.abtasty.com/accounts/{identifier}/segments/{visitor_id}

It is much more convenient and faster to use.

Limits

Maximum rows of a file

You can send up to 100,000 rows at once, or 20 MB. The same limit applies if you send the data directly in the payload of the request instead of in a file.

Maximum concurrent files

You can send as many files as you need, they will be queued up and processed in their order of arrival. This is the best way to work with the 100k rows limit.

Time to process a file

A large file, close to the limits, will take minutes to be processed. A smaller file will be processed almost instantly. If your data doesn't show up within 10 minutes, we advise you check your request before trying again.

Use case with JavaScript

You can build up the connection using native features of AB Tasty: the account JavaScript and a code targeting in each campaign. You will only need two snippets templates:

• the first one, in the AB Tasty account global code, makes the call to the API,

• the second, in the campaign code targeting, checks the answer of the API to decide whether the tag should play the campaign or not.

Doing the API call

A custom script set in the account global code will be executed at the very beggining of the tag execution as soon as there is at least one live campaign.

We are going to leverage this opportunity to connect to the API (example of code in AB Tasty global code):

const url = `https://api-data-connector.abtasty.com/accounts/${window.ABTasty.accountData.accountSettings.identifier}/segments/${localStorage.getItem('ABTastyUDC')}`;

fetch(url, { method: 'GET', mode: 'cors', headers: { Origin: document.location.origin } })
  .then((data) => data.json())
  .then((data) => sessionStorage.setItem('ABTastyUDC', JSON.stringify(data)))
  .catch(() => console.log('Unable to fetch UDC'));

This snippet asks the API to match the visitorId sent as parameter to its corresponding segment value. For this example, we assume the visitorId is stored in the localStorage in the ABTastyUDC entry.

Adjust this snippet to your needs.

Targeting on a segment

For each campaign, you can create a JS code trigger. Create a new trigger or go for a custom one and select "Code". In the scripting area, you can put your targeting code.

Example of code in an AB Tasty campaign's code targeting:

return !!sessionStorage.getItem('ABTastyUDC') && JSON.parse(sessionStorage.getItem('ABTastyUDC'))[0].segment === "SEGMENT_1";

This snippet looks for the value stored in the sessionStorage that was filled by the previous API call. If the value is equal to SEGMENT_1, then the script returns true and the campaign will launch.

Adjust this snippet to your needs.