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

Для того, чтобы иметь возможность собирать статистику и оптимизировать кампании, необходимо передавать в 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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gravityfield.ai/lang/server-side-api-references/peredacha-sobytii.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.