Skip to content

Custom Integration

Custom Integration (Backend Side) Guide and Restful API

Introduction

This tutorial provides a very simple and quick introduction to the Segmentify integration for custom applications by walking you through details of different events. Segmentify has a RESTful API to feed important events like page/product information and visitor actions to the Segmentify Engine.

Integration

This guide will help you to integrate different events (visitor actions) and also product recommendations, engagement campaigns and search-box recommendations. Integration can be divided into following steps:


Event Types

Segmentify uses different event types for different visitor actions. You can define following events by using Segmentify RESTful API:

Event Description Event Name
Page It is send when a visitor views a page PAGE_VIEW
Product It is send when a visitor views a product PRODUCT_VIEW
Basket It is send when a visitor makes a basket action (add product to basket or remove product from basket) BASKET_OPERATIONS
Checkout It is send when a visitor makes a checkout action (views basket, enter customer information, enter payment information, finishes purchase) CHECKOUT
User It is send when a visitor makes a user action or use this event to update information about customers USER_OPERATIONS
Custom It is send when to identify any visitor action that has no predefined value in Segmentify CUSTOM_EVENT
Interaction It is send when a visitor makes an interaction like click, view a widget, submit, etc. INTERACTION
Form It is send when a visitor submits a form or survey USER_FORM
Banner It is send when visitors views or clicks to banners BANNER_VIEW or BANNER_OPERATIONS
Search It is send when visitors clicks on search-box or types search query SEARCH

Request Details

In order to use Segmentify RESTful API, you must be make POST requests to your data center end point with event details at request body. Request body must be formed as a valid json array.

Segmentify accounts have two important system variables used in integration: API KEY and Data Center. You can access these values from Integrations menu of Segmentify Panel:

System Variable Description
Api Key unique Segmentify key value to send events
Data Center data center end point to send Segmentify events

To access Integrations menu of Segmentify Panel, please login to your Segmentify account and navigate to Settings > Integrations.

Request body should be a json array whose elements are Segmentify events that will be described in the next sections, you can send multiple events with a single request.

Request Endpoint

Requests must be made to proper end point. Endpoint url format is like

Request Endpoint Format:

<DATA CENTER URL>/add/events/v1.json?apiKey=<APIKEY>

Data Center Url is account specific and you should use the end point shown at Integrations page under Account Settings.

Example Data Center Url:

https://xxx.segmentify.com

Api Key is your account's unique key to send requests to Segmentify RESTful Api, and you can learn your Api Key from Integrations page under Account Settings

Example Api Key:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Proper request end point is changing data center url and api key with your account specific value.

Example Request Endpoint:

https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Request Headers

Segmentify Restful API is based on json, so headers should match content type and response type.

All request should have the following headers:

Header Value
Content-Type application/json
Accept application/json
Origin Your domain

Request Body

Request body should be a json array whose elements are Segmentify events that will be described in this document.

An example request body will be in this format:

[
    {
      "name": "PAGE_VIEW",
      "userId": "XXXXXXXXXXXXXXXXX",
      "sessionId": "YYYYYYYYYYYYYYYY",
      "device": "PC",
      "pageUrl": "http://www.exampleshop.com/",
      "referrer": "http://www.google.com/",
      "category": "Product Page",
      "subCategory": "Men > Sports"
    },
    {
      "name": "PRODUCT_VIEW",
      "userId": "XXXXXXXXXXXXXXXXX",
      "sessionId": "YYYYYYYYYYYYYYYY",
      "device": "PC",
      "productId": "EXAMPLE_PRODUCT_1"
    }
]
[
  {
    "name": "PAGE_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "MOBILE",
    "pageUrl": "http://www.exampleshop.com/",
    "referrer": "http://www.google.com/",
    "category": "Product Page",
    "subCategory": "Men > Sports"
  },
  {
    "name": "PRODUCT_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "MOBILE",
    "productId": "EXAMPLE_PRODUCT_1"
  },
]
[
  {
    "name": "PAGE_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "IOS",
    "pageUrl": "http://www.exampleshop.com/",
    "referrer": "http://www.google.com/",
    "category": "Product Page",
    "subCategory": "Men > Sports"
  },
  {
    "name": "PRODUCT_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "IOS",
    "productId": "EXAMPLE_PRODUCT_1"
  }
]
[
  {
    "name": "PAGE_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "ANDROID",
    "pageUrl": "http://www.exampleshop.com/",
    "referrer": "http://www.google.com/",
    "category": "Product Page",
    "subCategory": "Men > Sports"
  },
  {
    "name": "PRODUCT_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "device": "ANDROID",
    "productId": "EXAMPLE_PRODUCT_1"
  }
]

Response Details

RESTful API returns different status codes to show you status of your request. Summary of status codes are given:

Status Code Description
200 - OK Request has reached to Segmentify Server and it is processed. Please check Response Body for details.
400 - Bad Request  The request was unacceptable, often due to wrong request type. You should make a POST request for sending events.
404 - Not Found  The requested resource doesn't exist, often due to illformed request url
5XX - Server Errors Something went wrong on Segmentify's end.

Response Body

Segmentify event requests returns a json object as reponse.

Example format of response body is given below:

{
    "search": [
        []
    ],
    "campaigns": [
        []
    ],
    "coupons": [
        []
    ],
    "experiments": {
    },
    "responses": [
        []
    ],
    "statusCode": "SUCCESS",
    "timestamp": 1665657157927
}

Response object has a list of actions inside responses array. An example action definition (recommendation) is given below:

