Server-Side Hybrid 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”

Hybrid Implementation

The hybrid implementation combines elements from both frontend and server-side implementation. To ensure seamless user identification, you will need to pass the following Gravity Field values in the context of server-side API calls:

• Cookie with the user ID

• Cookie with the session ID

The values of these cookies are set differently depending on whether the user is new or returning.

For new users (interacting with the site for the first time), campaigns are requested with user.slid and session.sl set to null. In response to the "choose" request, values for cookies _slid, _slid_server, _slsession will be returned, these should be used in subsequent requests for this user. Do not set HttpOnly parameter for the new cookies.

For returning users, in hybrid requests, you will need to pass:

• In the user.slid attribute:

  • The value of the cookie _slid and/or _slid_server (if both cookies have values, pass both; in some cases, the user may have only one of these cookies). The values of cookies _slid and _slid_server passed in the requests must match their values in the user's browser.

• In the session.sl attribute:

  • The value of the cookie _slsession (if it exists). The value of the cookie _slsession passed in the requests must match its value in the user's browser.

Current values of cookies _slid, _slid_server, _slsession are returned in every response to the choose request.

Creating campaigns

Creating new API-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.

To make requests, you need to use the API keys generated in your account (you can turn to the team working on your project to get the API keys).

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 if there is no frontend secipt implemented on that page.

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: 425

{
  "user": {
    "slid": "1679843083476146043",
    "slid_server": "1679843083476146043"
  },
  "session": {
    "sl": "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: 365

{
  "user": {
    "slid": "1679843083476146043",
    "slid_server": "1679843083476146043"
  },
  "session": {
    "sl": "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 withnullin 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: 555

{
  "user": {
    "slid": "638073ccfb53d530340043f2"
  },
  "session": {
    "sl": "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 should:

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 to send 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: 868

{
  "user": {
    "slid": "638073ccfb53d530340043f2"
  },
  "session": {
    "sl": "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).