Server-Side Hybrid API
Last updated
Was this helpful?
Last updated
Was this helpful?
The API documentation includes a . 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.
This API uses . For the authorization, you will need to use your section's API-key.
Your authorization header should look like this:
You can request the API Key from “Settings” → “API Keys”
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 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).
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.
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
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.
To handle errors gracefully, you should:
Set a response timeout.
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
In order to gather valuable statistics and further optimize your campaigns, you should pass the information about users's interactions with personalization campaigns.
All requests are limited to 500 requests per second (RPS) per section.
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).
You can view all your requests and corresponding responses in real-time in your Gravity Field account (Settings/API Logs).
