> ## 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.

# Serving an ad

> ## 광고 요청 / 광고 제공

지면 태그(`tagid`)와 요청 페이로드(`AdRequest`)를 기반으로 광고를 제공합니다. 캠페인, 크리에이티브, 입찰 전략 데이터를 사용하여 가장 적합한 광고를 선택합니다. DSP 응답과 내부 중재 로직을 통해 결정된 최종 광고를 반환합니다.



## OpenAPI

````yaml /openapi/decision.api.ko-0.2.2.json post /app/v0/ad/{tagid}
openapi: 3.1.0
info:
  contact:
    email: a2support@aiderx.io
    name: A2 Support
    url: https://aiderx.io
  description: |-
    ### 소개
    이 문서는 Decision API의 Ad Serving API 및 Recommendation API 구성 요소를 다룹니다.
  title: Decision APIs
  version: v0.2.2
  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


      ### **중요**

      Serving 서버의 광고 또는 추천 관련 캐시 데이터를 직접 조작하는 경우, Ad Manager를 통해 광고 또는 추천 데이터를
      **동시에 수정하지 않을 것을 강력히 권장합니다.**

      Serving 서버에서 수행된 변경 사항은 Ad Manager에 반영되지 않으며,

      이는 **데이터 무결성**을 위협할 수 있습니다.
    name: Cache Management
  - description: 광고 서빙 서버 설정 API
    name: Configuration
  - description: |
      광고 전환, 노출, 클릭 로그를 수신하는 API — 광고 성능 추적 및 최적화에 필수적입니다.
    name: Ad Serving
paths:
  /app/v0/ad/{tagid}:
    post:
      tags:
        - Ad Serving
      summary: Serving an ad
      description: >-
        ## 광고 요청 / 광고 제공


        지면 태그(`tagid`)와 요청 페이로드(`AdRequest`)를 기반으로 광고를 제공합니다. 캠페인, 크리에이티브, 입찰 전략
        데이터를 사용하여 가장 적합한 광고를 선택합니다. DSP 응답과 내부 중재 로직을 통해 결정된 최종 광고를 반환합니다.
      parameters:
        - description: 지면 ID (tagid)
          in: path
          name: tagid
          required: true
          schema:
            description: 지면 ID (tagid)
            format: uuid
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdRequest'
        description: AdRequest는 광고 요청에 사용됩니다.
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                ad:
                  display:
                    banner:
                      img: https://example.com/image.jpg
                    h: 1024
                    w: 768
                  id: b56dc3bf-935d-4ee6-b1ed-f31bfc02be91
                ext:
                  ad_log: >-
                    YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm
                  message: success
                version: 0.1.0
              schema:
                $ref: '#/components/schemas/AdResponse'
          description: 광고 송출 성공
        '204':
          description: 입찰 없음.
        '404':
          description: 지면을 찾을 수 없습니다.
        '500':
          description: 내부 서버 오류.
      security:
        - '': []
