추천 요청

추천 API는 광고 단위에 설정된 추천 정책으로 상품 목록을 반환합니다. 이 페이지에서는 추천을 요청하고, 응답의 상품을 표시하고, 빈 결과와 요청 실패에 대비하는 방법을 다룹니다.

시작하기 전에

API 주소: API 주소를 확인합니다. 추천 요청에는 액세스 토큰이 필요 없습니다.
광고 단위: 추천이 활성화된 광고 단위의 ID를 A2 담당자에게 받습니다. 추천 정책, 추천 개수, 노출 추적 방식은 A2 담당자가 광고 단위에 설정합니다.
카탈로그: 추천할 상품을 상품 카탈로그에 등록합니다. 응답의 catalog_id는 카탈로그의 상품 ID입니다.

추천 요청 구성

추천 목록이 필요한 시점에 클라이언트(웹 또는 앱)나 서버에서 POST /app/v0/recommendation/{tagid}를 호출합니다. tagid에는 광고 단위 ID를 넣습니다. 사용 가능한 필드는 API Reference의 추천 제공을 참고하세요.

curl -i -X POST "<A2_API_URL>/app/v0/recommendation/<광고 단위 ID>" \
  -H "Content-Type: application/json" \
  -d '{"user": {"id": "user-123"}}'

필드	사용 기준
`user.id`	사용자 식별자입니다. 같은 사용자에게는 항상 같은 값을 보냅니다. 이 값이 없으면 추천 실험에 사용자를 배정할 수 없고, 추천 정책에 사용자 이력 조건(이미 본 상품 제외 등)이 있어도 적용되지 않습니다.
`seed_item_id`	기준 상품의 카탈로그 ID입니다. 상품 상세의 연관 상품처럼 특정 상품을 기준으로 추천하는 정책에서 사용합니다.
`filter`	추천에서 제외할 조건입니다. 사용할 수 있는 조건은 카탈로그에 따라 다르므로 A2 담당자와 확인하세요. 배열마다 값은 최대 100개입니다.

추천 개수는 요청이 아니라 광고 단위의 설정으로 정해집니다.

호출 위치	응답을 받은 뒤 처리할 내용
클라이언트	응답의 상품으로 목록을 표시하고, `tracking_token`과 상품별 `position`으로 추천 이벤트를 보냅니다.
서버	응답을 클라이언트에 전달합니다. 상품마다 `catalog_id`와 `position`을, 목록마다 `tracking_token`을 함께 전달하세요. 운영 규칙으로 일부 상품을 빼거나 순서를 바꾸더라도 `position`은 화면 순번이 아니라 원래 응답의 값을 유지해야 합니다.

응답 처리

추천 응답 예시

{
  "version": "0.1.0",
  "items": [
    { "catalog_id": "catalog-123", "position": 0, "score": 0.87 },
    { "catalog_id": "catalog-234", "position": 1 }
  ],
  "tracking_token": "<tracking_token>",
  "ext": { "ad_log_tracking_mode": "on_event_tracker" }
}

필드	설명
`items[].catalog_id`	추천 상품의 카탈로그 ID입니다. 상품명·이미지 등 표시할 정보는 서비스의 상품 데이터에서 찾습니다.
`items[].position`	0부터 시작하는 추천 순서입니다. 추천 이벤트의 `event_position`에 그대로 넣습니다.
`items[].score`	추천 점수입니다. 추천 방식에 따라 없을 수 있습니다.
`tracking_token`	이 추천 결과의 추적 토큰입니다. 추천 이벤트에 그대로 넣습니다.
`ext.ad_log_tracking_mode`	노출 추적 방식입니다. 추천 이벤트 추적을 참고하세요.

응답은 다음과 같이 구분해 처리합니다.

응답	처리
HTTP `200`, `items` 있음	상품을 표시하고 `tracking_token`을 보관합니다.
HTTP `200`, `items` 비어 있음	추천 영역을 숨기거나 서비스의 기본 목록을 표시합니다. 보낼 추천 이벤트가 없습니다.
오류 상태·통신 실패	서비스의 기본 목록을 표시합니다. 응답에 `tracking_token`이 없습니다.

요청 실패

서비스에서 추천을 기다릴 최대 시간을 정해 두고, 그 시간이 지나거나 요청이 실패하면 서비스의 기본 목록으로 대체하세요. 그 뒤에 도착한 응답은 표시하지 않습니다. A2는 기본 설정에서 1초 안에 처리하지 못한 요청에 HTTP 408을 반환합니다. 오류 응답에는 errorcode와 ext.message가 들어 있습니다.

HTTP 상태	`errorcode`	원인	확인할 내용
`408`	없음	A2가 기본 설정에서 1초 안에 추천을 처리하지 못했습니다.	서비스의 기본 목록으로 대체합니다. 반복되면 발생 시각과 광고 단위 ID를 A2 담당자에게 전달합니다.
`400`	`1300`	`tagid`가 UUID 형식이 아닙니다.	요청 경로의 광고 단위 ID를 확인합니다.
`400`	`1304`	`filter`의 배열에 값이 100개를 넘습니다.	제외 조건의 값 개수를 줄입니다.
`404`	`1301`	광고 단위를 찾을 수 없습니다.	광고 단위 ID와 A2 환경이 맞는지 확인합니다.
`422`	`1302`	광고 단위에 추천이 활성화되지 않았습니다.	A2 담당자에게 추천 설정을 요청합니다.
`422`	`1303`	광고 단위에 적용할 추천 정책이 없습니다.	A2 담당자에게 추천 정책 설정을 확인합니다.

오류 응답 예시

{
  "version": "0.1.0",
  "errorcode": "1302",
  "items": [],
  "ext": { "message": "Recommendation not enabled." }
}

다시 요청하면 추천 결과와 tracking_token이 달라질 수 있습니다. 이벤트에는 실제로 표시한 응답의 값을 사용하세요. 노출 추적 방식이 추천 응답 기준(on_ad_response)이면 표시하지 않은 응답도 응답 수로 집계됩니다.

다음 단계

추천 이벤트 추적에서 표시한 추천의 노출·클릭·전환을 보내는 방법을 확인합니다.

시작하기

광고 연동

추천 연동

데이터 연동

검증과 실험

시작하기 전에

추천 요청 구성

응답 처리

요청 실패

다음 단계

​시작하기 전에

​추천 요청 구성

​응답 처리

​요청 실패

​다음 단계

시작하기 전에

추천 요청 구성

응답 처리

요청 실패

다음 단계