> ## 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. # 추천 요청 > 광고 단위(`tagid`)의 추천 정책으로 추천 항목을 반환합니다. 응답에는 표시할 항목과 추천 이벤트에 쓰는 `tracking_token`이 포함됩니다. `user`는 포함되지 않습니다. ## OpenAPI ````yaml /openapi/decision.api.ko-dev.json post /app/v0/recommendation/{tagid} openapi: 3.1.0 info: contact: email: a2support@aiderx.io name: A2 Support url: https://aiderx.io description: |- ### 소개 Decision API는 사용자 요청 또는 컨텍스트 정보를 바탕으로 광고나 콘텐츠를 실시간으로 선택하고 배포합니다. 빠른 응답과 동적 기능을 통해 최적의 광고 또는 추천을 제공하여 사용자가 가능한 가장 높은 가치를 얻도록 합니다. 다양한 알고리즘, 머신러닝 모델 및 규칙 기반 로직을 적용할 수 있어 시스템이 끊임없이 변하는 조건에 유연하게 적응할 수 있습니다. title: Decision API 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: 광고 요청, 캐시 설정 및 광고 제공 모듈의 기타 매개변수를 구성하기 위한 API입니다. name: Ad Serving - description: 추천 요청을 위한 API name: Recommendation Serving - description: >- 광고 제공 서버의 캐시를 조작하기 위한 API입니다. ### **중요** Serving 서버의 광고 또는 추천 관련 캐시 데이터를 직접 조작하는 경우 Ad Manager에서 광고 또는 추천 데이터를 함께 수정하지 않는 것을 **강력히 권장합니다.** 대신 모든 광고 또는 추천 데이터 변경은 Ad Manager API를 통해 처리하는 것을 **권장합니다.** Serving 서버에서 변경한 내용은 Ad Manager에 반영되지 않으므로 **데이터 무결성**이 손상될 수 있습니다. name: Cache Management - description: 광고 서빙 서버 설정 API name: Configuration - description: 광고 또는 추천과 관련된 전환, 노출 및 클릭 로그를 수신하는 API입니다. name: Ad Log paths: /app/v0/recommendation/{tagid}: post: tags: - Recommendation Serving summary: 추천 요청 description: |- 광고 단위(`tagid`)의 추천 정책으로 추천 항목을 반환합니다. 응답에는 표시할 항목과 추천 이벤트에 쓰는 `tracking_token`이 포함됩니다. `user`는 포함되지 않습니다. parameters: - description: 광고 유닛의 ID입니다. 광고 관리자에서 확인할 수 있습니다. in: path name: tagid required: true schema: description: 광고 유닛의 ID입니다. 광고 관리자에서 확인할 수 있습니다. format: uuid type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendationServingRequest' required: true responses: '200': content: application/json: example: ext: ad_log_tracking_mode: on_ad_response items: - catalog_id: catalog-123 position: 0 score: 0.87 - catalog_id: catalog-234 position: 1 tracking_token: opaque-recommendation-tracking-token version: 0.1.0 schema: $ref: '#/components/schemas/RecommendationServingResponse' description: 추천 제공 성공 '400': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' text/plain; charset=utf-8: {} description: >- JSON 요청 본문의 형식이 잘못되면 text/plain을 반환합니다. 잘못된 tagid(`1300`) 또는 값이 100개를 초과하는 filter 배열(`1304`)에 대해서는 빈 items와 ext.message가 포함된 application/json 오류 응답을 반환합니다. '404': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' description: 광고 유닛을 찾을 수 없습니다(`1301`). JSON 응답에는 빈 items와 ext.message가 포함됩니다. '415': content: text/plain: schema: type: string description: '`Content-Type: application/json`인 요청이 필요합니다.' '422': content: application/json: schema: $ref: '#/components/schemas/RecommendationErrorResponse' text/plain; charset=utf-8: {} description: >- JSON 구조 또는 타입 역직렬화 오류는 text/plain을 반환합니다. 추천이 비활성화되었거나(`1302`) 적용할 수 있는 송출 정책이 없으면(`1303`) 빈 items와 ext.message가 포함된 application/json 오류 응답을 반환합니다. security: - '': [] components: schemas: RecommendationServingRequest: properties: app: anyOf: - $ref: '#/components/schemas/ServingRequestApp' - type: 'null' description: 앱 객체입니다. device: anyOf: - $ref: '#/components/schemas/Device' - type: 'null' description: 디바이스 객체입니다. examples: - null filter: description: >- 선택적인 제외 조건입니다. webtoon 카탈로그에서 `rating`은 지정한 등급보다 높은 항목을 제외하고, `exclusion_tags`는 지정한 태그 중 하나라도 겹치는 항목을 제외합니다. 조건은 제외 조건으로 결합되므로 둘 중 하나에 해당하면 항목이 제거됩니다. Creative 카탈로그 필터링은 구현되지 않았습니다. 알 수 없는 필드, null 값, 빈 배열은 후보를 필터링하지 않습니다. 알 수 없는 필드의 배열을 포함하여 모든 최상위 배열에는 최대 100개의 값을 지정할 수 있습니다. 이 제한을 초과하면 HTTP 400과 errorcode `1304`를 반환합니다. examples: - exclusion_tags: - tag:10 - taste:N rating: 2 seed_item_id: description: Association 및 Pinned처럼 시드 기반 조회를 지원하는 소스에서 사용하는 선택적인 카탈로그 ID입니다. type: - string - 'null' site: anyOf: - $ref: '#/components/schemas/ServingRequestSite' - type: 'null' description: 사이트 객체입니다. user: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: 사용자 객체입니다. examples: - gender: M id: account-187acvbvz yob: 1988 type: object RecommendationServingResponse: description: 추천 응답의 전송 형식입니다. 광고 응답과 달리 `user`를 되돌려 주지 않습니다. properties: errorcode: description: >- 오류 응답의 애플리케이션 오류 코드입니다. `1300`: 잘못된 tagid, `1301`: 광고 유닛을 찾을 수 없음, `1302`: 추천 비활성화, `1303`: 적용할 수 있는 송출 정책 없음, `1304`: filter 배열의 값이 100개를 초과함. 성공 응답에는 포함되지 않습니다. type: - string - 'null' ext: anyOf: - $ref: '#/components/schemas/RecommendationServingResponseExt' - type: 'null' description: 성공 응답의 추적 모드 또는 오류 응답의 메시지입니다. items: description: >- 추천된 카탈로그 ID, 0부터 시작하는 위치, 후보 소스가 제공하는 경우 점수입니다. 오류 시에는 빈 배열이며, 성공 응답에도 항목이 없을 수 있습니다. items: $ref: '#/components/schemas/RecommendationItem' type: array tracking_token: description: >- 이 추천 결과의 불투명한 토큰입니다. 추천 로그 이벤트에서 `tracking_token`으로 전송합니다. 오류 시에는 포함되지 않습니다. type: - string - 'null' version: description: SDK API 버전입니다. type: string required: - version - items type: object RecommendationErrorResponse: properties: errorcode: type: string ext: $ref: '#/components/schemas/RecommendationErrorDetails' items: description: 애플리케이션 오류 응답에서는 항상 빈 배열입니다. items: $ref: '#/components/schemas/RecommendationItem' maxItems: 0 type: array version: type: string required: - version - errorcode - items - ext type: object ServingRequestApp: properties: bundle: type: - string - 'null' domain: type: - string - 'null' name: type: - string - 'null' storeurl: type: - string - 'null' ver: type: - string - 'null' type: object Device: properties: ext: description: 광고 시스템별 확장을 위한 예약 필드 geo: anyOf: - $ref: '#/components/schemas/Geo' - type: 'null' description: 사용자의 현재 위치로 간주되는 기기의 위치 정보. Geo 객체로 정의됨. ip: description: 기기와 가장 가까운 IPv4 주소. type: - string - 'null' ua: description: >- 브라우저의 User-Agent 문자열입니다. 브라우저의 원시 사용자 에이전트 문자열을 나타냅니다. 하위 호환성을 위해 최종 사용자의 디바이스에서 사용할 수 있으면 대체 표현인 User-Agent Client-Hints로 `sua`를 채우더라도 `ua`를 User-Agent 문자열로 채우는 것이 권장됩니다. 이 필드에는 추론하거나 근사한 사용자 에이전트를 사용하지 않습니다. 클라이언트가 User-Agent Client Hints를 지원하고 `sua` 필드가 있으면 입찰자는 디바이스 유형, 브라우저 유형 및 버전과 사용자 에이전트 정보에 의존하는 기타 목적을 감지할 때 `sua`를 사용하고 `ua`를 무시하는 것이 권장됩니다. `ua`에는 동결되거나 축소된 사용자 에이전트 문자열이 포함될 수 있기 때문입니다. type: - string - 'null' type: object ServingRequestSite: properties: domain: type: - string - 'null' mobile: type: - boolean - 'null' name: type: - string - 'null' page: type: - string - 'null' ref: type: - string - 'null' search: type: - string - 'null' type: object User: properties: buyeruid: description: 익스체인지가 해당 바이어를 위해 매핑한 바이어별 사용자 ID type: - string - 'null' ext: description: OpenRTB의 익스체인지 전용 확장을 위한 필드 gender: anyOf: - $ref: '#/components/schemas/Gender' - type: 'null' description: 성별. “M”은 남성, “F”는 여성, “O”는 기타로 알려진 경우를 나타냅니다. 값이 없으면 알 수 없음으로 간주됩니다. geo: anyOf: - $ref: '#/components/schemas/Geo' - type: 'null' description: Geo 객체(3.2.19절)로 정의된 사용자의 거주지 위치입니다. 현재 위치와는 다를 수 있습니다. id: description: 익스체인지별 사용자 ID type: - string - 'null' keywords: description: >- 키워드, 관심사 또는 의도를 쉼표로 구분한 목록입니다. 'keywords'와 'kwarray' 중 하나만 사용할 수 있습니다. type: - string - 'null' yob: deprecated: true description: 출생 연도 (4자리 정수) format: uint16 maximum: 65535 minimum: 0 type: - integer - 'null' type: object RecommendationServingResponseExt: additionalProperties: true properties: ad_log_tracking_mode: anyOf: - $ref: '#/components/schemas/AdLogTrackingMode' - type: 'null' description: >- 적용된 노출 추적 모드입니다. `on_ad_response`이면 결과가 비어 있지 않을 때 서버가 노출을 기록합니다. `on_event_tracker`이면 서버가 기록하지 않으므로, 추천 항목이 표시될 때 `action: "imp"`와 응답의 `tracking_token`, `event_items`, `event_position`을 담은 `reco_log` 이벤트를 `/dmp/v0/log`로 보내야 합니다. message: description: 애플리케이션 오류 코드에 대한 설명입니다. type: - string - 'null' type: object RecommendationItem: description: '[`RecoResponse`]에 포함되는 추천 아이템 하나입니다.' properties: catalog_id: description: 추천 아이템 카탈로그 ID입니다. type: string position: description: |- 추천 지면의 0부터 시작하는 슬롯 위치입니다. 지면에 구분된 슬롯이 없으면 0으로 설정합니다. format: int32 type: integer score: description: 후보 풀에서 전달된 아이템의 순위 산정 관련성 점수입니다. format: double type: - number - 'null' required: - catalog_id - position type: object RecommendationErrorDetails: properties: message: type: string required: - message type: object Geo: properties: accuracy: format: int32 type: - integer - 'null' city: type: - string - 'null' country: type: - string - 'null' ext: true ipservice: anyOf: - $ref: '#/components/schemas/IpLocationService' - type: 'null' lastfix: format: uint32 minimum: 0 type: - integer - 'null' lat: format: float type: - number - 'null' lon: format: float type: - number - 'null' metro: type: - string - 'null' region: type: - string - 'null' regionfips104: type: - string - 'null' type: anyOf: - $ref: '#/components/schemas/LocationType' - type: 'null' utcoffset: format: int32 type: - integer - 'null' zip: type: - string - 'null' type: object Gender: enum: - M - F - O type: string AdLogTrackingMode: description: >- 노출 로그 추적 모드입니다. - `on_ad_response`: A2 서버가 광고 응답을 반환할 때 노출을 기록합니다. - `on_event_tracker`: 지원되는 소재의 응답에 노출 트래커 URL이 포함됩니다. 클라이언트가 광고가 표시될 때 URL을 호출하면 A2가 요청을 받아 노출을 기록합니다. 같은 `imp`를 Log API에 중복 제출하지 마세요. enum: - on_ad_response - on_event_tracker type: string IpLocationService: enum: - 1 - 2 - 3 - 4 type: integer LocationType: enum: - 1 - 2 - 3 type: integer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.