> For the complete documentation index, see [llms.txt](https://developer.gravityfield.ai/lang/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gravityfield.ai/lang/server-side-api-references/peredacha-sobytii.md).

# Передача событий

Для того, чтобы иметь возможность собирать статистику и оптимизировать кампании, необходимо передавать в Gravity Field информацию о действиях пользователя на сайте или в приложении.

## POST /ssapi/event

> Report a predefined or custom event.

```json
{"openapi":"3.0.3","info":{"title":"Gravity Field SSAPI","version":"1.0.0"},"servers":[{"url":"https://evs.gravityfield.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-KEY"}},"schemas":{"user":{"type":"object","description":"User ID. A Gravity Field-generated identifier is used, and managed via cookies. For a new user, send this object empty.","properties":{"id":{"description":"External user identification","type":"string"},"slid":{"description":"The user ID assigned to visitors by Gravity Field. For a new user, send this param empty.","type":"string"},"slid_server":{"description":"The user ID assigned to visitors by Gravity Field. For a new user, send this param empty.","type":"string"}}},"session":{"type":"object","description":"Session ID. A Gravity Field-generated identifier is used. For new sessions, send this object empty.","properties":{"custom":{"description":"External session identification, used only external user id","type":"string"},"sl":{"description":"Pass the value of the _slsession cookie if it exists. Otherwise, a new session identifier will be created by Gravity Field and returned in the response.","type":"string"}}},"context":{"type":"object","description":"The request's context.","properties":{"page":{"description":"Data for the page currently being browsed.","type":"object","properties":{"type":{"description":"Page type. Must be upper case. Valid values are HOMEPAGE, CATEGORY, PRODUCT, CART, SEARCH and OTHER.","type":"string","enum":["HOMEPAGE","PRODUCT","CART","CATEGORY","SEARCH","OTHER"]},"data":{"description":"Additional data for non-homepage pages The SKU for a PRODUCT page, the category for a CATEGORY page, SKUs for the CART page, and query string for SEARCH","type":"array","items":{"type":"string"}},"lng":{"description":"Page locale code, such as ru_RU.","type":"string"},"location":{"description":"The current location. URL (for web), location (for SPA), or screen name (for mobile apps). Enables targeting the current page/screen.","type":"string"},"referrer":{"description":"The previous location. URL (for web), location (for SPA), or screen name (for mobile apps). Enables targeting the previous page/screen.","type":"string"}},"required":["type","data","location"]},"device":{"description":"Data for the served device.","type":"object","properties":{"userAgent":{"description":"For web clients, the browser user-agent string. If not passed, the API gateway checks for the header in the HTTPS request.","type":"string"},"ip":{"description":"The client IP address, for geolocation-based targeting and audience building. If not passed, the caller IP is used.","type":"string"}}}},"required":["page"]},"addToCart":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be add-to-cart-v1","type":"string"},"currency":{"description":"The currency used for the value, or use section defaults","type":"string"},"value":{"description":"The total monetary value of the event. This is the item or items added that triggered the event only, not necessarily all items in the cart.","type":"number"},"quantity":{"description":"The number of items with this SKU added to the cart in the scope of this event.","type":"number"},"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"cart":{"description":"The updated contents of the cart, including the items added to trigger this event. Each object is a unique item/SKU.","type":"array","items":{"type":"object","properties":{"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"quantity":{"description":"Number of items.","type":"integer"},"itemPrice":{"description":"Item price","type":"number"},"size":{"description":"Product size.","type":"string"}},"required":["productId","quantity","itemPrice"]}},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","value","quantity","productId"]}},"required":["name","properties"]},"purchase":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be purchase-v1.","type":"string"},"currency":{"description":"The currency used for the value, or use section defaults","type":"string"},"value":{"description":"The total monetary value of the event in the actual payment currency. This is the total value of the cart purchased, not just a triggering item.","type":"number"},"uniqueTransactionId":{"description":"When this value is passed it ensures that only one purchase is recorded for the transaction ID, even if duplicate events are reported. Optional, but recommended","type":"string"},"cart":{"description":"The cart's absolute current state. Products are ordered from the first added to the cart to the most recent.","type":"array","items":{"type":"object","properties":{"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"quantity":{"description":"Number of items.","type":"integer"},"itemPrice":{"description":"Item price","type":"number"},"size":{"description":"Product size.","type":"string"}},"required":["productId","quantity","itemPrice"]}},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","value","uniqueTransactionId","cart"]}},"required":["name","properties"]},"removeFromCart":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be remove-from-cart-v1.","type":"string"},"currency":{"description":"The currency used for the value, or use section defaults","type":"string"},"value":{"description":"The total monetary value of the event. This is the item or items added that triggered the event only, not necessarily all items in the cart.","type":"number"},"quantity":{"description":"The total number of items removed.","type":"number"},"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"cart":{"description":"The updated contents of the cart, including the items added to trigger this event. Each object is a unique item/SKU.","type":"array","items":{"type":"object","properties":{"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"quantity":{"description":"Number of items.","type":"integer"},"itemPrice":{"description":"Item price","type":"number"},"size":{"description":"Product size.","type":"string"}},"required":["productId","quantity","itemPrice"]}},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","value","productId"]}},"required":["name","properties"]},"syncCart":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be sync-cart-v1.","type":"string"},"currency":{"description":"The currency used for the value, or use section defaults","type":"string"},"cart":{"description":"The cart's absolute current state, including the last item added. Products are ordered from the first added to the cart to the most recent.","type":"array","items":{"type":"object","properties":{"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"quantity":{"description":"Number of items.","type":"integer"},"itemPrice":{"description":"Item price","type":"number"},"size":{"description":"Product size.","type":"string"}},"required":["productId","quantity","itemPrice"]}},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","cart"]}},"required":["name","properties"]},"addToWishList":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be add-to-wishlist-v1.","type":"string"},"productId":{"description":"SKU exactly as it appears in the product feed.","type":"string"},"size":{"description":"Product size.","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","productId"]}},"required":["name","properties"]},"changeAttr":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be change-attribute-v1.","type":"string"},"attributeType":{"description":"Color, size, fit, brand, author, keyword, category, or any other attribute you allow.","type":"string"},"attributeValue":{"description":"The new value (for example, new color is Gray).","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","attributeType","attributeValue"]}},"required":["name","properties"]},"filterItems":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be filter-items-v1.","type":"string"},"filterType":{"description":"Name of the filter (color, size, brand, fit, author, keyword, category...) Must correspond to a product property in your product feed.","type":"string"},"filterNumericValue":{"description":"Specify a value for this property OR for filterStringValue, but not both. This affects how segmentation conditions are run.","type":"number"},"filterStringValue":{"description":"Specify a value for this property OR for filterNumericValue, but not both. This affects how segmentation conditions are run.","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","filterType"]}},"required":["name","properties"]},"keywordSearch":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be keyword-search-v1.","type":"string"},"keywords":{"description":"The search string.","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","keywords"]}},"required":["name","properties"]},"promocodeEntered":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be enter-promo-code-v1.","type":"string"},"code":{"description":"The promo code.","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","code"]}},"required":["name","properties"]},"sortItems":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be sort-items-v1.","type":"string"},"sortBy":{"description":"Sorting parameter, such as price, age, popularity, rating, or any other you allow.","type":"string"},"sortOrder":{"description":"ASC or DESC.","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType","sortBy","sortOrder"]}},"required":["name","properties"]},"newsletterSubscription":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be newsletter-subscription-v1.","type":"string"},"cuid":{"description":"Persistent external user ID","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType"]}},"required":["name","properties"]},"signUp":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be signup-v1","type":"string"},"cuid":{"description":"Persistent external user ID","type":"string"},"cuidType":{"description":"Use this identifier type to identify users across devices (for example, customer_id or account_id).","type":"string"},"hashedEmail":{"description":"Persistent user hashed emaol","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType"]}},"required":["name","properties"]},"login":{"type":"object","properties":{"name":{"description":"A human-readable name corresponding to the schema name.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"eventType":{"description":"Must be login-v1","type":"string"},"cuid":{"description":"Persistent external user ID","type":"string"},"cuidType":{"description":"Use this identifier type to identify users across devices (for example, customer_id or account_id).","type":"string"},"hashedEmail":{"description":"Persistent user hashed emaol","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}},"required":["eventType"]}},"required":["name","properties"]},"customEvent":{"type":"object","properties":{"name":{"description":"Event name for display. Does not have a eventType property.","type":"string"},"properties":{"type":"object","description":"Data for the reported event.","properties":{"value":{"description":"The total monetary value of the event in the actual payment currency. This is the total value of the cart purchased, not just a triggering item.","type":"number"},"customProperty":{"description":"Any custom property","type":"string"},"event_time":{"type":"string","description":"Event time, used if the event was in the past. Format ISO (YYYY-MM-DDTHH:ii:ss.ms+00:00)"}}}}}},"responses":{"UnauthorizedError":{"description":"Access token is missing or invalid"},"ValidationError":{"description":"Error validation request data","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"type":{"type":"string"}}}}}}}},"paths":{"/ssapi/event":{"post":{"tags":["SSAPI"],"description":"Report a predefined or custom event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/user"},"session":{"$ref":"#/components/schemas/session"},"context":{"$ref":"#/components/schemas/context"},"events":{"description":"One or more events to report.","type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/addToCart"},{"$ref":"#/components/schemas/purchase"},{"$ref":"#/components/schemas/removeFromCart"},{"$ref":"#/components/schemas/syncCart"},{"$ref":"#/components/schemas/addToWishList"},{"$ref":"#/components/schemas/changeAttr"},{"$ref":"#/components/schemas/filterItems"},{"$ref":"#/components/schemas/keywordSearch"},{"$ref":"#/components/schemas/promocodeEntered"},{"$ref":"#/components/schemas/sortItems"},{"$ref":"#/components/schemas/newsletterSubscription"},{"$ref":"#/components/schemas/signUp"},{"$ref":"#/components/schemas/login"},{"$ref":"#/components/schemas/customEvent"}]}}},"required":["user","session","context","events"]}}}},"responses":{"200":{"description":"Successful store event","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"slid":{"type":"string","nullable":true,"description":"If a user has been created then the uid is returned. Set cookies in the frontend"}}},"session":{"type":"object","properties":{"sl":{"type":"string","nullable":true,"description":"If a session has been created then the ses is returned. Set cookies in the frontend"}}}}}}}},"204":{"description":"Successful response","content":{"text/plain":{}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/ValidationError"}}}}}}
```