{
    "type": "recommendProducts",
    "params": {
        "staticItems": "[]",
        "notificationTitle": "Last Visited Products",
        "insertType": "AFTER",
        "ordering": "SHUFFLE",
        "exclusions": "[]",
        "recommendedProducts": {
            "RECOMMENDATION_SOURCE_ALL_PRODUCTS|THIS_WEEK": [{
                "productId": "XXXXXXXXXXXXXXXXXXXXXX",
                "name": "Example Product 1",
                "url": "https://www.exampleshop.com/example-product?_sgm_source=XXXXXXXXXXXXXXXXXXXXXX&_sgm_campaign=scn_XXXXXXXXXXXXXXXXX&_sgm_action=click&_sgm_type=RSAP",
                "image": "https://cdn.exampleshop.com/example-product.jpg",
                "price": 169.9,
                "priceText": "€169,90",
                "oldPriceText": "",
                "currency": "EUR",
                "category": ["Main Category > Sub Category 1 > Sub Category2"],
                "lastUpdateTime": 1501510936208,
                "inStock": true,
                "insertTime": 1459250843999,
                "publishTime": 1463306155916,
                "brand": "BrandName",
                "gender": "male",
                "labels": ["New"],
                "sizes": ["41", "42", "43", "44", "45"],
                "colors": ["White", "Black"],
                "params": {
                    "brand": "BrandName",
                    "pid": "378331",
                    "availCount": "5",
                    "newItem": "false",
                    "totalSize": "8"
                }
            }, {
                "productId": "YYYYYYYYYYYYYYYYYYYYYYY",
                "name": "Example Product 2",
                "url": "https://www.exampleshop.com/example-product?_sgm_source=YYYYYYYYYYYYYYYYYYYYY&_sgm_campaign=scn_XXXXXXXXXXXXXXXXX&_sgm_action=click&_sgm_type=RSAP",
                "image": "https://cdn.exampleshop.com/example-product2.jpg",
                "price": 209.25,
                "priceText": "€209,25",
                "oldPrice": 279.0,
                "oldPriceText": "€279,00",
                "currency": "EUR",
                "category": ["Main Category > Sub Category 1 > Sub Category 2"],
                "categories": ["BrandName2"],
                "lastUpdateTime": 1501511406943,
                "inStock": true,
                "insertTime": 1492146294110,
                "publishTime": 1492146294110,
                "brand": "BrandName2",
                "gender": "male",
                "labels": ["Online"],
                "sizes": ["42.5", "43", "46"],
                "colors": ["Red"],
                "params": {
                    "pid": "563270",
                    "brand": "BrandName2",
                    "availCount": "3",
                    "totalSize": "8"
                }
            }],
            "RECOMMENDATION_SOURCE_STATIC_ITEMS": []
        },
        "actionType": "INPAGE_WIDGET",
        "instanceId": "scn_XXXXXXXXXXXXXXXXX",
        "postJsCode": "",
        "itemsPerRow": "4",
        "recommendationTemplate": "
            <div id=\"seg-detail-rec\" class=\"seg-recom\">
               <div class=\"seg-title\">[[title]]</div>
               <div class=\"text-center\">
                  <ul class=\"seg-detail_slider\">
                     [[#products]]
                     <li>
                        <div class=\"item-info\">
                           <a class=\"product-image\" onclick=\"ga('segmentifyGAEvent.send', 'event','Product Pages_[[productId]]','Product Detail','[[productId]]', 1, { 'nonInteraction': 1 });\" href=\"[[url]]\">
                              <img src=\"[[newImage]]\" alt=\"[[name]]\"  title=\"[[name]]\" style=\"width: 140px; height: 140px;\">
                           </a>
                           <div class=\"product-details\">
                              <div class=\"related-attr\"></div>
                                 <span class=\"orange\">[[discount]]</span>
                              <h3 class=\"product-brand\">[[brand]]</h3>
                              <div class=\"productPrices\">
                                 [[#oldPriceFarkliPrice]][[#oldPrice]]
                                 <span class=\"oldPrice\">€[[commaFormatPrice]]</span>
                                 [[/oldPrice]][[/oldPriceFarkliPrice]][[#price]]
                                 <span class=\"newPrice\">€[[commaFormatPrice]]</span>[[/price]]
                              </div>
                           </div>
                        </div>        
                     </li>
                     [[/products]]
                  </ul>
               </div>
            </div>
        ",
        "actionId": "act_1e062d2793a42000",
        "selector": "body",
        "elimination": "ELIMINATE_DUPLICATES",
        "preJsCode": "window.segSearch = new Object();\n  window.segSearch[\"product\"] = conf.products[0];\n}",
        "inclusions": "[]",
        "actionName": "actn_1e063090c56a6000"
    }
}

Response object has a list of actions inside campaigns array. An example action definition (engagement) is given below:

{
  "campaigns": [
    [
      {
        "type": "POPUP_BANNER",
        "name": "TestCampaign",
        "instanceId": "cmp_ed8b236d72956000",
        "status": "ACTIVE",
        "devices": [
          "PC",
          "MOBILE",
          "TABLET",
          "ANDROID",
          "IOS"
        ],
        "startDate": 1671547045867,
        "note": "",
        "timing": {
          "type": "IMMEDIATE",
          "param": ""
        },
        "frequency": {
          "type": "ALWAYS",
          "param": ""
        },
        "filters": [
          {
            "type": "PAGE",
            "includedCategories": [
              "Category Page",
              "Home Page",
              "Product Page"
            ],
            "excludedCategories": [

            ]
          }
        ],
        "accountId": "acc_ec8978ab072f2000",
        "prioritized": false,
        "title": "PopupBannerTestCampagn",
        "image": "https://example.com/example.jpg",
        "url": "https://example.com/examplePage.html",
        "overlay": "false",
        "verticalPosition": "middle",
        "horizontalPosition": "center",
        "html": "<div class=\"seg-popup-overlay\"></div>\n<div class=\"seg-popup seg-rec-banner seg-[[vertical]]-[[horizontal]] segFadeInUp\">\n    <div class=\"seg-popup-container\">\n        [[#title]]\n            <div class=\"seg-popup-header\">\n                <h1 class=\"seg-popup-title\">[[title]]</h1>\n            </div>\n        [[/title]]\n        <div class=\"seg-popup-content\">\n            <div class=\"seg-banner-container\">\n                [[#url]]<a href=\"[[url]]\" target=\"_blank\">[[/url]]\n                <img src=\"[[image]]\" />\n                [[#url]]</a>[[/url]]\n            </div>\n        </div>\n    </div>\n    <span class=\"seg-popup-close\"></span>\n</div>",
        "css": "",
        "preJs": "function preRenderConf(conf) { /* add your custom code inside this function */ }",
        "postJs": "",
        "pureHtml": "true"
      }
    ]
  ]
}

Response object has a list of actions inside search array. An example action definition (before-search) is given below:

{
  "search": [
    [
      {
        "categoryProducts": {
          "category > category1 > category2": [
            {
              "productId": "72155",
              "name": "Product Name",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Product Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "brands": {
          "Brand": "https://www.example.com/Brand?_sgm_campaign=bs_brand&_sgm_source=Brand&_sgm_action=search&_sgm_term="
        },
        "keywords": {
          "dress": [
            {
              "productId": "72155",
              "name": "Dress",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ],
          "dress2": [
            {
              "productId": "72156",
              "name": "Dress2",
              "url": "https://www.example.com/product/72156/?_sgm_campaign=bs_product&_sgm_source=72156%7Ccategory&_sgm_action=search&_sgm_term=72156",
              "image": "https://www.example.com/72156.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Product Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "brandProducts": {
          "Brand": [
            {
              "productId": "72155",
              "name": "Dress",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "hasData": true,
        "lastSearches": [

        ],
        "campaign": {

        },
        "categories": {
          "category > category1 > category2": "https://www.example.com/category_category1_category2?_sgm_campaign=bs_category&_sgm_source=category_category1_category2&_sgm_action=search&_sgm_term="
        },
        "incremental": false,
        "banners": [
          {
            "id": "searchb_f38af653fbd18000",
            "instanceId": "fcs_9d9d5a4bf8000",
            "status": "ACTIVE",
            "searchType": "instant",
            "name": "Name Of The Banner",
            "bannerUrl": "https://www.example.com/examlpe.png",
            "targetUrl": "https://www.example.com/example_page.html?_sgm_campaign=searchb_f38af653fbd18000&_sgm_source=fcs_9d9d5a4bf8000%7Cbanner&_sgm_action=search&_sgm_term=term",
            "position": "FILTERS_FOOTER",
            "width": "100%",
            "height": "auto",
            "method": "URL",
            "newtab": false
          }
        ],
        "products": [
          {
            "productId": "72155",
            "name": "Dress",
            "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
            "image": "https://www.example.com/72155.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          },
          {
            "productId": "72156",
            "name": "Dress2",
            "url": "https://www.example.com/product/72156/?_sgm_campaign=bs_product&_sgm_source=72156%7Ccategory&_sgm_action=search&_sgm_term=72156",
            "image": "https://www.example.com/72156.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Product Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          }
        ]
      }
    ]
  ],
  "campaigns": [
    []
  ],
  "responses": [
    []
  ],
  "statusCode": "SUCCESS",
  "timestamp": 1665652596632
}

Response object has a list of actions inside search array. An example action definition (after-search) is given below:

{
  "search": [
    [
      {
        "brands": {
          "Brand": "https://www.example.com/Brand?_sgm_campaign=brand&_sgm_source=Brand&_sgm_action=search&_sgm_term="
        },
        "keywords": {

        },
        "synonyms": [

        ],
        "incremental": false,
        "banners": [

        ],
        "meanings": [

        ],
        "products": [
          {
            "productId": "72155",
            "name": "Dress",
            "url": "https://www.example.com/product/72155/?_sgm_campaign=bproduct&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
            "image": "https://www.example.com/72155.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          },
          {
            "productId": "72156",
            "name": "Dress2",
            "url": "https://www.example.com/product/72156/?_sgm_campaign=product&_sgm_source=72156%7Ccategory&_sgm_action=search&_sgm_term=72156",
            "image": "https://www.example.com/72156.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Product Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          }
        ],
        "categoryProducts": {
          "category > category1 > category2": [
            {
              "productId": "72155",
              "name": "Product Name",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Product Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "contents": [

        ],
        "meta": {
          "brand": [
            {
              "value": "Brand",
              "count": 177
            },
            {
              "value": "Brand1",
              "count": 19
            },
            {
              "value": "Brand2",
              "count": 9
            },
            {
              "value": "Brand3",
              "count": 9
            }
          ],
          "category": [
            {
              "value": "category > category1 > category2",
              "count": 1291
            },
            {
              "value": "category > category1 > category3",
              "count": 1034
            },
            {
              "value": "category5 > category6 > category7",
              "count": 325
            },
            {
              "value": "category5 > category6 > category8",
              "count": 49
            }
          ],
          "product": {
            "value": "static",
            "count": 165
          }
        },
        "brandProducts": {
          "Brand": [
            {
              "productId": "72155",
              "name": "Dress",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "campaign": {

        },
        "categories": {
          "category > category1 > category2": "https://www.example.com/category_category1_category2?_sgm_campaign=category&_sgm_source=category_category1_category2&_sgm_action=search&_sgm_term="
        }
      }
    ]
  ],
  "campaigns": [
    []
  ],
  "responses": [
    []
  ],
  "statusCode": "SUCCESS",
  "timestamp": 1665651163536
}

Response object has a list of actions inside search array. An example action definition (searchandising) is given below:

{
  "search": [
    [
      {
        "facets": [
          {
            "property": "gender",
            "items": [

            ],
            "filtered": [

            ],
            "viewMode": "picklist"
          },
          {
            "property": "sizes",
            "items": [

            ],
            "filtered": [

            ],
            "viewMode": "picklist"
          },
          {
            "property": "price",
            "items": [
              {
                "value": "24.95 - 3699.0",
                "count": 56
              }
            ],
            "filtered": [

            ],
            "viewMode": "sliding"
          },
          {
            "property": "category",
            "items": [
              {
                "value": "Tablet > Tech > Case",
                "count": 43
              },
              {
                "value": "Tablets > Tech > Computing > Tablet Cases",
                "count": 7
              },
              {
                "value": "TV > TV's by Brand > TV",
                "count": 2
              },
              {
                "value": "Tablets > Tech > Computing",
                "count": 1
              }
            ],
            "filtered": [

            ],
            "viewMode": "treeview"
          },
          {
            "property": "brand",
            "items": [
              {
                "value": "Barand1",
                "count": 40
              },
              {
                "value": "Brand2",
                "count": 1
              }
            ],
            "filtered": [

            ],
            "viewMode": "picklist"
          },
          {
            "property": "colors",
            "items": [
              {
                "value": "Black",
                "count": 4
              },
              {
                "value": "Silver",
                "count": 3
              },
              {
                "value": "Bronze",
                "count": 1
              },
              {
                "value": "Green",
                "count": 1
              },
              {
                "value": "Mystic Black",
                "count": 1
              },
              {
                "value": "Mystic Pink",
                "count": 1
              },
              {
                "value": "Mystic Silver",
                "count": 1
              },
              {
                "value": "Rose Gold",
                "count": 1
              },
              {
                "value": "White",
                "count": 1
              }
            ],
            "filtered": [

            ],
            "viewMode": "picklist"
          }
        ],
        "meta": {
          "total": 118,
          "page": {
            "current": 1,
            "rows": 60,
            "prev": false,
            "next": true
          },
          "params": {
            "defaultOrder": "BEST_MATCH",
            "currentRow": 60,
            "currency": "€",
            "isCurrencyPlaceBefore": true
          }
        },
        "contents": [

        ],
        "banners": [
          {
            "id": "searchb_f38af653fbd18000",
            "instanceId": "fcs_9d9d5a4bf8000",
            "status": "ACTIVE",
            "searchType": "faceted",
            "name": "Name Of The Banner",
            "bannerUrl": "https://www.example.com/examlpe.png",
            "targetUrl": "https://www.example.com/example_page.html?_sgm_campaign=searchb_f38af653fbd18000&_sgm_source=fcs_9d9d5a4bf8000%7Cbanner&_sgm_action=search&_sgm_term=term",
            "position": "FILTERS_FOOTER",
            "width": "100%",
            "height": "auto",
            "method": "URL",
            "newtab": false
          }
        ],
        "meanings": [

        ],
        "products": [
          {
            "productId": "72155",
            "name": "Product Name",
            "url": "https://www.example.com/product/72155/?_sgm_campaign=fcs_9d9d5a4bf8000&_sgm_source=72155%7Cproduct&_sgm_action=search&_sgm_term=72155",
            "image": "https://www.example.com/72155.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "Brands > Product Brand"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Product Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          }
        ],
        "instanceId": "fcs_9d9d5a4bf8000"
      }
    ]
  ]
}

If request is taken successfully, but there is an error with the request, statusCode variable shows the error. Example format of response body indicating an error is given below:

{
    "timestamp": "",
    "responses": [],
    "statusCode": "NO_DOMAIN_APIKEY_MATCH"
}

Details of response errors are given in section API Errors

API Errors

If your request body has a field statusCode, then you have an error in your request. Details of errors are given in below table:

Error Code Description
NO_API_KEY Your request doesn't have an apiKey parameter, please provide apiKey parameter at the request with your account's unique api key.
NO_ACCOUNT  Given api key is not associated with a Segmentify account, please check your api key value.
FAILED_ACCOUNT Account associated with api key is not an active account. Please contact with support team to re-activate your account.
NO_DOMAIN_APIKEY_MATCH Each Segmentify account is associated with a domain. Please check your domain and provide at requests with header Origin. Check Reqeust Details for required headers.
NO_EVENT There is no events inside request body. You should add at least one event with each request.
INVALID_EVENT Event format is not acceptable.
NO_USERID Each Segmentify event should have an userId parameter, and at least one event in the request lacks this parameter.
NO_SESSIONID Each Segmentify event should have an sessionId parameter, and at least one event in the request lacks this parameter.
BAD_INPUT Your request body should be a json array of Segmentify events. It is malformed, please check your json object for validity.

User & Session Management

Each event has to have user and session id fields to uniquely identify the user using your store and current session through out the visit.

User and session ids can be generated by Segmentify and new ids can be reached by making GET requests to following url:

<DATA CENTER URL>/get/key?count=<KEY COUNT TO GENERATE>

Data Center Url is account specific and you should use the end point shown at Integrations page under Account Settings.

Example Data Center Url:

https://xxx.segmentify.com

You should ask for one key to just getting key for session id, and ask for two keys to get keys for both user id and session id.

Example Key Generate Request:

GET https://xxx.segmentify.com/get/key?count=1 // for just session id

GET https://xxx.segmentify.com/get/key?count=2 // for both user id and session id

Request Body is a simple array with number of keys you have asked for. Example request body is shown below for two key request:

["XXXXXXXXXXXXXXXXXXXXXXX","YYYYYYYYYYYYYYYYYYYY"]

Alternative approach is creating and using your own unique ids. These ids can be any string, but must be unique for each user and session.


Common Parameters

Every event in Segmentify shares common parameters and you can add these parameters to all events that will be defined later.

Details of common parameters for events are given below:

Name Type Description Example
Event
(name)
Mandatory Name of the event. Use one name from Event Types 'PAGE_VIEW' or 'CHECKOUT'
User ID
(userId)
Mandatory Unique id of the user. Please check User & Session Management for creating unique key for the user/visitor. You should send same key for every event of same user and this id must be unique among other users 'USER_1234567890'
Session ID
(sessionId)
Mandatory Unique id of the user session. Please check User & Session Management for creating unique key for the user/visitor session. You should send same key for every event of same user session and this id must be unique among other sessions 'SESSION_1234567890'
Device
(device)
Mandatory Device type of current visitor.
Possible Options are:
- 'PC'
- 'TABLET'
- 'MOBILE'
- 'ANDROID'
- 'IOS'
'PC'
User Agent
(userAgent)
Optional User Agent information of current visitor's browser 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'
Language
(lang)
Optional Type of current visitor's language.Contact us for other languages.
Default languages :
- 'TR'
- 'EN'
- 'FR'
- 'DE'
'FR'
Region
(region)
Optional Type of current visitor's region. 'EU'
Currency
(currency)
Optional Currency of product price. Must be in Short Format. If not given, account's currency will be used for the product
'EUR'
Browser
(browser)
Optional Type of current visitor's browser
Possible Options are:
- 'Chrome'
- 'Firefox'
- 'Internet Explorer'
- 'Microsoft Edge'
- 'Safari'
- 'Android'
- 'Opera'
- 'Maxthon'
- 'iPhone'
- 'iPad'
'Chrome'
Operating System
(os)
Optional Operating System of current visitor.
Possible Options are:
- 'Windows'
- 'Linux'
- 'MacOS'
- 'Android'
- 'iOS'
- 'Other'
'MacOS'
Operating System Version
(osversion)
Optional Operating System Version of current visitor. '10.13.2'
Page Url
(pageUrl)
Optional Url of the current page which the event is generated 'https://www.exampleshop.com/example-product-1/'
Referrer
(referrer)
Optional Referal Url of the current page 'https://www.google.com/'
Parameters
(params)
Optional Custom parameters of the event. Must be in map format {'FIELD_1': 'VALUE_1', 'FIELD_2': 'VALUE_2'}
Test Mode
(testMode)
Optional Test Mode Flag. If event is set to test mode, it will be only processed by campaigns in test mode and discarded in reports. Possible values are 'true' or 'false' 'false'
Next Page Flag
(nextPage)
Optional Next Page Flag. If it is set to next page mode, this event will not be sent now, but will be kept for next page load. Set this flag to true, if page is redirecting and you want to store the event to be sent at next page. Possible values are 'true' or 'false' 'false'

Page View

When a visitor views a page, this event should be sent.

Parameters can be sent with page view event is given below (you can also add common parameters):

Name Type Description Example
Category
(category)
Mandatory Category of the Page. Predefined values for Segmentify are:
- Home Page
- Product Page
- Category Page
- Basket Page
- Checkout Page
- Search Page
- 404 Page
'Product Page'
Sub Category
(subCategory)
Optional Sub-category of the page. It is used to enhance information about product and category pages.
Example: For a sports category listing page, page category should be 'Category Page' and sub category should be 'Men>Shoes>Sports'
 'Men>Shoes>Sports'

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"PAGE_VIEW",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "category":"Home Page”,
        "device":"IOS"
    }
]
BODY

!!! warning When category parameter needs to be sent as "Search Page", then squery parameters must be sent under params parameter. Squery parameter should be equal to keyword that searched

    {
        "name":"PAGE_VIEW",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "category":"Search Page”,
        "device":"PC"
        "params": {"squery":"SEARCH_KEYWORD"}
    }

Product View

When a visitor views a product, this event should be sent.

If product is also inside a page, don't forget to send a page view event with category 'Product Page' and subCategory product's category too.

Parameters can be sent with product view event is given below (you can also add common parameters):

Name Type Description Example
Product ID
(productId)
Mandatory Unique id of the product 'EXAMPLE_PRODUCT_1'
Title
(title)
Mandatory Name/Title of the product  'EXAMPLE PRODUCT'
Stock
(inStock)
Optional Product’s stock status - either true or false. If not given it is assumed to be in stock ('true') 'true'
Url
(url)
Mandatory Canonical url of the product 'https://www.exampleshop.com/example-product-1/'
Mobile Url
(mUrl)
 Optional mobile specific url for the product 'https://m.exampleshop.com/example-product-1/'
Image
(image)
Mandatory main image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1.png'
Image X-Small
(imageXS)
Optional very small image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1-xs.png'
Image Small
(imageS)
Optional small image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1-small.png'
Image Medium
(imageM)
Optional medium image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1-medium.png'
Image Large
(imageL)
Optional large image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1-large.png'
Image X-Large
(imageXL)
Optional very large image url to be used in product recommendations 'https://cdn.exampleshop.com/example-product-1-xl.png'
Category
(category)
Mandatory Hierarchical category of the product 'Men > Sports > Shoes'
Brand
(brand)
Optional Brand of the product 'EXAMPLE BRAND'
Price
(price)
 Mandatory Price of the product, must be numeric 349.99
Old/Sales Price
(oldPrice)
Optional Price of the product before sales 449.99
Special Price
(specialPrice)
Optional Price of the product for special cases 549.99
Currency
(currency)
 Optional Currency of product price. Must be in Short Format. If not given, account's currency will be used for the product 'EUR'
Gender
(gender)
Optional Gender of the product. Possible values are 'M', 'F', 'U' 'M'
Colors
(colors)
Optional Different color options of the product. Must be in array format ['black', 'red', 'blue']
Sizes
(sizes)
 Optional  Different size options of the product. Must be in array format ['small', 'medium', 'large']
Labels
(labels)
Optional Custom labels associated with the product. You can use these labels to filter products in the recommendations. Must be in array format ['top-seller', 'new-comer']
Stock Count
(stockCount)
Optional Product’s stock count 5
Stock Ratio
(stockRatio)
Optional Product’s stock ratio 55.5
Stock Count
(stockStatus)
Optional Product’s stock status 5

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"PRODUCT_VIEW",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"TABLET"
        "productId":"EXAMPLE_PRODUCT_1”,
        "title":"Example Product”,
        "inStock":"true”,
        "stockCount":512,
        "url":"https://www.exampleshop.com/example-product-1/”,
        "image":"https://cdn.exampleshop.com/example-product-1.png,
        "category":"Men>Sports>Shoes”,
        "brand":"Example Brand,
        "price":349.99,
        "oldPrice":449.99,
        "gender":"M",
        "colors":["black","red","blue"],
        "sizes":["small","medium","large"],
        "labels":["new-comer","top-seller"],
        "params":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

!!! info "Validation Rules" * language parameter should be valid * price parameter must not be greater than 9000000000 * oldPrice parameter must not be greater than 9000000000 * specialPrice parameter must not be greater than 9000000000 * stockCount parameter must not be less than 0 * stockRatio parameter must not be greater than 100 * stockStatus parameter must not be greater than 100


Basket Operations

Segmentify uses basket operations as intermediary step for measuring success of recommendations throughout the conversion funnel. Basket success rate is also reported by Micro Analytics and Bannerify to show individual performance of products, categories, brands and banners.

Basket operations are similar to page view and product view. There are two possible steps in a basket operation these are: add product to basket, remove product from basket.

Basket Event Parameters

Parameters can be sent with basket operations event is given below (you can also add common parameters):

Name Type Description Values
Basket Step
(step)
Mandatory  Basket operation type. Can be either 'add' or 'remove'  'add'
Product ID
(productId)
Mandatory Unique id of the product. Must match with product ids sent with product view event 'EXAMPLE_PRODUCT_1'
Price
(price)
Optional Price of the product in the basket. If not given, price of the product in product catalogue will be assumed 349.99
Currency
(currency)
Optional Currency of product price. Must be in Short Format. Currency of the product is used if not given  'EUR'
Quantity
(quantity)
Optional Number of items added to basket at this operation. If not given, it is assumed 1. You can also use decimals for not integer quantities like 2.3 1

Add Product to Basket

When a visitor adds a product to basket/cart, this event should be sent.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"BASKET_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"IOS",
        "step":"add",
        "productId":"EXAMPLE_PRODUCT_1",
        "price":349.99,
        "currency":"EUR",
        "quantity":2
    }
]
BODY

!!! info "Validation Rules" * quantity must not be greater than 1000000.0 * price parameter must not be greater than 9000000000

Remove Product from Basket

When a visitor removes a product from basket/cart, this event should be sent.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"BASKET_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"IOS",
        "step":"remove",
        "productId":"EXAMPLE_PRODUCT_1",
        "quantity":1
    }
]
BODY

!!! info "Validation Rules" * quantity must not be greater than 1000000.0 * price parameter must not be greater than 9000000000

Checkout Operations

Segmentify uses checkout operations to measure success of recommendations throughout the conversion funnel. Checkout information and steps are also used in email & personalization campaigns. Campaign, Micro Analytics, Bannerify and Sales reports are feed from checkout information. It is essential for both analyitcs and recommendation capabilities to function properly.

Segmentify track four different steps of checkout operation:

Operation Step Details
View Basket basket When customer views the basket page. Some online stores has dedicated basket pages, others have basket detail pop-ups. For both use cases we recommend you to send checkout event with basket details. To see details, please click
Customer Information customer This is the second step on checkout funnel. When customer is entering his personal information details, this event should be send to Segmentify. To see details, please click
Payment Information payment When customer is on payment stage of checkout funnel, you should send this event to Segmentify.To see details, please click
Purchase/Success purchase Final step of checkout funnel is purchase and Segmentify uses this step as success indicator for recommendations. Reports for campaigns (both recommendation and engagement), sales analysis and real-time analtyics are dependent to this event and shoukd be implemented with great care. To see details, please click

Checkout Event Parameters

Parameters can be sent with checkout operations event is given below (you can also add common parameters):

Name Type Description Values
Step
(step)
Mandatory Checkout operation type. Can be one of the followings 'view-basket', 'customer-info', 'payment-info' or 'purchase' 'purchase'
Basket ID
(basketId)
Optional Unique id of the basket. 'EXAMPLE_BASKET_ID'
Total Price
(totalPrice)
Optional Total price of the product/s in the basket. 349.99
Order No
(orderNo)
Optional Unique id of the order, should be sent via only 'purchase' step 'EXAMPLE_UNIQUE_ORDER_NO'

View Basket

View Basket is the first step of checkout funnel, and followed by Customer Information.

When a visitor views his/her basket/cart, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"PC",
        "step":"view-basket",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

!!! info "Validation Rules" * totalPrice parameter must not be greater than 90000000000 * price parameter under productList must not be greater than 9000000000 * oldPrice parameter under productList must not be greater than 9000000000 * quantity parameter under productList must not be greater than 1000000.0

Customer Information

Customer Information is the second step of checkout funnel, and preceeded by View Basket & followed by Payment Information.

When a visitor enters customer information as second step of checkout funnel, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"PC",
        "step":"customer-info",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

!!! info "Validation Rules" * totalPrice parameter must not be greater than 90000000000 * price parameter under productList must not be greater than 9000000000 * oldPrice parameter under productList must not be greater than 9000000000 * quantity parameter under productList must not be greater than 1000000.0

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

Payment Information

Payment Information is the third step of checkout funnel, and preceeded by Payment Information & followed by Purchase/Success.

When a visitor enters payment information as third step of checkout funnel, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"PC",
        "step":"payment-info",
        "totalPrice":999.99,
        "currency":"EUR",
        "cartUrl":"http://www.exampleshop.com/cart/cart-1234567890/"
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

!!! info "Validation Rules" * totalPrice parameter must not be greater than 90000000000 * price parameter under productList must not be greater than 9000000000 * oldPrice parameter under productList must not be greater than 9000000000 * quantity parameter under productList must not be greater than 1000000.0

Purchase/Success

Purchase/Success is the fourth and final step of checkout funnel, and preceeded by Payment Information.

When a visitor finalizes a purchase, this event should be sent with basket details.

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CHECKOUT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",
        "device":"ANDROID",
        "step":"purchase",
        "totalPrice":999.99,
        "orderNo":"UNIQUE_ORDER_NO"
        "currency":"EUR",
        "productList":[
            {
                "productId":"EXAMPLE_PRODUCT_1",
                "price":349.99,
                "currency":"EUR",
                "quantity":2
            },
            {
                "productId":"EXAMPLE_PRODUCT_2",
                "price":249.99,
                "currency":"EUR",
                "quantity":1
            }
        ]
    }
]
BODY

Please refer to View Basket Step of Checkout for basket products detail and use the same information throughout the purchase funnel by only changing step information.

!!! info "Validation Rules" * totalPrice parameter must not be greater than 90000000000 * price parameter under productList must not be greater than 9000000000 * oldPrice parameter under productList must not be greater than 9000000000 * quantity parameter under productList must not be greater than 1000000.0

Checkout Parameters

Detailed explanation for each parameter is given below:

Name Type Description Example
Checkout Step
(step)
Mandatory Identifies which step of the checkout funnel. Each step has different meaning and use it accordingly 'basket'
Total Price/Amount
(totalPrice)
Mandatory Total amount of the basket including taxes, shipping costs and also discounts 999.99
Currency
(currency)
Optional Currency of the total amount of the basket. Must be in Short Format. If not given, currency of the account is used 'EUR'
Order No
(orderNo)
Optional Your unique id of the order. Send this value only for purchase/succeess step and you can access to this id on sales report 'ord_XXXXXX'
Cart Url
(cartUrl)
Optional Permalink for accessing basket at later stages. Should be used for view basket, customer information and payment information steps of checkout. This url can be used at engagement campaigns like cart abondonment reminders. Customers will be informed with this url with out-bound channels like email and push messages. If not given, account's default cart url will be used (which can be adjusted from account settings in panel)  'https://www.exampleshop.com/cart/cart-1234567890/'
Products Mandatory List of products inside the basket. Must be in array format. Details are given at product parameters [product1,product2]

Basket Product Parameters

Each product inside the basket can be defined with following parameters. See Checkout Parameters for defining checkout operation in which basket product is also defined.

Name Type Description Example
Product ID
(productId)
Mandatory Unique id of the product 'EXAMPLE_PRODUCT_1'
Price Optional Price of the product in the basket. If not given, price of the product in the product catalogue will be used 349.99
Currency Optional Currency of product price. Must be in Short Format. If not given, currency of the product in the product catalogue will be used  'EUR'
Quantity Optional Number of items from current product in the basket. If not given, it is assumed to be 1 1

User/Visitor Operations

Segmentify tracks important user operations like sign-up/register, sign-in/login, sign-out/logout and also you can share your customer's information with Segmentify by sending an update event.

There are 4 possible user/visitor operations:

  1. User Register/Sign-up: It should be sent when a visitor signed up to your website, to see details please click
  2. User Login/Sign-in: It should be sent when a registered user logins to your website, to see details please click
  3. User Logout/Sign-out: It should be sent when a registered user logouts from your website, to see details please click
  4. User Update: It should be sent when you want to share registered user's information (ex: name, email, phone number, etc.) with Segmentify. These information can be used at campagin templates to customize message or email address is used for email out-bound campaigns like abandoned cart reminders. To see details please click

New User

When a visitor registers (sign-up) to your website, you should send a new user event.

If you want to share details of an already registered user with Segmentify, please use User Update.

Details of parameters of new user is given below:

Name Type Description Example
User Operation
(step)
Mandatory Identifies which operation is taken for current user/customer. Each operation has differen meaning and use it accordingly 'signup'
Username
(username)
Mandatory Unique identifier for the customer 'johndoe'
Full Name
(fullName)
Optional Full name of the customer.  'John Doe'
Email
(email)
Optional
(Mandatory for using email module)
Email address of the customer  'john.doe@exampleshop.com'
Mobile Phone
(phone)
Optional Mobile phone number of the customer  '+1 555 555 5555'
Gender
(gender)
Optional Gender of the customer. Must be either 'M' or 'F'  'M'
Age
(age)
Optional Age of the customer. Must be numeric. Either use age or birthdate  27
Birthdate
(birthdate)
Optional Birthdate of the customer. Must be in format 'DD.MM.YYYY'. Either use age or birthdate  '23.01.1980'
Membership Date
(memberSince)
Optional Membership date of the customer. Must be in format 'DD.MM.YYYY'  '20.01.2014'
Location
(location)
Optional Location of the customer  'New York'
Customer Segments
(segments)
Optional Segments of the customer. Must be in array format  ['SEGMENT 1', 'SEGMENT 2']

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signup",
        "username":"CUSTOMER USERNAME",
        "fullName":"NAME SURNAME",
        "email":"EMAIL OF THE CUSTOMER",
        "phone":"MOBILE PHONE OF THE CUSTOMER",
        "gender":"GENDER OF THE CUSTOMER",
        "age":18,
        "memberSince":"23.01.2014",
        "location":"LOCATION OF THE CUSTOMER",
        "segments":["segment1","segment2"]
    }
]
BODY

User Login

When a registered customer logins (sign-in), a user login event should be sent to Segmentify.

Details of parameters of user login is given below:

Name Type Description Example
User Operation
(step)
Mandatory Identifies which operation is taken for current user/customer 'signin'
Username Mandatory Unique identifier for the customer 'johndoe'

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signin",
        "username":"CUSTOMER USERNAME"  
    }
]
BODY

User Logout

When a registered customer logouts (sign-out), a user logout event should be sent to Segmentify.

Details of parameters of user logout is given below:

Name Type Description Example
User Operation
(step)
Mandatory Identifies which operation is taken for current user/customer 'signout'
Username Mandatory Unique identifier for the customer 'johndoe'

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"signout",
        "username":"CUSTOMER USERNAME"
    }
]
BODY

User Update

When you want to share an already registered customer information, provide details of the customer by sending an user update event. You can use both this integration for both frequently updating user information and instant updates when customer updates his/her personal information.

If you want to share a new registered user with Segmentify, please use New User.

Details of parameters of user update is given below:

Name Type Description Example
User Operation
(step)
Mandatory Identifies which operation is taken for current user/customer. Each operation has differen meaning and use it accordingly 'update'
Username
(username)
Mandatory Unique identifier for the customer 'johndoe'
Full Name
(fullName)
Optional Full name of the customer. 'John Doe'
Email
(email)
Optional
(Mandatory for using email module)
Email address of the customer 'john.doe@exampleshop.com'
Mobile Phone
(phone)
Optional Mobile phone number of the customer '+1 555 555 5555'
Gender
(gender)
Optional Gender of the customer. Must be either 'M' or 'F' 'M'
Age
(age)
Optional Age of the customer. Must be numeric. Either use age or birthdate 27
Birthdate
(birthdate)
Optional Birthdate of the customer. Must be in format 'DD.MM.YYYY'. Either use age or birthdate '23.01.1980'
Membership Date
(memberSince)
Optional Membership date of the customer. Must be in format 'DD.MM.YYYY' '20.01.2014'
Location
(location)
Optional Location of the customer 'New York'
Customer Segments
(segments)
Optional Segments of the customer. Must be in array format [ 'SEGMENT 1', 'SEGMENT 2' ]
Is Registered Flag
(isRegistered)
Optional This is an advanced parameter, use cautiously. If you want to change user's register status without sending a register event, use this flag. Value is either 'true' or 'false' 'true'
Is Login Flag
(isLogin)
Optional This is an advanced parameter, use cautiously. If you want to change user's login status without sending a login/logout event, use this flag. Value is either 'true' or 'false' 'true'
Email Opt-in Flag
(emailNtf)
Optional If user wants to opt-in for email notifications, this parameter should be used. Value is either 'true' or 'false' 'true'

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"USER_OPERATIONS",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "step":"update",
        "username":"CUSTOMER USERNAME",
        "fullName":"NAME SURNAME",
        "email":"EMAIL OF THE CUSTOMER",
        "phone":"MOBILE PHONE OF THE CUSTOMER",
        "gender":"GENDER OF THE CUSTOMER",
        "age":18,
        "memberSince":"23.01.2014",
        "location":"LOCATION OF THE CUSTOMER",
        "segments":["segment1","segment2"]
    }
]
BODY

Custom Event

This integration enables any event & data important for you to be tracked by Segmentify and become actionable. With this integration, you can send any non standard events & data to Segmentify, and gives endless opportunities to track and take actions to your visitor's behaviour.

Details of parameters of custom event is given below:

Name Type Description Example
Type
(type)
Mandatory Type of the event. You should use same type for same events 'my_custom_event'
Custom Parameters
(params)
Optional Custom parameters of the event. Must be in map format. '{"field1":"value1", "field2":"value2"}'

An example curl request is given below:

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name":"CUSTOM_EVENT",
        "userId":"XXXXXXXXXXXXXXXXXXX",
        "sessionId":"YYYYYYYYYYYYYYYYYYYYY",
        "pageUrl":"http://www.exampleshop.com/",
        "referrer":"",      
        "device":"MOBILE",
        "type":"my_custom_event",
        "params":{
            "field1":"value1",
            "field2":"value2"
        }
    }
]
BODY

This document explains how the search-box request is sent in accounts using the search-box product. In this document, you can find information about the possible values of the parameters in the request body.

Here you can see the sample request body:

[
   {
       "name": "SEARCH",
       "userId": "XXXXXXXXXXXXXXXXX",
       "sessionId": "YYYYYYYYYYYYYYYY",
       "lang": "EN",
       "currency": "",
       "region": "",
       "query": "",
       "type": "instant"
   }
]

Request Parameters with their explanations

Parameter Type Description Example
name Mandatory name of the event. SEARCH
userId Mandatory unique id of the user. USER_1234567890
sessionId Mandatory unique id of the user session. SESSION_1234567890
lang Mandatory language of the relevant account. TR, EN, FR, DE
currency Optional currency contains the currency symbol of the account. EUR
region Optional region of the relevant account. EU
query Mandatory query property represents the keyword that search should be executed on. For before-search query must be empty, for after-search query must contain at least 3 characters Dress
type Mandatory type of the request. must be instant

You can use the sample cURL below by changing the values of the parameters depending on your account information and the request you want to send.

Request

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name": "SEARCH",
        "userId": "XXXXXXXXXXXXXXXXXXX",
        "sessionId": "YYYYYYYYYYYYYYYYYYYYY",
        "testMode": "false",
        "device": "PC",
        "recommendIds": [],
        "pageUrl": "http://www.exampleshop.com/",
        "referrer": "",
        "lang": "EN",
        "currency": "",
        "region": "",
        "query": "black",
        "type": "instant"
    }
]'

Response

Segmentify Search requests return a json object as response. An example format of response body is given below:

{
  "search": [
    [
      {
        "categoryProducts": {
          "category > category1 > category2": [
            {
              "productId": "72155",
              "name": "Product Name",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Product Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "brands": {
          "Brand": "https://www.example.com/Brand?_sgm_campaign=bs_brand&_sgm_source=Brand&_sgm_action=search&_sgm_term="
        },
        "keywords": {
          "dress": [
            {
              "productId": "72155",
              "name": "Dress",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ],
          "dress2": [
            {
              "productId": "72156",
              "name": "Dress2",
              "url": "https://www.example.com/product/72156/?_sgm_campaign=bs_product&_sgm_source=72156%7Ccategory&_sgm_action=search&_sgm_term=72156",
              "image": "https://www.example.com/72156.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Product Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "brandProducts": {
          "Brand": [
            {
              "productId": "72155",
              "name": "Dress",
              "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
              "image": "https://www.example.com/72155.png",
              "price": 109.0,
              "priceText": "€109.00",
              "oldPrice": 159.0,
              "oldPriceText": "€159.00",
              "specialPriceText": "",
              "category": [
                "category > category1 > category2"
              ],
              "lastUpdateTime": 1665477420174,
              "inStock": true,
              "insertTime": 1634135806842,
              "publishTime": 1634135806842,
              "brand": "Brand",
              "params": {
                "ws_code": "",
                "variant": "false",
                "addToCartUrl": "https://www.example.com/72155",
                "sku": "PRODUCT_SKU"
              },
              "language": "EN",
              "currency": "EUR",
              "lastBoughtTime": 1660834710537
            }
          ]
        },
        "hasData": true,
        "lastSearches": [

        ],
        "campaign": {

        },
        "categories": {
          "category > category1 > category2": "https://www.example.com/category_category1_category2?_sgm_campaign=bs_category&_sgm_source=category_category1_category2&_sgm_action=search&_sgm_term="
        },
        "incremental": false,
        "banners": [
          {
            "id": "searchb_f38af653fbd18000",
            "instanceId": "fcs_9d9d5a4bf8000",
            "status": "ACTIVE",
            "searchType": "instant",
            "name": "Name Of The Banner",
            "bannerUrl": "https://www.example.com/examlpe.png",
            "targetUrl": "https://www.example.com/example_page.html?_sgm_campaign=searchb_f38af653fbd18000&_sgm_source=fcs_9d9d5a4bf8000%7Cbanner&_sgm_action=search&_sgm_term=term",
            "position": "FILTERS_FOOTER",
            "width": "100%",
            "height": "auto",
            "method": "URL",
            "newtab": false
          }
        ],
        "products": [
          {
            "productId": "72155",
            "name": "Dress",
            "url": "https://www.example.com/product/72155/?_sgm_campaign=bs_product&_sgm_source=72155%7Ccategory&_sgm_action=search&_sgm_term=72155",
            "image": "https://www.example.com/72155.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          },
          {
            "productId": "72156",
            "name": "Dress2",
            "url": "https://www.example.com/product/72156/?_sgm_campaign=bs_product&_sgm_source=72156%7Ccategory&_sgm_action=search&_sgm_term=72156",
            "image": "https://www.example.com/72156.png",
            "price": 109.0,
            "priceText": "€109.00",
            "oldPrice": 159.0,
            "oldPriceText": "€159.00",
            "specialPriceText": "",
            "category": [
              "category > category1 > category2"
            ],
            "lastUpdateTime": 1665477420174,
            "inStock": true,
            "insertTime": 1634135806842,
            "publishTime": 1634135806842,
            "brand": "Product Brand",
            "params": {
              "ws_code": "",
              "variant": "false",
              "addToCartUrl": "https://www.example.com/72155",
              "sku": "PRODUCT_SKU"
            },
            "language": "EN",
            "currency": "EUR",
            "lastBoughtTime": 1660834710537
          }
        ]
      }
    ]
  ],
  "campaigns": [
    []
  ],
  "responses": [
    []
  ],
  "statusCode": "SUCCESS",
  "timestamp": 1665652596632
}
Name Type Description
campaign
SearchCampaignModel? Search Campaign object.
products
[ProductRecommendationModel]? Products for product list.
errorString
String? Error message in case of unexpected results.
instanceId
String? Campaign instanceId. It will be used on events.
interactionId
String? Identity of the action.
banners
[SearchBannerModel]? Search banners list.
meanings
[String]? List of alternative keywords. It uses for 'did you mean' feature.
lastSearches
[String]? List of user's last searched words.
brands
String:String? Map of brand name and its tracking url. It uses for brand asset.
brandProducts
String:[ProductRecommendationModel]? Map of brand name and list of its products.
categories
String:String? Map of category name and its tracking url. It uses for category asset.
categoryProducts
String:[ProductRecommendationModel]? Map of category name and list of its products.
keywords
String:[ProductRecommendationModel]? Map of keyword and list of its products. It uses for keyword asset.
SearchCampaignModel
Name Type Description
instanceId
String? Campaign instanceId. It will be used on events.
name
String? Campaign name.
status
String? campaign status like ACTIVE/TEST
devices
String? Available device list.
searchDelay
Int? delay for calling search event.
minCharacterCount
Int? min character count in input to call search event.
searchUrlPrefix
String? search url prefix of website
mobileItemCount
Int? max product count to be displayed
stringSearchAssetTextMap
[String:SearchAssetTextModel] language based map of titles
SearchAssetTextModel
Name Type Description
popularProductsText
String? title for popular products on cold start.
mobileCancelText
String? title for cancel button.
notFoundText
String? title for no result.

Searchandising

This document explains how the searchandising request is sent in accounts using the searchandising product. In this document, you can find information about the possible values of the parameters in the request body.

Here you can see the sample request body:

[
    {
        "name": "SEARCH",
        "userId": "XXXXXXXXXXXXXXXXX",
        "sessionId": "YYYYYYYYYYYYYYYY",
        "lang": "EN",
        "currency": "",
        "region": "",
        "query": "",
        "type": "faceted",
        "ordering": {
            "page": 1,
            "sort": "BEST_SELLERS"
        },
        "filters": [
            {
                "facet": "",
                "values": [
                    ""
                ]
            }
        ],
        "trigger": "filter",
        "service": "default",
        "mode": "LIVE"
    }
]

Request Parameters with their explanations

Parameter Type Description Example
name Mandatory name of the event. SEARCH
userId Mandatory unique id of the user. USER_1234567890
sessionId Mandatory unique id of the user session. SESSION_1234567890
lang Optional language of the relevant account. TR, EN, FR, DE
currency Optional currency contains the currency symbol of the account. EUR
region Optional region of the relevant account. EU
query Mandatory query property represents the keyword that search should be executed on. black
type Mandatory type of the request. must be faceted
ordering Optional ordering property represents the sort options that should be applied to the search result and the bucket number to retrieve. sort property is optional and if it’s not provided then the search module sorts the search result based on the default order provided on the faceted campaign. { "page": 1, "sort":"BEST_SELLERS" }
filters Optional filters property represents the facets that the user requests to be applied on the search results. facet property is equal to the property value of the related facet. If no filter will be applied to the search results, then filters must be sent as an empty array. [ { "facet": "brand", "values": [ "BARRACUDA" ] } ]
trigger Optional The purpose of trigger property is to provide data for search analytics reports. This property can take the following values: keyword, filter, page, order.
service Optional service property decides which faceted campaign should be executed. It’s default value is default. default
mode Optional mode property represents the campaign type. It’s default value is LIVE. Search SDK sets this property based on the query parameter _sgm_search_mode. LIVE

You can see the detailed trigger values’ descriptions below:

Parameter Description
keyword Sent when the run function of SegmentifySearch is called. It represents the facet search event triggered by the keyword entered on the search box
filter Sent when there is a change on facets
page Sent when the page number is changed
order Sent when order type is changed

Possible sort options for ordering parameter:

Parameter Description
BEST_MATCH Sorting based on text-based relevancy in Solr.
SMART_SORTING Sorting according to score first and then rockScore.
ALPHABETICAL_DESC Sort alphabetically descending. (Z-A)
ALPHABETICAL_ASC Alphabetically ascending order (A-Z)
PRICE_DESC Sort by product's price in descending order. (9-0)
PRICE_ASC Sort by product's price ascending. (0-9)
BEST_SELLERS Sorting by most preferred products
NEWEST Sorting by Solr Query by time of product release.

You can use the sample cURL below by changing the values of the parameters depending on your account information and the request you want to send.

Request

curl \
    --url 'https://xxx.segmentify.com/add/events/v1.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
    --request POST \
    --header 'Origin: http://www.exampleshop.com' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data-binary @- <<BODY
[
    {
        "name": "SEARCH",
        "userId": "XXXXXXXXXXXXXXXXXXX",
        "sessionId": "YYYYYYYYYYYYYYYYYYYYY",
        "testMode": "false",
        "device": "PC",
        "recommendIds": [],
        "pageUrl": "http://www.exampleshop.com/",
        "referrer": "",
        "lang": "EN",
        "currency": "",
        "region": "",
        "query": "black",
        "type": "faceted",
        "ordering": {
            "page": 1,
            "sort": "BEST_SELLERS"
        },
        "filters": [
            {
                "facet": "",
                "values": [
                    ""
                ]
            }
        ],
        "trigger": "filter",
        "service": "default",
        "mode": "LIVE"
    }
]'

Response

Segmentify Search requests return a json object as response. An example format of response body is given below:

{
   "search": [
       [
            {
                "facets": [],
                "meta": {},
                "contents": [],
                "queryVerboseLog": {},
                "banners": [],
                "meanings": [],
                "products": [],
                "executable": true
            }
       ]
   ],
   "campaigns": [
       []
   ],
   "coupons": [
       []
   ],
   "responses": [
       []
   ],
   "statusCode": "SUCCESS",
   "timestamp": 1648648320117
}
Parameter Description Example
facets facet property is equal to the property value of the related facet (which is given when facet is selected through the Segmentify panel). "facets": [ { "property": "gender", "items": [ { "value": "female", "count": 10 } ] } ]
meta meta property contains sorting, pagination and some additional information about the faceted search. "meta": { "total": 21, "page": { "current": 1, "rows": 60, "prev": false, "next": false }, "params": { "currentRow": 21, "currency": "€ ", "isCurrencyPlaceBefore": false } }
contents contents array includes custom contents to customize your personalized searchandising page. These custom contents can be set through the Segmentify panel.
banners It is the list containing json objects containing the information of the banners that come as a result of this search, such as name, id, bannerUrl, targetUrl, position. "banners": [ { "id": "xxx", "instanceId": "yyy", "status": "ACTIVE", "searchType": "faceted", "name": "coppia", "bannerUrl": "", "targetUrl": "", "position": "zzz", "width": "100%", "height": "200px", "method": "URL", "newtab": false } ]
meanings meanings property suggestion for misspelled words. [ "shoes", "shoe"]
products product property includes product information fed by our customer success team. "products": [ { "productId": "2757307", "name": "aaa", "url": "xxx", "image": "yyy", "imageS": "zzz", "price": 360.0, "priceText": "360.00 € ", "oldPriceText": "", "specialPriceText": "", "lastUpdateTime": 1, "inStock": true, "insertTime": 2, "publishTime": 3, "brand": "BARRACUDA", "gender": "Male", "sizes": [ "45" ], "params": { "currency": "", "additionalImage": "ttt", "isDiscount": "false" }, "language": "EN", "currency": "EUR", "groupId": "506841" } ]
executable executable returns whether the campaign is executable or not. Returns true or false. true if there is a campaign to run, false otherwise. true

Interaction

Interaction events needs to be sent to use the information from widgets.

Impression

Impression is used when the page's widget is received.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the campaign scn_6186a632e0d76001
interactionId
String Mandatory Identity of the action act_6185c1e624ab0000
type
String Mandatory Type of Interaction Event impression
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "impression",
    "interactionId": "act_3b0acb2738bf0001",
    "instanceId": "scn_3b0acb2738bf0000"
  }
]

!!! warning When Searchbox recommendation has been requested and successful response has been received then interaction event should be sent via following values

If searchbox recommendation is before search
```
    "instanceId":"BEFORE_SEARCH",
    "interactionId":"static"
```

If searchbox recommendation is after search
```
"instanceId":"SEARCH",
"interactionId":"static"
```

Widget View

Widget View is used when the page's widget is actually displayed.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the campaign scn_6186a632e0d76001
type
String Mandatory Type of Interaction Event widget-view
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "widget-view",
    "instanceId": "scn_3b0acb2738bf0000"
  }
]

!!! warning When Searchbox recommendation has been requested and successful response has been received then interaction event should be sent via following values

If searchbox recommendation is before search
```
    "instanceId":"BEFORE_SEARCH",
    "interactionId":"static"
```

If searchbox recommendation is after search
```
"instanceId":"SEARCH",
"interactionId":"static"
```

Click

It is necessary to notify the product productId and which campaign it belongs to when it is clicked on a product in any recommendation.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the campaign instanceId = "scn_6186a632e0d76001"
interactionId
String Mandatory Unique id of the product interactionId = "25803234569"
type
String Mandatory Unique id of the product click
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "click",
    "instanceId": "scn_3b0acb2738bf0000",
    "interactionId": "UNIQUE_PRODUCT_ID"
  }
]

Search Click

It is necessary to notify the productId when it is clicked on a product in any search result.

If identity of the campaign in search response is "BEFORE_SEARCH" then instanceId should be bs_product.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the product for before search input instanceId = "bs_product"
interactionId
String Mandatory Unique id of the product for before search input interactionId = "123456789"

If identity of the campaign in search response is "SEARCH" then instanceId should be product.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the product for after search input instanceId = "product"
interactionId
String Mandatory Unique id of the product for after search input interactionId = "123456789"
params
Map Mandatory Search query of the product for after search input {term = "SEARCH_QUERY"}
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "search",
    "instanceId": "bs_product",
    "interactionId": "UNIQUE_PRODUCT_ID"
  }
]
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "search",
    "instanceId": "product",
    "interactionId": "UNIQUE_PRODUCT_ID",
    "params" : {
      "term": "SEARCH_QUERY"
    }
  }
]

Searchandising Click

It is necessary to notify the product productId and which campaign it belongs to when it is clicked on a product in any search result.

Name Type Requirement Description Example
instanceId
String Mandatory Identity of the campaign instanceId = "fcs_aa01825dcc000"
interactionId
String Mandatory Unique id of the campaign interactionId = "123456789|product"
params
Map Mandatory Search query of the product for after search input {term = "SEARCH_QUERY"}
[
  {
    "name": "INTERACTION",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "search",
    "instanceId": "fcs_aa01825dcc000",
    "interactionId": "123456789|product",
    "params" : {
      "term": "SEARCH_QUERY"
    }
  }
]

Banners

Event Types and Definitions

Event Description Event Name
Banner Operations Events that should be sent when there is an interaction with the banner. It can be an impression, a click to the banner, or an update for banner information. BANNER_OPERATIONS
Banner Group View Event that needs to be sent for the banner group uploaded to the page. BANNER_GROUP_VIEW
Internal Banner Group The event that feeds the active banner status in the relevant group and the information of these banners to the Segmentify. INTERNAL_BANNER_GROUP

Parameters can be sent with banner operations event is given below (you can also add common parameters):

Name Type Requirement Description Example
Type
(type)
String Mandatory Banner operation type. Can be 'impression', 'click' or 'update' 'impression'
Title
(title)
String Mandatory Title of the banner 'Home Page Banner'
Group
(group)
String Mandatory Group of the banner 'Home Page Banner - Group 1'
Order
(url)
NSNumber  Mandatory Order of the banner in the group 1
Product ID
(productId)
String  Optional Unique id of the product 'EXAMPLE_PRODUCT_1'
Category
(category)
String Optional Hierarchical category of the product 'Men > Sports > Shoes'
Brand
(brand)
String Optional Brand of the product 'EXAMPLE BRAND'
Label
(label)
String Optional Custom label associated with the banner. 'top-seller'
[
  {
    "name": "BANNER_OPERATIONS",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "type": "impression",
    "title": "banner-title",
    "group": "PC Main Slider",
    "order": 1
  }
]

Parameters can be sent with banner group view event is given below (you can also add common parameters):

Name Type Requirement Description Example
Group
(group)
String Mandatory Group of the banner 'Home Page Banner - Group 1'
[
  {
    "name": "BANNER_GROUP_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "true",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC Main Slider"
  },
  {
    "name": "BANNER_GROUP_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "true",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC Ship and Magazine Banner"
  },
  {
    "name": "BANNER_GROUP_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "true",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC First Banner Group"
  },
  {
    "name": "BANNER_GROUP_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "true",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC Second Banner Group"
  },
  {
    "name": "BANNER_GROUP_VIEW",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "true",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC Blog Banner Group"
  }
]

Internal Banner Group

Parameters can be sent with banner group view event is given below (you can also add common parameters):

Name Type Requirement Description Example
Group
(group)
String Mandatory Group of the banner 'Home Page Banner - Group 1'
Banners
(banners)
Array type Any Optional List of banners. Must be in array format. Details are given at banner details [banner1,banner2]
[
  {
    "name": "INTERNAL_BANNER_GROUP",
    "userId": "XXXXXXXXXXXXXXXXX",
    "sessionId": "YYYYYYYYYYYYYYYY",
    "testMode": "false",
    "device": "PC",
    "pageUrl": "https://www.exampleshop.com/",
    "referrer": "",
    "browser": "Chrome",
    "os": "macOS",
    "osversion": "10.15.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36",
    "lang": "EN",
    "currency": "",
    "region": "",
    "async": "false",
    "globalMode": "REAL",
    "email": "",
    "ft": "1970.01.01 12:00:00.000",
    "tz": "-180",
    "group": "PC Main Slider",
    "banners": [
      {
        "title": "banner-1-title",
        "order": 1,
        "image": "https://cdn.exampleshop.com/media/banner/banner-1.jpg",
        "urls": [
          "https://www.exampleshop.com/banner-1"
        ]
      },
      {
        "title": "banner-2-title",
        "order": 2,
        "image": "https://cdn.exampleshop.com/media/banner/banner-2.jpg",
        "urls": [
          "https://www.exampleshop.com/banner-2"
        ]
      },
      {
        "title": "banner-3-title",
        "order": 3,
        "image": "https://cdn.exampleshop.com/media/banner/banner-3.jpg",
        "urls": [
          "https://www.exampleshop.com/banner-3"
        ]
      },
      {
        "title": "banner-4-title",
        "order": 4,
        "image": "https://cdn.exampleshop.com/media/banner/banner-4.jpg",
        "urls": [
          "https://www.exampleshop.com/banner-4"
        ]
      },
      {
        "title": "banner-5-title",
        "order": 5,
        "image": "https://cdn.exampleshop.com/media/banner/banner-5.jpg",
        "urls": [
          "https://www.exampleshop.com/banner-5"
        ]
      }
    ]
  }
]
Name Type Requirement Description Example
Title
(title)
String Optional Title of the banner 'Home Page Banner'
Image
(image)
String Optional Image of the banner 'https://example.com/image.jpg'
Order
(url)
NSNumber  Optional Order of the banner 1
Urls
(urls)
Array type Any Optional Urls of the banner [https://example.com/banner1]
[
  {
    "title": "banner-1-title",
    "order": 1,
    "image": "https://cdn.exampleshop.com/media/banner/banner-1.jpg",
    "urls": [
      "https://www.exampleshop.com/banner-1"
    ]
  },
  {
    "title": "banner-2-title",
    "order": 2,
    "image": "https://cdn.exampleshop.com/media/banner/banner-2.jpg",
    "urls": [
      "https://www.exampleshop.com/banner-2"
    ]
  },
  {
    "title": "banner-3-title",
    "order": 3,
    "image": "https://cdn.exampleshop.com/media/banner/banner-3.jpg",
    "urls": [
      "https://www.exampleshop.com/banner-3"
    ]
  },
  {
    "title": "banner-4-title",
    "order": 4,
    "image": "https://cdn.exampleshop.com/media/banner/banner-4.jpg",
    "urls": [
      "https://www.exampleshop.com/banner-4"
    ]
  },
  {
    "title": "banner-5-title",
    "order": 5,
    "image": "https://cdn.exampleshop.com/media/banner/banner-5.jpg",
    "urls": [
      "https://www.exampleshop.com/banner-5"
    ]
  }
]