Server-Side API

Postman Collection

The API documentation includes a collection of requests with examples. It is designed for easy browsing, allowing you to explore the functionality even without a Postman account.

If you are already using Postman, you can fork and run the collection directly in your own account.

Authorization

This API uses basic authentication. For the authorization, you will need to use your section's API-key.

Your authorization header should look like this:

--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'

You can request the API Key from “Settings” → “API Keys”

Main Differences Between Server-Side and Frontend Implementation

With the API integration, it is necessary to assign IDs to users and sessions on the customer’s side.

Creating new campaigns requires the involvement of the development team, specifically for:

• Implementing a campaign request using choose.

• Processing the received response (JSON) and rendering the result.

• Passing information about a user interactions with the campaign using engagement.

Page: Sending Page View Information

For personalization to work correctly, it is necessary to send information about page views on the website (or screen views in the application) for all the users. Typically, this task is solved together with the campaign request via a dedicated parameter in the choose request (see below). However, there is also the option to send page view information separately from the campaign request using /page endpoint.

When using hybrid implementation, it is necessary to send page view information for the pages where there is no frontend script.

page: Sending Page View Information

post

Store page view event

Authorizations

bearerAuth

Body

application/json

Responses

200

Successful response

application/json

422

Bad request

post

/ssapi/page

HTTPcURLJavaScriptPython

POST /ssapi/page HTTP/1.1
Host: evs.gravityfield.ai
Content-Type: application/json
Accept: */*
Content-Length: 388

{
  "user": {
    "id": "yaexono4ohphania"
  },
  "session": {
    "custom": "iquahngaishe2koh"
  },
  "context": {
    "page": {
      "type": "PRODUCT",
      "data": [
        "p76311-020"
      ],
      "location": "https://shop.biz/nice-shirt-p76311.html",
      "referrer": "https://yandex.ru",
      "lng": "Krasnodar"
    },
    "device": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
      "ip": "54.100.200.255"
    }
  }
}

{
  "user": {
    "slid": "652956104e001b933809e082"
  },
  "session": {
    "sl": "20D05AE5-9D53-4E89-8241-797B58F5DC3D"
  },
  "hits": {
    "day": {
      "6363bd91533c119251018587": "1",
      "639af359083a980895099796": "1"
    },
    "ses": {
      "6363bd91533c119251018587": "1",
      "639af359083a980895099796": "1"
    }
  },
  "cookies": [
    {
      "name": "_slsession",
      "value": "20D05AE5-9D53-4E89-8241-797B58F5DC3D",
      "maxAge": "1800"
    }
  ]
}

Events: Transmitting Information About Events

In order to collect statistics and optimize campaigns, it is necessary to provide Gravity Field with information about user actions on the site (in the application).

List of possible events: 3. Events

It is recommended to exclude events generated by bots and the QA team from the transmitted data.

events: Transmitting Information About Events

post

Store event

Authorizations

bearerAuth

Body

application/json

Responses

200

Successful response

application/json

post

/ssapi/event

HTTPcURLJavaScriptPython

POST /ssapi/event HTTP/1.1
Host: evs.gravityfield.ai
Content-Type: application/json
Accept: */*
Content-Length: 328

{
  "user": {
    "id": "yaexono4ohphania"
  },
  "session": {
    "custom": "iquahngaishe2koh"
  },
  "context": {
    "device": {
      "ip": "54.100.200.255"
    }
  },
  "events": [
    {
      "name": "Add to Cart",
      "properties": {
        "eventType": "add-to-cart-v1",
        "value": 39.95,
        "currency": "RUB",
        "productId": "item-34454ga",
        "quantity": 1,
        "cart": [
          {
            "productId": "123456",
            "quantity": 1,
            "itemPrice": 23
          }
        ]
      }
    }
  ]
}

200

Successful response

{
  "user": {
    "slid": "652956104e001b933809e082"
  },
  "session": {
    "sl": "20D05AE5-9D53-4E89-8241-797B58F5DC3D"
  },
  "hits": {
    "day": {
      "6363bd91533c119251018587": "1",
      "639af359083a980895099796": "1"
    },
    "ses": {
      "6363bd91533c119251018587": "1",
      "639af359083a980895099796": "1"
    }
  },
  "cookies": [
    {
      "name": "_slid_server",
      "value": "6529596c0128a1ae3c09e230",
      "maxAge": "31556926"
    },
    {
      "name": "_slsession",
      "value": "20D05AE5-9D53-4E89-8241-797B58F5DC3D",
      "maxAge": "1800"
    }
  ]
}

Choose: Requesting Campaigns

Both Custom Code and Recommendations campaigns could be requested by choose.

The campaigns are identified in the requests by API Selector Name or API Selector Groups.