components:
  schemas:
    AdRequest:
      description: AdRequest is used for requesting an ad.
      properties:
        device:
          anyOf:
            - $ref: '#/components/schemas/Device'
            - type: 'null'
          description: 광고 요청에 대한 디바이스 객체.
        user:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: 'null'
          description: 광고 요청에 대한 사용자 객체
        version:
          description: SDK API 버전
          type: string
      required:
        - version
      type: object
    AdResponse:
      properties:
        ad:
          anyOf:
            - $ref: '#/components/schemas/Ad'
            - type: 'null'
          description: 광고 객체
        errorcode:
          description: Error code if the request failed.
          type:
            - string
            - 'null'
        ext:
          description: Optional vendor-specific extensions.
        version:
          description: Version of the SDK API.
          type: string
      required:
        - version
      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 문자열. 이 필드는 브라우저의 원본 UA 문자열을 나타냄. 하위 호환성을 위해
            User-Agent Client-Hints가 사용 가능하더라도 UA 문자열을 항상 포함하는 것을 권장. 추정되거나 근사된
            UA는 허용되지 않음. Client-Hints가 지원되고 'sua' 필드가 있는 경우, 입찰자는 기기 유형, 브라우저 유형
            및 버전 감지를 위해 'sua'를 사용하고 'ua'는 무시하는 것을 권장.
          type:
            - string
            - 'null'
      type: object
    User:
      properties:
        buyeruid:
          description: >-
            Buyer-specific ID for the user as mapped by the exchange for the
            buyer.
          type:
            - string
            - 'null'
        ext:
          description: Placeholder for exchange-specific extensions to OpenRTB.
        gender:
          anyOf:
            - $ref: '#/components/schemas/Gender'
            - type: 'null'
          description: >-
            Gender, where “M” = male, “F” = female, “O” = known to be other
            (i.e., omitted is unknown).
        geo:
          anyOf:
            - $ref: '#/components/schemas/Geo'
            - type: 'null'
          description: >-
            Location of the user’s home base defined by a Geo object (Section
            3.2.19). This is not necessarily their current location.
        id:
          description: Exchange-specific ID for the user.
          type:
            - string
            - 'null'
        keywords:
          description: >-
            Comma separated list of keywords, interests, or intent. Only one of
            ‘keywords’ or ‘kwarray’ may be present.
          type:
            - string
            - 'null'
        yob:
          deprecated: true
          description: Year of birth as a 4-digit integer.
          format: uint16
          minimum: 0
          type:
            - integer
            - 'null'
      type: object
    Ad:
      properties:
        cat:
          description: >-
            광고의 콘텐츠 카테고리를 설명하는 배열. cattax에 지정된 분류법을 사용하여 구현자는 데이터 사용 및 공유에 대한 지역
            법률 준수를 보장해야 합니다.
          items:
            type: string
          type:
            - array
            - 'null'
        cattax:
          anyOf:
            - $ref: '#/components/schemas/CategoryTaxonomy'
            - type: 'null'
          description: 'cat 속성에 사용되는 분류법. 분류법 목록: 카테고리 분류법'
        display:
          anyOf:
            - $ref: '#/components/schemas/Display'
            - type: 'null'
          description: 이 광고는 디스플레이 광고이며 추가 세부 정보를 제공합니다.
        ext:
          description: A2 확장 정보
        id:
          description: >-
            ID of the creative; unique at least throughout the scope of a vendor
            (e.g., an exchange or buying platform). Note that multiple instances
            of the same ad when used in transactions must have the same ID.
          type: string
        iurl:
          description: >-
            캐시 비활성화 없이 광고 콘텐츠를 대표하는 이미지의 URL. 광고 품질 검사를 위한 커서 수준 광고 품질 검사에
            사용됩니다.
          type:
            - string
            - 'null'
        lang:
          description: >-
            ISO-639-1-alpha-2 형식의 광고 크리에이티브 언어. 이 객체를 사용하는 업체는 이 객체를 사용하기 전에 대체
            표준(예: BCP-47)을 선택할 수 있습니다. 광고에 언어 콘텐츠가 없는 경우(예: 회사 로고만 있는 배너) 비표준 코드
            “xx”도 사용할 수 있습니다.
          type:
            - string
            - 'null'
        video:
          anyOf:
            - $ref: '#/components/schemas/Video'
            - type: 'null'
          description: 이 광고는 비디오 광고이며 추가 세부 정보를 제공합니다.
      required:
        - id
      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
    CategoryTaxonomy:
      oneOf:
        - enum:
            - IABTechLabAdProductTaxonomy1_0
            - IABTechLabAudienceTaxonomy1_1
            - IABTechLabContentCategoryTaxonomy2_1
            - IABTechLabContentCategoryTaxonomy2_2
            - IABTechLabContentCategoryTaxonomy3_0
            - IABTechLabAdProductTaxonomy2_0
          type: string
        - deprecated: true
          enum:
            - IABTechLabContentCategoryTaxonomy1_0
          type: string
        - deprecated: true
          enum:
            - IABTechLabContentCategoryTaxonomy2_0
          type: string
        - additionalProperties: false
          properties:
            VendorSpecific:
              format: uint16
              minimum: 0
              type: integer
          required:
            - VendorSpecific
          type: object
    Display:
      properties:
        adm:
          type:
            - string
            - 'null'
        api:
          items:
            $ref: '#/components/schemas/ApiFramework'
          type:
            - array
            - 'null'
        banner:
          anyOf:
            - $ref: '#/components/schemas/Banner'
            - type: 'null'
          description: 배너 소재에 대한 배너 이미지 객체.
        ctype:
          items:
            $ref: '#/components/schemas/CreativeSubtypesDisplay'
          type:
            - array
            - 'null'
        curl:
          type:
            - string
            - 'null'
        event:
          items:
            $ref: '#/components/schemas/Event'
          type:
            - array
            - 'null'
        ext:
          description: A2 확장 정보
        h:
          description: 절대 높이, 픽셀(DIPS) .
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        hratio:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        mime:
          description: '광고의 MIME 유형(예: “image/jpeg”).'
          type:
            - string
            - 'null'
        native:
          anyOf:
            - $ref: '#/components/schemas/Native'
            - type: 'null'
          description: 네이티브 광고에 대한 네이티브 객체.
        priv:
          type:
            - string
            - 'null'
        w:
          description: 절대 너비, 픽셀(DIPS).
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        wratio:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
      type: object
    Video:
      properties:
        adm:
          type:
            - string
            - 'null'
        api:
          items:
            $ref: '#/components/schemas/ApiFramework'
          type:
            - array
            - 'null'
        ctype:
          anyOf:
            - $ref: '#/components/schemas/CreativeSubtypesAudioVideo'
            - type: 'null'
        curl:
          type:
            - string
            - 'null'
        dur:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        ext: true
        mime:
          items:
            type: string
          type:
            - array
            - 'null'
      type: object
    IpLocationService:
      enum:
        - 1
        - 2
        - 3
        - 4
      type: integer
    LocationType:
      enum:
        - 1
        - 2
        - 3
      type: integer
    ApiFramework:
      oneOf:
        - enum:
            - VPAID1_0
            - VPAID2_0
            - MRAID1_0
            - ORMMA
            - MRAID2_0
            - MRAID3_0
            - OMID1_0
            - SIMID1_0
            - SIMID1_1
          type: string
        - additionalProperties: false
          properties:
            VendorSpecific:
              format: uint16
              minimum: 0
              type: integer
          required:
            - VendorSpecific
          type: object
    Banner:
      properties:
        ext: true
        img:
          type: string
        link:
          anyOf:
            - $ref: '#/components/schemas/LinkAsset'
            - type: 'null'
      required:
        - img
      type: object
    CreativeSubtypesDisplay:
      enum:
        - HTML
        - AMPHTML
        - StructuredImageObject
        - StructuredNativeObject
      type: string
    Event:
      properties:
        api:
          items:
            $ref: '#/components/schemas/ApiFramework'
          type:
            - array
            - 'null'
        cdata: true
        ext: true
        method:
          $ref: '#/components/schemas/EventTrackingMethod'
        type:
          $ref: '#/components/schemas/EventType'
        url:
          type: string
      required:
        - method
        - type
        - url
      type: object
    Native:
      properties:
        asset:
          items:
            $ref: '#/components/schemas/Asset'
          type:
            - array
            - 'null'
        ext: true
        link:
          anyOf:
            - $ref: '#/components/schemas/LinkAsset'
            - type: 'null'
      type: object
    CreativeSubtypesAudioVideo:
      oneOf:
        - enum:
            - VAST1_0
            - VAST2_0
            - VAST3_0
            - VAST1_0Wrapper
            - VAST2_0Wrapper
            - VAST3_0Wrapper
            - VAST4_0
            - VAST4_0Wrapper
            - DAAST1_0
            - DAAST1_0Wrapper
            - VAST4_1
            - VAST4_1Wrapper
            - VAST4_2
            - VAST4_2Wrapper
          type: string
        - additionalProperties: false
          properties:
            VendorSpecific:
              format: uint16
              minimum: 0
              type: integer
          required:
            - VendorSpecific
          type: object
    LinkAsset:
      description: >-
        This object identifies the native asset as a link asset and is used to
        define navigation for call-to-action or other activations (i.e.,
        clicks). A link asset can be independent or associated with the overall
        native ad (i.e., a default for all assets).
      properties:
        ext: true
        trkr:
          items:
            type: string
          type:
            - array
            - 'null'
        url:
          type: string
        urlfb:
          type:
            - string
            - 'null'
      required:
        - url
      type: object
    EventTrackingMethod:
      enum:
        - 1
        - 2
      type: integer
    EventType:
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      type: integer
    Asset:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/DataAsset'
            - type: 'null'
        ext: true
        id:
          format: int32
          type:
            - integer
            - 'null'
        image:
          anyOf:
            - $ref: '#/components/schemas/ImageAsset'
            - type: 'null'
        link:
          anyOf:
            - $ref: '#/components/schemas/LinkAsset'
            - type: 'null'
        req:
          anyOf:
            - $ref: '#/components/schemas/IsRequired'
            - type: 'null'
        title:
          anyOf:
            - $ref: '#/components/schemas/TitleAsset'
            - type: 'null'
        video:
          anyOf:
            - $ref: '#/components/schemas/VideoAsset'
            - type: 'null'
      type: object
    DataAsset:
      description: >-
        This object identifies the native asset as a data asset. A data asset is
        used for all miscellaneous elements such as brand name, ratings, stars,
        review count, downloads, price, counts, etc. It is purposefully generic
        to support native elements not currently contemplated by this
        specification.
      properties:
        ext: true
        len:
          format: int32
          type:
            - integer
            - 'null'
        type:
          anyOf:
            - $ref: '#/components/schemas/NativeDataAssetType'
            - type: 'null'
        value:
          type: string
      required:
        - value
      type: object
    ImageAsset:
      description: >-
        This object identifies the native asset as a image asset. Image assets
        are use for such elements as the actual creative images and icons.
      properties:
        ext: true
        h:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        type:
          anyOf:
            - $ref: '#/components/schemas/NativeImageAssetType'
            - type: 'null'
        url:
          type: string
        w:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
      required:
        - url
      type: object
    IsRequired:
      enum:
        - 0
        - 1
      type: integer
    TitleAsset:
      description: >-
        This object identifies the native asset as a title asset, which is
        essentially just a plain text string with specified length.
      properties:
        ext: true
        len:
          format: uint32
          minimum: 0
          type:
            - integer
            - 'null'
        text:
          type: string
      required:
        - text
      type: object
    VideoAsset:
      description: >-
        This object identifies the native asset as a video asset. Video markup
        (e.g., VAST) must be either included or referenced.
      properties:
        adm:
          type:
            - string
            - 'null'
        curl:
          type:
            - string
            - 'null'
        ext: true
      type: object
    NativeDataAssetType:
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
        - 11
        - 12
      type: integer
    NativeImageAssetType:
      enum:
        - 1
        - 2
        - 3
      type: integer

````