NAV Navbar
Examples

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:

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
  • string
  • integer
  • float
  • datetime
  • boolean
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

ParameterDescription
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:
Parameter Description
directionOne of asc or desc
labelThe label shown to the user. If blank, the label is taken as the sort option label + (asc) or (desc)

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 checkbox or range.

  • For checkboxes the value is an array of the selected filter IDs
  • For ranges the value is a hash with the following keys:
    • selected_min The starting point of the range selected by the user
    • selected_max The ending point of the range selected by the user
request Array of strings Required

Define what information you want as part of the API response.

  • total The total number of products matching the search / listing page
  • results The product IDs of the matching results
  • details The details of the matching results to enable rendering of the page without making a database call
  • sort_options The available sort options for this list
  • filters The available filters for this list
  • variables (Only for Product Listing Pages) The list of variables defined in the Tagalys Dashboard
  • banners (Only for Product Listing Pages) The list of banners defined in the Tagalys Dashboard

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:

$('#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:
  • view
  • add_to_cart
  • buy
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:
  • page-platform (PLPs - Category / Collection)
  • search
  • widget-custom
  • widget-similar_products
  • widget-bought_also_bought
  • widget-viewed_also_viewed
  • mpage (Legacy)
String NA
pl_details Yes Details of the product list, depends on pl_type
  • page-platform
    • page_id - the identifier of the PLP on the platform (Category / Collection ID)
  • search - q and qf should be in the same format sent to the search API. qm should be the value in the search API's response - it could be and or or depending on whether the search results are a full or parital matches.
    • q
    • qf
    • qm
    • f in the same format as in listing page API requests
  • widget-custom
    • id - the ID of the widget in the Tagalys dashboard
  • widget-similar_products, widget-bought_also_bought, widget-viewed_also_viewed
    • product - the identifier of the product that the widget is displayed for. Magento: top-level SKU. Shopify & BigCommerce: top-level ID
  • mpage
    • url - should match the URL component /m/*url* entered in the Tagalys dashboard for the merchandised page being displayed
    • title - used for displaying the page in Tagalys Dashboard reports
    • f in the same format as in listing page API requests
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