In case of Hybrid implementation you can use a choose-request withnull in user.slid andsession.sl to get new identifiers.

choose: Requesting Campaigns

post

Choose variation

Authorizations

bearerAuth

Body

application/json

Responses

200

Successful response

application/json

post

/ssapi/choose

HTTPcURLJavaScriptPython

POST /ssapi/choose HTTP/1.1
Host: evs.gravityfield.ai
Content-Type: application/json
Accept: */*
Content-Length: 557

{
  "user": {
    "id": "638073ccfb53d530340043f2"
  },
  "session": {
    "custom": "E4EE9F9C-72AC-4036-A3A6-F3874E779FC1"
  },
  "context": {
    "page": {
      "type": "HOMEPAGE",
      "data": [],
      "location": "shop.ru"
    },
    "device": {
      "userAgent": "Mozilla/5.0 (Linux; U; Android 8.1.0; zh-CN; EML-AL00 Build/HUAWEIEML-AL00) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/57.0.2987.108 baidu.sogo.uc.UCBrowser/11.9.4.974 UWS/2.13.1.48 Mobile Safari/537.36 AliApp(DingTalk/4.5.11) com.alibaba.android.rimet/10487439 Channel/227200 language/zh-CN",
      "ip": "54.100.200.255"
    }
  },
  "selector": {
    "names": [
      "test1"
    ]
  }
}

200

Successful response

No content

To handle errors gracefully, you need to

1. Set a response timeout.

2. In case of timeout or response different from status 200, you will need either

   • display nothing

   • display a stub (default banner, pre-installed set of products in the widget, etc.). Additionally, we recommend sending a custom fallback event to Gravity Field.

Engagement: Passing Information About Users’ Interactions With Personalization Campaigns

In order to gather valuable statistics and further optimize your campaigns, you should pass the information about users's interactions with personalization campaigns.

engagement: Passing Information About Users’ Interactions With Personalization Campaigns

post

Store click variation

Authorizations

bearerAuth

Body

application/json

Responses

200

Successful response

application/json

post

/ssapi/engagement

HTTPcURLJavaScriptPython

POST /ssapi/engagement HTTP/1.1
Host: evs.gravityfield.ai
Content-Type: application/json
Accept: */*
Content-Length: 870

{
  "user": {
    "id": "638073ccfb53d530340043f2"
  },
  "session": {
    "custom": "356A7EA8-64BD-4161-9CD1-DBAEC60FE379"
  },
  "context": {
    "page": {
      "type": "HOMEPAGE",
      "data": [],
      "location": "test.com"
    },
    "device": {
      "userAgent": "Mozilla/5.0 (Linux; U; Android 8.1.0; zh-CN; EML-AL00 Build/HUAWEIEML-AL00) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/57.0.2987.108 baidu.sogo.uc.UCBrowser/11.9.4.974 UWS/2.13.1.48 Mobile Safari/537.36 AliApp(DingTalk/4.5.11) com.alibaba.android.rimet/10487439 Channel/227200 language/zh-CN",
      "ip": "54.100.200.255"
    }
  },
  "engagements": [
    {
      "type": "CLICK",
      "decisionId": "63887d7be56d03ffa20a0eb4:63888700e56d03ffa20a0eb8:63887dca4ced2efd590e0c48:638887f598d04ac34107c155"
    },
    {
      "type": "SLOT_CLICK",
      "slotId": "638864ee8a5cfa1c840b4252:6388ae4be56d03ffa20a0eba:638865144ced2efd590e0c45:6388ad638a5cfa1c840b4258:6384c154a6f52fbd430fa182:637de30b1d1fded85d0bfcd2:0:390:0:4:1"
    }
  ]
}

200

Successful response

{
  "user": {
    "slid": "65296144f09308517c06ede7"
  },
  "session": {
    "sl": "E8A5D10B-6D76-4EF9-A9FE-6F40BDD0C4FB"
  },
  "cookies": [
    {
      "name": "_slid_server",
      "value": "65296144f09308517c06ede7",
      "maxAge": "31556926"
    },
    {
      "name": "_slsession",
      "value": "E8A5D10B-6D76-4EF9-A9FE-6F40BDD0C4FB",
      "maxAge": "1800"
    }
  ]
}

Rate limits

All requests are limited to 500 requests per second (RPS) per section.

Additional Recommendations

• Keep API keys safe and do not disclose them to third parties

• Ensure that all API calls for the same user within one session have the same User and Session IDs

• Request recommendations asynchronously to speed up content rendering

• Set a timeout for waiting for a response from the API. Prepare a default content option in advance for displaying when there is no response. It is also recommended to keep statistics on timings and cases when a response from the API was not received (additional events can be sent in case of response timeouts).

Debugging

You can view all your requests and corresponding responses in real-time in your Gravity Field account (Settings/API Logs).