A-Sense 연동 가이드

A-Sense API는 챗봇 및 대화형 AI 서비스에 최적화된 문맥 광고를 제공합니다. 단 한 번의 API 호출로 사용자 대화 맥락에 맞는 광고를 추천받고 수익을 창출할 수 있습니다.

인증 (Authentication)

모든 API 요청은 헤더에 x-api-key를 포함해야 합니다. API Key는 파트너 센터에서 발급받을 수 있습니다.

headers = {
    "x-api-key": "sk_live_..."
}

광고 요청 (Ad Request)

가장 적합한 광고를 가져오기 위해 POST /api/v1/get-ad 엔드포인트를 호출합니다.

Endpoint

POST https://a-sense-project.vercel.app/api/v1/get-ad

Parameters (Body)

필드명	타입	필수 여부	설명
`keywords`	List[str]	Yes	사용자 대화에서 추출한 키워드 목록 (예: ["운동화", "나이키"])
`platform`	string	No	플랫폼 식별자 (기본값: "chatbot")
`lang`	string	No	언어 설정 (기본값: "en", 한국어: "ko")

Request Example (Python)

import requests

url = "https://a-sense-project.vercel.app/api/v1/get-ad"
headers = {
    "x-api-key": "sk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "keywords": ["여행", "제주도", "호텔"],
    "lang": "ko",
    "platform": "chatbot"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

응답 처리 (Response Handling)

성공적인 요청 시, 다음과 같은 JSON 응답을 받습니다.

{
    "id": "ad_12345",
    "brand": "제주 신라호텔",
    "ad_copy": "제주도 호캉스의 정석, 지금 예약 시 20% 할인!",
    "link": "https://a-sense-project.vercel.app/api/v1/click/ad_12345?pub_id=...",
    "cpc": 500
}

Fields

id: 광고 고유 ID
brand: 광고주 브랜드명 (챗봇 답변에 활용 가능)
ad_copy: 광고 문구 (챗봇이 사용자에게 전달할 메시지)
link: 트래킹 링크 (사용자가 클릭해야 할 URL)
cpc: 클릭당 예상 수익 (KRW)

클릭 트래킹 (Click Tracking)

수익을 인정받기 위해서는 반드시 응답에 포함된 link 필드의 URL을 사용자에게 제공해야 합니다. 사용자가 이 링크를 클릭하면 A-Sense 서버를 거쳐 광고주 페이지로 이동하며, 이때 클릭이 집계되어 수익이 발생합니다.

중요: 챗봇 답변 생성 시, ad_copy와 함께 link를 마크다운 링크 등으로 자연스럽게 노출해주세요.

# 챗봇 답변 예시 (Markdown)
[제주 신라호텔] 제주도 호캉스의 정석, 지금 예약 시 20% 할인!
[자세히 보기](https://a-sense-project.vercel.app/api/v1/click/...)

에러 코드 (Error Codes)

Status Code	설명	대처 방법
`200 OK`	요청 성공	정상 처리
`401 Unauthorized`	인증 실패	API Key가 올바른지, `x-api-key` 헤더에 포함되었는지 확인하세요.
`500 Internal Error`	서버 내부 오류	잠시 후 다시 시도하거나 고객센터에 문의하세요.

자주 묻는 질문 (FAQ)

Q. 광고가 반환되지 않을 때는 어떻게 하나요?

A. 현재 키워드와 매칭되는 광고가 없거나, 광고주의 예산이 소진된 경우 {"message": "No ads available"}가 반환될 수 있습니다. 이 경우 광고를 표시하지 않거나 자체 콘텐츠로 대체하시면 됩니다.

Q. 테스트 환경에서 클릭해도 수익이 잡히나요?

A. 테스트 API Key를 사용하거나 동일 IP에서 반복 클릭 시 is_valid=False로 처리되어 수익에 반영되지 않습니다. 실제 배포 후에는 정상적으로 집계됩니다.