Overview
This document describes how you can integrate Tagalys with your custom ecommerce store / platform.
Accessing your API credentials
{
"api_server": "https://api-rx.tagalys.com",
"client_code": "JFJ39R9VJW929DJF",
"public_api_key": "hdu28fh37f8238idi29djdu38fifjhe8",
"private_api_key": "j2jdhw9e837chs920dh6cu2hd28dhd2u"
}
Log in to your Tagalys account at https://next.tagalys.com. In the landing page (if this is your first visit and products are not synced yet), or via the Integration link, your API credentials are listed as a JSON object. This includes the following information:
Parameter | Description |
---|---|
api_server |
Protocol and hostname for our API server in your selected region. You should direct all API calls to this origin. In this document we will use https://api-rx.tagalys.com as an example. |
client_code |
The main identifier for your Tagalys account |
public_api_key |
A key that allows access to all our front-end APIs. Only this key should be used in contexts where it may be exposed to your visitors (for example, when making client side API calls directly to Tagalys as is the case when you use our JS plugin). |
private_api_key |
A key that allows access to admin / setup APIs. This allows modifiying your products database, product listing pages etc. It should never be exposed to any untrusted party. |
Making API calls
curl -X POST \
https://api-rx.tagalys.com/v1/endpoint \
-H 'Content-Type: application/json' \
-d '"JSON Content"'
The Tagalys API works via POST endpoints that accept data in JSON and FormData formats and responds in JSON format.
Authentication & Identification
{
"identification": {
"client_code": "JFJ39R9VJW929DJF",
"api_key": "j2jdhw9e837chs920dh6cu2hd28dhd2u",
"store_id": "store_id",
"currency": "currency_code"
}
}
The identification
key is required for all Tagalys API calls. It should contain the following parameters:
Parameter | Description |
---|---|
client_code |
Client code from your API Credentials. Required for all API calls. |
api_key |
Required for all API calls. Which API key you use will depend on the endpoint you call. Use your private key for Configuration, Product Sync APIs and your public key for all front-end and analytics APIs. |
store_id |
Tagalys supports multi-store setups, and this parameter sets the store context for the call. Required for all API endpoints except Configuration (in which you define your stores and store IDs). |
currency |
Required for all front-end APIs where the default currency is not being used |
Configuration API
{
"identification": {...},
"stores": [
{
"id": "1",
"label": "English",
"locale": "en_US",
"timezone": "America/Los_Angeles",
"multi_currency_mode": "exchange_rate",
"products_count": 21532,
"currencies": [
// see subsection
],
"fields": [
// see subsection
],
"tag_sets": [
// see subsection
],
"sort_options": [
// see subsection
]
}
]
}
Endpoint: /v1/configuration
API Key: Private
This endpoint is used to configure your store(s). It should be called first to define your stores and again if any fields
or tag_sets
are created. Each call to /configuration
should contain the complete definition and not just the delta.
Each Store should contain the following basic fields and associated information as described in the subsections.
Parameter | Description |
---|---|
id |
The ID for the store. This is used in subsequent API calls as identification[store_id] . |
label |
Label used when showing this store in the Tagalys Dashboard |
locale |
Two letter language and country codes separated by an underscore. For example, 'en_US'. Number and currency formatting will be based on this field. |
timezone |
Timezone for displaying dates and times in the Tagalys Dashboard. |
multi_currency_mode |
Implementation method for different currencies (currenly, the only value supported is exchange_rate ) |
products_count |
Approximate number of products this store contains. This information is used for provisioning resources. |
Currencies
[
{
"id": "USD",
"label": "$",
"fractional_digits": 2,
"rounding_mode": "round",
"exchange_rate": 1.0,
"default": true
},
{
"id": "HKD",
"label": "HK$",
"fractional_digits": 2,
"rounding_mode": "round",
"exchange_rate": 7.76,
"default": false
}
]
This array defines the list of currencies that can be displayed to visitors. Each currency should have the following parameters.
Parameter | Description |
---|---|
id |
The unique identifier for this currency. This is used in subsequent API calls as identification[curency] |
label |
Label used when showing this currency in the Tagalys Dashboard and in front-ends |
fractional_digits |
How many decimal places should be visible when displayed to visitors |
rounding_mode |
The only supported value is round |
exchange_rate |
What multiplier should be used on currency field values defined in products to arrive at a display value for this currency |
default |
Boolean signifying the currency to use when there is no identification[currency] defined in an API call. Only one currency should have this set to true. |
Fields & Tag Sets
There are two data structures in Tagalys for storing product data:
- Field: All integer, float (price / sale price), datetime (introduced date), boolean (in stock) and free text fields (name, description) should be defined as Fields. All fields except free text fields can be used in the Tagalys Dashboard as filters when creating listing pages. For now, only integer and float Fields can be used in front-end filters. Free text fields that are defined as a Field can be used for searching (but not for filtering in either the front-end or Tagalys Dashboard).
- Tag Set: This is a special data structure that can hold single, multiple and nested strings in tree structures (color, categories). These are used for product details where the set of possible values is finite / predefined. These can be used in front-end filters, in the Tagalys Dashboard for creating pages and while searching for products.
Core Fields
Tagalys defines a set of mandatory fields for products. Equivalent fields in your platform should be mapped to these names.
Field name | Type | Description |
__id |
String | The unique identifier for this product that will not change over time |
name |
string | |
sku |
string | |
link |
string | Absolute link to the product detail page |
image_url |
string | Absolute link to the product image used in listing pages |
image_hover_url |
string | Absolute link to the product hover image used in listing pages |
price |
float | The list price of the product in the base currency |
sale_price |
float | The selling price of the product in the base currency |
introduced_at |
datetime | The date and time (in the format 2016-11-02T09:40:01+00:00 ) at which the product was first available online. This will be used as the reference value for the 'newness' component of product scores. |
in_stock |
boolean | Whether the product is currently in stock |
available |
boolean | Whether the product is available to be sold online (for example, via a back-order) |
synced_at |
datetime | The date and time (in the format 2016-11-02T09:40:01+00:00 ) at which the product details were last extracted while syncing to Tagalys |
Custom Fields
[
{
"name": "inventory",
"type": "integer",
"label": "Inventory",
"display": true
},
{
"name": "caratage",
"type": "integer",
"label": "Caratage",
"display": true,
"filters": true,
"display_suffix": "K"
},
{
"name": "short_description",
"type": "string",
"label": "Short Description",
"search": true
}
]
If you have any product fields (integer, float, datetime, boolean or free text fields) other than the core fields defined above, you should define them in the fields
section of the Configuration object. Each field can contain the following parameters.
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
name |
string | Yes | Machine name of the field. This is used as the key while defining values for products. Should start with a lowercase alphabet, can contain lower case alphabets, numbers and underscores. | |
type |
string | Yes | One of
|
|
label |
string | Yes | Human readable name of the field | |
display |
boolean | No | false |
Should this field be included when product details are requested in front-end APIs? |
filters |
boolean | No | false |
Should a front-end filter be created for this field? |
search |
boolean | No | false |
Should this field's values be used when searching for products? |
currency |
boolean | No | false |
Does this field store currency values? If true, exchange rate logic is applied for the currency in context. |
Tag Sets
[
{
"id": "categories",
"label": "Categories",
"filters": true,
"search": true
},
{
"id": "color",
"label": "Color",
"filters": true,
"search": true,
"display": true
},
{
"id": "gender",
"label": "Gender",
"filters": true,
"search": true
},
{
"id": "size",
"label": "Size",
"filters": true,
"search": false,
"display": true
}
]
Any product attributes that are predefined strings and can contain one more more values as an array or in a tree structure should be defined as Tag Sets. Tag Set parameters are similar to Custom Fields.
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
name |
string | Yes | Machine name of the field. Should start with a lowercase alphabet, can contain lower case alphabets, numbers and underscores. | |
label |
string | Yes | Human readable name of the field | |
display |
boolean | No | false |
Should this tag set be included when product details are requested in front-end APIs? |
filters |
boolean | No | false |
Should a front-end filter be created for this tag set? |
search |
boolean | No | false |
Should this tag set's values be used when searching for products? |
Sort Options
[
{
"field": "introduced_at",
"directions": [
{
"direction": "desc",
"label": "Newest first"
}
]
},
{
"field": "sale_price",
"directions": [
{
"direction": "asc",
"label": "Price - Low to high"
},
{
"direction": "desc",
"label": "Price - High to low"
}
]
}
]
Define the sort options available to visitors on search and product listing pages. Each sort option should contain the following parameters
Parameter | Description | ||||||
field |
The ID of the Core or Custom field which is used for sorting | ||||||
label |
The label shown to the user if direction labels are not specified | ||||||
directions |
An array of directions within this field to allow sorting on. Each direction should contain the following parameters:
|
Product Sync APIs
These endpoints are used to keep each store's catalog synced with Tagalys. Once a store has been created, its products should be syced via the sync_feed
endpoint and as products are added / edited or deleted, the changes should be sent to the sync_updates
endpoint. Both of these endpoints work by receiving a link to a file that contains either the full feed or just the details of the products that have been updated since the last sync.
File Format
{"perform":"index","payload":{"__id":"337","name":"Aviator Sunglasses","sku":"ace000","price":295,"sale_price":249,"link":"http://www.your-store.com/aviator-sunglasses.html","image_url":"http://www.your-store.com/media/catalog/product/a/c/ace000a_1.jpg","image_hover_url":"http://www.your-store.com/media/catalog/product/a/c/ace000a_1_hover.jpg","synced_at":"2016-11-02T09:40:01+00:00","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"description":"Gunmetal frame with crystal gradient polycarbonate lenses in grey. ","short_description":"A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.","__tags":[{"tag_set":{"id":"categories","label":"Categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Silver","id":"15"},{"label":"Grey","id":"16"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]}]}}
{"perform":"delete","payload":{"__id":"440"}}
For any sync request, a publicly accessible file must be created with jsonl extension and a link to this file must be sent to Tagalys. This is simply a file with one valid json per line.
Each line must contain the following parameters:
Parameter | Description |
---|---|
perform |
Either index (for creating / editing) or delete |
payload |
Details of the product |
Constructing the payload
{
"perform": "index",
"payload": {
"__id": "337",
"name": "Aviator Sunglasses",
"sku": "ace000",
"price": 295,
"sale_price": 249,
"link": "http://www.your-store.com/aviator-sunglasses.html",
"image_url": "http://www.your-store.com/media/catalog/product/a/c/ace000a_1.jpg",
"image_hover_url": "http://www.your-store.com/media/catalog/product/a/c/ace000a_1_hover.jpg",
"synced_at": "2016-11-02T09:40:01+00:00",
"introduced_at": "2013-03-04T16:48:17-08:00",
"in_stock": true,
"description": "Gunmetal frame with crystal gradient polycarbonate lenses in grey. ",
"short_description": "A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.",
"__tags": [
{
"tag_set": {
"id": "categories",
"label": "Categories"
},
"items": [
{
"id": "6",
"label": "Accessories",
"items": [
{
"id": "18",
"label": "Eyewear"
}
]
}
]
},
{
"tag_set": {
"id": "color",
"label": "Color"
},
"items": [
{
"label": "Silver",
"id": "15"
},
{
"label": "Grey",
"id": "16"
}
]
},
{
"tag_set": {
"id": "gender",
"label": "Gender"
},
"items": [
{
"label": "Male",
"id": "93"
}
]
}
]
}
}
If perform
is delete
, the payload only needs to contain the __id
parameter.
If perform
is index
, which is used for creating and editing products, the entire product's details should be present. Fields
are entered as keys directly into the payload object. Tag Sets
are a complex structure set inside the __tags
key.
__tags
The tags object contains two keys: tag_set
and items
.
tag_set
should contain the following parameters:
Parameter | Description |
---|---|
id |
Machine name of the attribute that is used for internal references and in URLs when this tag_set is used as a filter. Can contain lower case alphabets, numbers and underscores. Cannot start with an underscore. |
label |
Name dispalyed to users in the Tagalys Dashboard |
items
This is an array that can house one more more values for the attribute defined in tag_set
. It can also be nested by using the items
key within itself. Each item can contain the following parameters:
Parameter | Description |
---|---|
id |
Unique identifier of the item. Can contain lower case alphabets, numbers and underscores. Cannot start with an underscore. |
label |
Name dispalyed to visitors |
items |
For specifying nested attributes like Categories |
Sync Feed
{
"identification": {...},
"link": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6",
"updates_count": 21532,
"callback_url": "http://www.yours-store.com/feed-callback"
}
Endpoint: /v1/products/sync_feed
API Key: Private
This endpoint is used to transfer a point-in-time snapshot of the entire product catalog. It is used for the initial product data transfer and at a later point if any updates / deletes have been missed. After this request is processed, any products not in the file are deleted from Tagalys permanently.
Parameters are defined in the Common Sync API parameters section.
Sync Updates
{
"identification": {...},
"link": "http://www.your-store.com/path/to/updates-file.jsonl?authkey=hdt24628dhw8dg2d6",
"updates_count": 7,
"callback_url": "http://www.yours-store.com/update-callback"
}
Endpoint: /v1/products/sync_updates
API Key: Private
This entpoint is used to transfer updates after the initial sync. If perform
is delete
, only __id
is required. For perform
: index
, the product's complete data should be present. Partial updates are not supported.
Parameters are defined in the Common Sync API parameters section.
Common Sync API parameters
Both endpoints use the following parameters:
Parameter | Description |
---|---|
link |
A publicly accessible link to the file |
updates_count |
The number of products in the file (and therefore the number of lines in the file) |
callback_url |
Once the sync file is processed, Tagalys will call this URL via POST method with the parameters described below. |
Callback parameters
{
"identification": {...},
"completed": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6"
}
Once a sync file is processed, Tagalys will call the specified Callback URL via POST method with the following parameters.
Parameter | Description |
---|---|
identification |
You should verify your private key to validate this call |
completed |
Link to the file that has been processed |
Front End APIs
Search Suggestions API
{
"q": "dre",
"queries": 5,
"products": 8
}
Endpoint: /v1/ss
API Key: Public
Parameter | Type | Required | Description |
---|---|---|---|
q |
string | Yes | The query currently filled into the search box |
queries |
integer | Yes | The maximum number of search query suggestions you want |
products |
integer | Yes | The maximum number of product suggestions you want |
This API can be used to suggest search queries and products to the user as they are typing in their query. A minimum query length of 2 and a debounce implementation of 100ms is suggested. Earlier requests should be cancelled before making new requests to make sure results for the latest query is displayed to the user.
{
"queries": [
{
"query": [
"Dresses"
],
"filter": {
"_product_type": [
"Dresses"
]
}
}
],
"products": [
{
"id": "1",
"name": "Red Sheath Dress",
"sku": "RSD-1",
"link": "https://demo.tagalys.com/products/women-red-sheath-dress",
"image_url": "...",
"price": 45,
"sale_price": 30,
"discount_amount": 15,
"in_stock": true
},
{
...
}
]
}
The response object will contain the queries
and products
keys as requested. On selection of a given search query suggestion, the filter
key inside queries
can be sent as the qf
parameter in the search results API request to display more accurate results.
Search API
Request
{
"q": "silver eyewear",
"qf": {
"color": ["15"],
"categories": ["18"]
}
}
Endpoint: /v1/search
API Key: Public
Parameter | Type | Required | Description |
---|---|---|---|
q |
String | Required | The search term can be two or more characters |
qf |
Filter Object | Optional | Optional parameter to include filters implied by the query to get more precise search results. Uses the same format as the f parameter described in the Common listing page parameters section. |
In addition to this, all of the parameters in the Common listing page parameters section can be used.
Response
In addition to the standard response format, the following additional details may be present in search API responses, depending on the query and product availability.
Redirects
{
"redirect_to_url": "https://www.your-store.com/account/orders"
}
Tagalys can be configured to return redirect URLs when certain queries are performed. In these cases you should redirect the user to the URL defined in redirect_to_url
.
Spelling corrected results
{
"query_original": "shirst",
"query": "shirts"
}
When Tagalys does not find products for a given query, it will first try looking for alternate spellings that have results. In this case, the response will contain the original query in query_original
and the corrected query in query
.
Partial matches
{
"query": "black white dresses",
"query_mode": "or"
}
If Tagalys doesn't find alternate spellings with results, then it will look for partial matches instead of trying to match all the words in the query. You can detect this based on the query_mode
parameter's value being or
(instead of and
.)
Recommendations
Smart Widgets
{
"identification": {...},
"limit": 16,
"request": ["results", "details"]
}
Endpoint: /v1/custom_widgets/:smart-widget-id
API Key: Public
Product IDs and details in Smart Widgets created on the Tagalys Dashboard can be retrieved via this endpoint.
Similar Products
{
"identification": {...},
"limit": 16,
"request": ["results", "details"]
}
Endpoint: /v1/products/:product-id/similar
API Key: Public
Product IDs and details of products similar to the specified product ID can be retrieved through this endpoint.
Bought also bought
{
"identification": {...},
"limit": 16,
"request": ["results", "details"]
}
Endpoint: /v1/products/:product-id/bought_also_bought
API Key: Public
Product IDs and details of products bought by users who bought the specified product ID can be retrieved through this endpoint.
Viewed also viewed
{
"identification": {...},
"limit": 16,
"request": ["results", "details"]
}
Endpoint: /v1/products/:product-id/viewed_also_viewed
API Key: Public
Product IDs and details of products viewed by users who viewed the specified product ID can be retrieved through this endpoint.
Product Listing Pages
Endpoint: /v1/mpages/:listing-page-name
API Key: Public
Product Listing Pages are created on the Tagalys Dashboard with a name that can be included in the URL. A page's details can be called using the endpoint that includes that page's name.
The request format is as described in the Common listing page parameters section.
Common listing page parameters
{
"page": 2,
"per_page": 24,
"sort": "introduced_at-desc",
"f": {
"gender": ["93"],
"price": {
"selected_min": 50,
"selected_max": 100
}
},
"request": [
"total",
"results",
"details",
"sort_options",
"filters"
]
}
For Search and Product Listing Pages APIs, the following parameters can be used.
Parameter | Type | Required | Description |
---|---|---|---|
page |
Integer | Optional | Requested page number |
per_page |
Integer | Optional | Number of search results per page |
sort |
String | Optional | Specify the field and direction to sort results in the format field-direction where direction can be asc or desc . -direction should not be included for the default sort option trending |
f |
String | Filter Object |
An object with the Tagalys filters selected by the user. The format varies depending on whether the filter is of type
|
request |
Array of strings | Required |
Define what information you want as part of the API response.
|
Response format
{
"total": 164,
"results": [
"8810",
"...",
"..."
],
"filters": [
{
"id": "price",
"name": "Price",
"type": "range",
"min": 29,
"max": 329
},
{
"id": "gender",
"name": "Gender",
"type": "checkbox",
"items": [
{
"id": "female",
"name": "Female",
"count": 93,
"selected": false
},
{
"id": "male",
"name": "Male",
"count": 71,
"selected": false
}
]
}
],
"sort_options": [
{
"id": "trending",
"label": "Trending",
"selected": false
},
{
"id": "introduced_at",
"label": "Introduced at",
"selected": true,
"directions": [
{
"direction": "desc",
"label": "What's new",
"selected": true
}
]
},
{
"id": "price",
"label": "Price",
"selected": false,
"directions": [
{
"direction": "asc",
"label": "Price-low to high",
"selected": false
},
{
"direction": "desc",
"label": "Price-high to low",
"selected": false
}
]
}
],
"details": [
{
"id": "8810",
"name": "Lorem ipsum dolor sit amet",
"sku": "LIDSA",
"link": "https://www.example.com/lorem-ipsum-dolor-sit-amet",
"image_url": "https://www.example.com/images/lorem-ipsum-dolor-sit-amet.jpg",
"price": 49,
"in_stock": true,
},
{...},
{...}
]
}
This is the response format of a generic results page that includes filters, sort options, product IDs, and product details. This information can be used to completely render the results page.
Front End - JavaScript
Tagalys Search suggestions, Search results, Listing pages and Recommendations can be integrated into your front-end using our jQuery plugins.
Include the plugin
<script src="https://d3htxdwqp62ai4.cloudfront.net/tagalys-plugins-v6.js" type="text/javascript"></script>
Include https://d3htxdwqp62ai4.cloudfront.net/tagalys-plugins-v6.js
in your footer.
Set the Context
var tagalys_context_opts = {
api_server: 'https://api-rx.tagalys.com',
api_identification: {
client_code: "...",
api_key: "public-api-key",
store_id: "...",
currency: "currency-id" // for use exchange rate transformations to base currency on the API side - should be the id related to the details mentioned in the currency section
},
currency: { // currency details for display
label: '$',
exchange_rate: 1.0, // to convert from base currency
fractional_digits: 0,
locale: "en-US"
}
};
if(user_id != ""){
tagalys_context_opts.user_id = user_id;
}
$('body').tagalys_context(tagalys_context_opts);
The Context is set by our jQuery plugin on a DOM element that contains all elements related to Tagalys features. Unless you require multiple Contexts, this element is <body>
. The Context specifies the API endpoint with identification details, currency information for the visitor and the visitor's identifying information. Make sure you enter the public API Key and not the private one. These details are accessible by all your visitors.
Search Suggestions
$.fn.tagalys_search_suggestions.search_link = function(q, qf, qin) {
var search_url_base = 'https://www.your-website.com/';
if (typeof(qf) == 'undefined' || $.isEmptyObject(qf)) {
return (search_url_base + '?q=' + encodeURIComponent(q));
} else {
qf = Object.keys(qf).map(function(key) {
return encodeURIComponent(key) + "-" + encodeURIComponent(qf[key]);
}).join('~');
return (search_url_base + '?q=' + encodeURIComponent(q) + '&qf=' + qf);
}
};
Define how links should be constructed using the search_link
function. The arguments are:
q
- the string representation of the queryqf
- the filters to apply via the selected optionqin
- in case of nested filters, the entire list of options (superset ofqf
)
$('#search').tagalys_search_suggestions({
currency: {
label: '$',
exchange_rate: 1.0,
fractional_digits: 0,
locale: "en-US"
},
track: 'asynchronous'
});
Finally, initialize the search suggestions plugin. You should define the currency being used by the visitor along with the exchange rate.
Search Results
<div class="tagalys-namespace" id="tagalys-namespace"></div>
<script type="text/javascript">
$(document).on('tagalys:ready', function() {
$('#tagalys-namespace').tagalys_search_results({
per_page: 16,
pagination_mode: 'pages' // or 'infinite-scroll'
});
});
</script>
Create a blank page with your layout and initialize this plugin on an empty DOM element. Make the ID and Class of this element tagalys-namespace
to provide sufficient CSS specificity. The plugin will use the URL's q
and qf
query string parameters to initialize itself. These query string parameters are set by the Search Suggestions plugin.
Product Listing Pages
<div class="tagalys-namespace" id="tagalys-namespace"></div>
<script type="text/javascript">
$(document).on('tagalys:ready', function() {
$('#tagalys-namespace').tagalys_mpage({
name: 'url-slug' // generally part of the page's URL, defined in the Tagalys Dashboard
});
});
</script>
Create a blank page with your layout and initialize this plugin on an empty DOM element. Make the ID and Class of this element tagalys-namespace
to provide sufficient CSS specificity.
Analytics Integration
Tagalys uses analytics data you send to calculate product scoring and provide you with detailed reports. Once integrated, product scoring is updated automatically, and you can attribute product views / add to carts / buys to specific Tagalys features and even to specific queries / widgets / pages.
Analytics via JavaScript
The JavaScript plugin takes care of setting up and maitaining user identification cookies and handles API communication.
Track User
$.fn.tagalys_analytics.track_user(user_id);
The track_user
helper allows you to associate each browsing session with a user account across devices. To perform this association, make the following call after the user logs in. Previous events in the session where the user was not logged in are automatically associated with this user account.
Track Event
$.fn.tagalys_analytics.track_event(event_type, event_data);
Using the track_event
helper, you can send Tagalys details on product listing pages and actions. This helps us improve the relevance and sort orders of various Tagalys features, as well as provide you with detailed reports on our dashboard.
event_type
maybe one of product_action
or product_list
.
Product Action Events
product_action
events send Tagalys details on each product view, add to cart and buy.
The event_data
argument should be an object containing the following parameters:
Parameter | Required | Description | Type | Default value |
---|---|---|---|---|
sku |
Yes | The identifier of the target product (top-level SKU for Magento, top-level ID for Shopify/BigCommerce) | String | NA |
action |
Yes |
That action that is being performed on the product. One of:
|
String | NA |
quantity |
For add_to_cart and buy |
The number of items of the sku that are being added to cart or bought |
Integer | NA |
order_id |
For buy |
The unique ID of the order to which this buy is associated. If an order is placed for multiple items, send the buy event once for each sku with the associated quantity and the same order_id . |
String | NA |
Product List Events
product_list
events send Tagalys details about searches and product listing pages to enable attribution of product actions to specific features and queries. This helps with providing our popular searches API, sorting products better for individual searches / pages, and with advanced reporting that lets you figure out which pages and searches are working and what can be done to improve conversion.
The event_data
argument should be an object containing the following parameters:
Parameter | Required | Description | Type | Default value |
---|---|---|---|---|
pl_type |
Yes |
The type of the Tagalys feature being shown to the user. One of:
|
String | NA |
pl_details |
Yes |
Details of the product list, depends on pl_type
|
JSON object | NA |
pl_total |
For search , widget-* and mpage |
The total number of product results for the search / merchandised page | Integer | NA |
pl_page |
For search , widget-* and mpage |
Events should be sent for each page number of the search or merchandised page being displayed. This parameter should mention the page number for the event being sent. | Integer | NA |
pl_sort |
For search , widget-* and mpage , if you are not using the default sort option trending |
The sort option in the same format as listing page API requests | string | trending |
pl_products |
For search , widget-* and mpage |
An array of SKUs of the products being displayed on the current page. | Array of integers | NA |
Analytics via API
If using the Tagalys JavaScript SDK is not an option because you are integrating Tagalys into a native app or PWA, then you can send events to the API directly.
Identifying Users
To identify users on across browsing sessions and across devices, Tagalys uses the following parameters. You will need to maintain values for these parameters that behave as described and include them in the identification
section of all analytics API requests.
{
"identification": {
"client_code": "...",
"api_key": "...",
"store_id": "...",
"user": {
"device_id": "gcBQKHYcSojrDNOgAxyyFo1Xlz0C3saT",
"visit_id": "K9k5NRzVMjNXleb5OqOI8QDq825l13kP",
"user_id": "123"
}
}
}
Name | Required | Description |
---|---|---|
device_id |
Yes | A hexadecial string, 32 characters long, that is used to uniquely identify a single device. It should be generated when the device first connects, and should be maintained for the lifetime of the device. If this value changes, the API requests will be considered to originate from a different device. |
visit_id |
Yes | A hexadecial string, 32 characters long, that is used to uniquely identify a single browsing session. Tagalys defines a session as any string of events from a single device within 30 minutes of each other. If there is a > 30 minute differece between two events, the old visit_id should be abandoned and new one should be generated. |
user_id |
Required when a user is logged-in | A string that is used to uniquely identify a single user across devices. This usually maps to the User ID for the logged-in user. |
Device Info
{
"device_info": {
"device_type": "desktop",
"os": {
"name": "mac"
},
"browser": {
"name": "Chrome",
"version": "83.0"
},
"screen_resolution": {
"width": 1680,
"height": 532
}
}
}
Tagalys allows segmentation of analytics data based on device information. You can include this info using this format with the following parameters:
Name | Required | Description |
---|---|---|
device_type |
Yes | mobile , tablet , or desktop |
os.name |
Yes | A string identifying the Operating System on the device. Examples: mac , android , ios . |
browser.name |
Yes | Name of the browser. Examples: Chrome , Safari . You can also use the name of your app. |
browser.version |
Yes | A string with the version of the browser / app being used |
screen_resolution.width |
Yes | The width of the device's screen, in pixels |
screen_resolution.height |
Yes | The height of the device's screen, in pixels |
Endpoints
// complete example of a search results analytics event
{
"event_type": "product_list",
"details": {
"pl_type": "search",
"pl_details": {
"q": "tops",
"qm": "and"
},
"pl_products": [
"SKU-P-1",
"SKU-P-2",
"SKU-P-3",
"SKU-P-4"
],
"pl_page": 1,
"pl_total": 4
},
"device_info": {
"device_type": "desktop",
"os": {
"name": "mac"
},
"browser": {
"name": "Chrome",
"version": "83.0"
},
"screen_resolution": {
"width": 1680,
"height": 532
}
},
"identification": {
"client_code": "...",
"api_key": "...",
"store_id": "...",
"user": {
"device_id": "gcBQKHYcSojrDNOgAxyyFo1Xlz0C3saT",
"visit_id": "K9k5NRzVMjNXleb5OqOI8QDq825l13kP",
"user_id": "123"
}
}
}
Track User
Endpoint: /v1/analytics/users/track
Track Event
Endpoint: /v1/analytics/events/track