> ## 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 events > Sends user responses (impressions, clicks, conversions) to ad and recommendation results. Choose ad events (`ad_log`) or recommendation events (`reco_log`) with `type`, and copy the tracking token from the matching response unchanged. A successful response does not mean the event was recorded. Events with a modified token or fields in the wrong format are not recorded. ## Ad events (`ad_log`) Copy the ad response's `ext.ad_log` into `ad_log` and send clicks and conversions. * `clk`: Send when the user clicks the ad. * `conv`: Send when a user who saw the ad converts, for example by purchasing. Put the conversion revenue in `conversion_data.sales`. ### Ad impressions A2 records ad impressions. When it records them depends on the impression tracking mode set on the allocation in Ad Manager. * On Ad Response (`on_ad_response`, default): A2 automatically counts an impression when it sends the ad response. * On Impression Event (`on_event_tracker`): A2 records the impression when its impression tracker URL is called as the ad is displayed. A2-managed banners include the URL in `ad.display.event`; supported native responses include it in `ad.display.native.eventtrackers`. For ads without an A2 impression tracker, such as external network banners and video ads, set `on_ad_response`. A2 then automatically counts an impression when it sends the ad response, so you do not need to send a separate impression event. The impression is counted even if the ad is never displayed on screen. Do not also send `imp` to this API for an impression already recorded by A2, as it would be counted twice. `vimp` is not counted in ad metrics. ## Recommendation events (`reco_log`) Copy the recommendation response's `tracking_token`. Put the catalog IDs of the items in `event_items` and their `position` values from the response in `event_position`, in the same order. * `imp`: Send once when the recommendation list is displayed, with every item in the response. * `vimp`: Send the items that actually became visible on screen. Send each item once. * `clk`: Send the item the user clicked. * `conv`: Send the purchased item when a purchase that started from a recommended item completes. If `ext.ad_log_tracking_mode` in the recommendation response is `on_ad_response`, do not send `imp`; A2 records it when it returns the response. The default is `on_event_tracker`. Positions not in the response are not counted. ```bash Ad click theme={null} curl --request POST \ --url https://your_a2_service/dmp/v0/log \ --header 'Content-Type: application/json' \ --data '{"type":"ad_log","action":"clk","ad_log":""}' ``` ```bash Recommendation viewable impression theme={null} curl --request POST \ --url https://your_a2_service/dmp/v0/log \ --header 'Content-Type: application/json' \ --data '{"type":"reco_log","action":"vimp","tracking_token":"","event_items":["catalog-item-123","catalog-item-456"],"event_position":[0,1]}' ``` ## 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: Event Logging paths: /dmp/v0/log: post: tags: - Event Logging summary: Record events description: >- Sends user responses (impressions, clicks, conversions) to ad and recommendation results. 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_log type: object - allOf: - $ref: '#/components/schemas/RecommendationLog' properties: type: const: reco_log type: string required: - type title: reco_log 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.