> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt > Use this file to discover all available pages before exploring further. # Record recommendation events > Records an ad or recommendation event. Choose the payload by `type`; the two use different tracking tokens. ### Ad events (`type: "ad_log"`) Send `ad_log`, copied unchanged from the ad response's `ext.ad_log`. The action determines which event is recorded and how its optional values are used: | `action` | Meaning and handling | | --- | --- | | `imp` | Impression. The allocation's `ad_log_tracking_mode` controls when A2 records it: `on_ad_response` is recorded by the A2 server when it returns the ad; for supported creatives, `on_event_tracker` adds a tracker URL to the response, which the client calls when the ad is displayed. Do not also submit the same `imp` to the Log API. | | `vimp` | Viewable-impression event. This is separate from the configured `imp` tracking mode. The A2 Web SDK does not currently send `vimp` automatically. | | `clk` | Click. The A2 Web SDK sends this action without `price` by default. | | `conv` | Conversion. `conversion_data.sales` is conversion revenue; `price` is advertising cost. | `price` is an additional event cost. A2 automatically records impression cost for an `imp` it tracks, so omit `price` for that cost. Supply it only for costs A2 cannot track from the ad response, such as a conversion fee, and do not report costs already recorded by A2 again. Downstream ad metrics add supplied values to spend. `conversion_data.sales` is read for `conv` as conversion revenue and remains separate from spend. ```json {"type":"ad_log","action":"clk","ad_log":""} ``` ### Recommendation events (`type: "reco_log"`) Send `tracking_token`, copied from the recommendation response, with the affected item IDs in `event_items` and their positions in `event_position`. For `imp`, `on_ad_response` records an impression when the response returns items and a tracking token; `on_event_tracker` records it when the client reports that the recommended items were shown. The recommendation tracking mode is returned in the response's `ext.ad_log_tracking_mode`. ```json {"type":"reco_log","action":"clk","tracking_token":"","event_items":["catalog-item-123"],"event_position":[0]} ``` The request is accepted for downstream processing; acceptance does not confirm that the event was recorded. Send `type: "reco_log"`. Send `tracking_token`, copied from the recommendation response, with the affected item IDs in `event_items` and their positions in `event_position`. For `imp`, `on_ad_response` records an impression when the response returns items and a tracking token; `on_event_tracker` records it when the client reports that the recommended items were shown. The recommendation tracking mode is returned in the response's `ext.ad_log_tracking_mode`. ```bash cURL theme={null} curl --request POST \ --url https://your_a2_service/dmp/v0/log \ --header 'Content-Type: application/json' \ --data '{"type":"reco_log","action":"clk","tracking_token":"","event_items":["catalog-item-123"],"event_position":[0]}' ``` ## OpenAPI ````yaml openapi/decision.api.en-dev.json POST /dmp/v0/log openapi: 3.1.0 info: contact: email: a2support@aiderx.io name: A2 Support url: https://aiderx.io description: >+ ### Introduction The Decision API is responsible for selecting and distributing ads or content based on user requests or contextual information, all in real time. Its rapid response and dynamic capabilities enable the **optimal** ad or recommendation to be served, ensuring users receive the highest possible value. A variety of algorithms, machine learning models, and rule-based logic can be applied, allowing the system to **adapt flexibly** to constantly changing conditions. title: Decision APIs version: dev x-logo: altText: A2 Logo url: >- https://cdn.prod.website-files.com/668de9e1f25ab5675d87758d/6690cf1bdce95af5e3522c25_a2_logo_800_250.png servers: [] security: [] tags: - description: > Ad Serving APIs for requesting ads and configuring cache settings and other parameters of the ad serving modules. name: Ad Serving - description: | Recommendation Serving APIs for requesting recommendations. name: Recommendation Serving - description: >- APIs for manipulating caches of the serving server. ### **Important** If you directly manipulate the cached data related to advertising or recommendations on the Serving server, we **strongly advise** against also modifying the advertising or recommendation data through the Ad Manager. Alternatively, we **recommend** handling any advertising or recommendation data modifications via the Ad Manager APIs. Any changes made on the Serving server will **not** be reflected in the Ad Manager, which can compromise **data integrity**. name: Cache Management - description: |- APIs for manipulating configurations of the serving server name: Configuration - description: > APIs for receiving conversion, impression, and click logs related to ads or recommendations. name: Ad Log paths: /dmp/v0/log: post: tags: - Ad Log summary: Record User Log description: >- Records an ad or recommendation event. Choose the payload by `type`; the two use different tracking tokens. ### Ad events (`type: "ad_log"`) Send `ad_log`, copied unchanged from the ad response's `ext.ad_log`. The action determines which event is recorded and how its optional values are used: | `action` | Meaning and handling | | --- | --- | | `imp` | Impression. The allocation's `ad_log_tracking_mode` controls when A2 records it: `on_ad_response` is recorded by the A2 server when it returns the ad; for supported creatives, `on_event_tracker` adds a tracker URL to the response, which the client calls when the ad is displayed. Do not also submit the same `imp` to the Log API. | | `vimp` | Viewable-impression event. This is separate from the configured `imp` tracking mode. The A2 Web SDK does not currently send `vimp` automatically. | | `clk` | Click. The A2 Web SDK sends this action without `price` by default. | | `conv` | Conversion. `conversion_data.sales` is conversion revenue; `price` is advertising cost. | `price` is an additional event cost. A2 automatically records impression cost for an `imp` it tracks, so omit `price` for that cost. Supply it only for costs A2 cannot track from the ad response, such as a conversion fee, and do not report costs already recorded by A2 again. Downstream ad metrics add supplied values to spend. `conversion_data.sales` is read for `conv` as conversion revenue and remains separate from spend. ```json {"type":"ad_log","action":"clk","ad_log":""} ``` ### Recommendation events (`type: "reco_log"`) Send `tracking_token`, copied from the recommendation response, with the affected item IDs in `event_items` and their positions in `event_position`. For `imp`, `on_ad_response` records an impression when the response returns items and a tracking token; `on_event_tracker` records it when the client reports that the recommended items were shown. The recommendation tracking mode is returned in the response's `ext.ad_log_tracking_mode`. ```json {"type":"reco_log","action":"clk","tracking_token":"","event_items":["catalog-item-123"],"event_position":[0]} ``` The request is accepted for downstream processing; acceptance does not confirm that the event was recorded. requestBody: content: application/json: schema: $ref: '#/components/schemas/LogType' required: true responses: '200': description: Accepted for downstream processing. security: - '': [] components: schemas: LogType: oneOf: - allOf: - $ref: '#/components/schemas/AdLog' properties: type: const: ad_log type: string required: - type title: Ad event type: object - allOf: - $ref: '#/components/schemas/RecommendationLog' properties: type: const: reco_log type: string required: - type title: Recommendation event type: object AdLog: examples: - action: clk ad_log: type: ad_log properties: action: allOf: - $ref: '#/components/schemas/ActionType' description: Event type. Send an explicit action for each event. ad_log: description: >- Required ad tracking token: copy ext.ad_log from the ad response unchanged. type: string conversion_data: anyOf: - $ref: '#/components/schemas/ConversionData' - type: 'null' description: >- Optional conversion data. For action=conv, downstream metrics read sales as conversion revenue, separately from price/spend. Do not send purchase value as price unless it also represents advertising cost. custom_targeting: additionalProperties: true description: >- Optional custom targeting attributes forwarded to downstream ad-log processing type: - object - 'null' price: description: >- Optional additional advertising cost for this event. A2 automatically records the cost of an impression it tracks, so omit price for that cost. Supply price only for costs A2 cannot track from the ad response, such as a conversion fee, and do not report costs already recorded by A2 again. Downstream ad metrics add supplied price values to spend. This is separate from conversion revenue (conversion_data.sales). format: double type: - number - 'null' timestamp_in_ms: description: >- Optional event time as an integer Unix timestamp in milliseconds. If omitted, advertising processing uses its current time. format: int64 type: integer required: - action - ad_log type: object RecommendationLog: examples: - action: clk event_items: - catalog-item-123 event_position: - 0 timestamp_in_ms: 1760000000000 tracking_token: type: reco_log properties: action: allOf: - $ref: '#/components/schemas/ActionType' description: Event type. Send an explicit action for each event. event_items: description: >- Catalog IDs of the items involved in this event, as strings. Optional in the payload; recording recommendation interaction history requires event_items and a user ID in the tracking token. Report the affected items, for example the clicked item or the visible subset for vimp. items: type: string type: - array - 'null' event_position: description: >- Nonnegative slot positions of the affected items, copied from their recommendation response positions. Used for per-slot metrics; omitted positions produce no slots for that processing. items: format: uint64 minimum: 0 type: integer type: - array - 'null' seed_item_id: description: >- Optional nonempty seed item ID from the recommendation request, when that request used a seed item. type: - string - 'null' timestamp_in_ms: description: >- Optional event time as an integer Unix timestamp in milliseconds. Use a positive value; recommendation processing falls back to ingestion time when it is absent or invalid. format: int64 type: - integer - 'null' tracking_token: description: >- Required recommendation tracking token: copy tracking_token from the recommendation response unchanged. This is different from an ad response's ext.ad_log. type: string required: - action - tracking_token type: object ActionType: oneOf: - const: clk description: >- Click event - Records when a user clicks on an advertisement or recommended item title: clk type: string - const: vimp description: View event - Records a viewable advertisement or recommended item title: vimp type: string - const: imp description: Impression event accepted by downstream processing title: imp type: string - const: conv description: >- Conversion event - Records when a user performs a valuable action after viewing an ad. Conversions can be defined based on your business goals. Example conversion activities include: * Product purchase * Cart addition * Application installation * Service subscription * File download * Link click * Timed content consumption You can define any meaningful user action as a conversion based on your advertising objectives. title: conv type: string ConversionData: properties: sales: anyOf: - $ref: '#/components/schemas/ConversionSales' - type: 'null' description: >- Conversion revenue, consumed for action=conv. A JSON number or a numeric string is accepted by downstream metrics. type: object ConversionSales: anyOf: - format: double title: number type: number - title: string type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.