Ad Serving

Serving an ad

Serves an ad based on the placement tag (tagid) and request payload (AdRequest). Selects the most appropriate ad using campaign, creative, and bidding strategy data. Returns the final ad determined through DSP response and internal mediation logic.

curl --request POST \
  --url https://your_a2_service/app/v0/ad/{tagid} \
  --header 'Content-Type: application/json' \
  --data '{
  "user": {
    "gender": "M",
    "id": "account-187acvbvz",
    "yob": 1988
  },
  "version": "0.1.0"
}'

POST

app

{tagid}

curl --request POST \
  --url https://your_a2_service/app/v0/ad/{tagid} \
  --header 'Content-Type: application/json' \
  --data '{
  "device": {
    "ext": "<any>",
    "geo": {
      "accuracy": 123,
      "city": "<string>",
      "country": "<string>",
      "ext": "<any>",
      "ipservice": 1,
      "lastfix": 1,
      "lat": 123,
      "lon": 123,
      "metro": "<string>",
      "region": "<string>",
      "regionfips104": "<string>",
      "type": 1,
      "utcoffset": 123,
      "zip": "<string>"
    },
    "ip": "<string>",
    "ua": "<string>"
  },
  "user": {
    "buyeruid": "<string>",
    "ext": "<any>",
    "gender": "M",
    "geo": {
      "accuracy": 123,
      "city": "<string>",
      "country": "<string>",
      "ext": "<any>",
      "ipservice": 1,
      "lastfix": 1,
      "lat": 123,
      "lon": 123,
      "metro": "<string>",
      "region": "<string>",
      "regionfips104": "<string>",
      "type": 1,
      "utcoffset": 123,
      "zip": "<string>"
    },
    "id": "<string>",
    "keywords": "<string>",
    "yob": 1
  },
  "version": "<string>"
}'

{
  "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"
}

Path Parameters

tagid

string

required

The ID of the placement.

Get from the advertising manager.

Body

application/json

AdRequest is used for requesting an ad.

version

string

required

Version of the SDK API.

device

object | null

Device object for the current ad request.

user

object | null

User object for the current ad request.

Response

200

application/json

Successfully served an ad

version

string

required

Version of the SDK API.

object | null

Ad object.

ad.id

string

required

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.

ad.cat

string[] | null

Array of content categories describing the ad using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing.

ad.cattax

The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies.

Available options:

IABTechLabAdProductTaxonomy1_0,

IABTechLabAudienceTaxonomy1_1,

IABTechLabContentCategoryTaxonomy2_1,

IABTechLabContentCategoryTaxonomy2_2,

IABTechLabContentCategoryTaxonomy3_0,

IABTechLabAdProductTaxonomy2_0

ad.display

object | null

Creative Subtype Object that indicates this is a display ad and provides additional detail as such.

ad.ext

any

Optional A2 specific extensions.

ad.iurl

string | null

URL without cache-busting to an image that is representative of the ad content for cursory level ad quality checking.

ad.lang

string | null

Language of the creative using ISO-639-1-alpha-2. In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated beforehand. The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).

ad.video

null

Creative Subtype Object that indicates this is a video ad and provides additional detail as such.

errorcode

string | null

Error code if the request failed.

ext

any

Optional A2 specific extensions.

Was this page helpful?

/app/v0/logRecords ad interaction events for advertising optimization and analytics. Supported event types: - Impressions (imp): Records ad view events - Clicks (clk): Records ad click events - Conversions (conv): Records post-view conversion events including purchases, installations, and subscriptions Note: Returns 200 OK for all requests. Invalid schemas are silently ignored.

curl --request POST \
  --url https://your_a2_service/app/v0/ad/{tagid} \
  --header 'Content-Type: application/json' \
  --data '{
  "device": {
    "ext": "<any>",
    "geo": {
      "accuracy": 123,
      "city": "<string>",
      "country": "<string>",
      "ext": "<any>",
      "ipservice": 1,
      "lastfix": 1,
      "lat": 123,
      "lon": 123,
      "metro": "<string>",
      "region": "<string>",
      "regionfips104": "<string>",
      "type": 1,
      "utcoffset": 123,
      "zip": "<string>"
    },
    "ip": "<string>",
    "ua": "<string>"
  },
  "user": {
    "buyeruid": "<string>",
    "ext": "<any>",
    "gender": "M",
    "geo": {
      "accuracy": 123,
      "city": "<string>",
      "country": "<string>",
      "ext": "<any>",
      "ipservice": 1,
      "lastfix": 1,
      "lat": 123,
      "lon": 123,
      "metro": "<string>",
      "region": "<string>",
      "regionfips104": "<string>",
      "type": 1,
      "utcoffset": 123,
      "zip": "<string>"
    },
    "id": "<string>",
    "keywords": "<string>",
    "yob": 1
  },
  "version": "<string>"
}'

{
  "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"
}

Data Management APIs

Decision APIs

Serving an ad

Path Parameters

Body

Response