Ad Serving (Advanced)

If you’ve requested an ad and inspected the response in the Ad Serving Quickstart, this page covers what you need to apply ads in your service: building requests with user and page information and custom targeting, handling no-ad and failure cases, and rendering each creative type.

Configure ad requests

Call POST /app/v0/ad/{tagid} from the client (web or app) or a server when an ad is needed. Use the ad unit ID as tagid. If there are no additional conditions, send an empty JSON object {}. For the available fields and response structure, see Serving an ad in the API Reference.

Call location	What to do with the response
Client	Render the ad from the creative in the response. When the user clicks the ad, open the landing page and handle the required events.
Server	Pass the ad response to the client. If you rebuild the response, include the creative data, the ad tracking identifier, and any impression tracking URL your settings add, and let the client tell no-ad and request failures apart.

Add request information

After confirming that the minimum request renders an ad, add the information needed for ad selection. Adding fields one at a time and checking the response makes it easier to see which condition stops an ad from being returned.

Field	When to use it
`user.id`	The user identifier. Always send the same value for the same user so that frequency caps and A/B experiment user assignment are consistent.
`device`	Device information. When a server sends the request, include the actual user’s IP address and User-Agent.
`site` or `app`	Web page or app information.
`ad_size`	The list of creative sizes to request. Only creatives with a matching size are selected.
`targeting`	Keys and values for custom targeting. See the example below.

curl -X POST "<A2_API_URL>/app/v0/ad/<tagid>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {"id": "example-user-001"},
    "app": {"bundle": "com.example.customerapp"}
  }'

curl -X POST "<A2_API_URL>/app/v0/ad/<tagid>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {"id": "example-user-001"},
    "site": {
      "domain": "shop.example.com",
      "page": "https://shop.example.com/products/1234"
    }
  }'

Custom targeting example

If a line item has custom targeting, its ad is selected only when the request’s targeting matches the conditions. For example, if you register the targeting key gender with the value code male in General > Custom Targeting > Key-Values in Ad Manager and set gender to Include male in the line item’s Custom targeting, send the request as follows.

curl -X POST "<A2_API_URL>/app/v0/ad/<tagid>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {"id": "example-user-001"},
    "targeting": {"gender": "male"}
  }'

Use the targeting key and value code, not the display names, and match the case exactly. With multiple conditions, all of them must be met; within one condition, any one of its values is enough. Send values as strings, even numbers, such as "age": "30".

Handle the response

Handle ad responses as one of the following four cases.

Response	Handling
HTTP `200` with `ad`	Render the ad by creative type and keep `ext.ad_log`.
HTTP `200` with `ext.passback`	Process the fallback ad tag configured for the ad unit.
HTTP `204`	Hide the ad area or show default content.
Error status or network failure	End ad loading and keep the existing content.

No ad

HTTP 204 is a successful response meaning no ad was selected. It has no body, so don’t parse it as JSON. If you expected an ad but received 204, check the settings below. For an example of configuring an AdUnit, creative, and allocation from the beginning, see Ad Serving Quickstart.

Settings to check when no ad is served

Item	What to check
Line item	Its status is Delivering, and the current time falls within its flight dates and schedule.
Allocation	The allocation that links the line item to the ad unit, a parent ad unit, or a placement is Published.
Creative association	The association between the line item and creative is active and within its configured dates.
Creative	The creative is active and the current time falls within its configured dates. If the request includes `ad_size`, the creative size must match.
Native style	If the ad unit’s Render Mode is HTML (styled markup), a native style for the creative’s native format must be linked to the ad unit. If no style is linked or the style can’t be applied, A2 returns `204` without a passback.
Request conditions	If the line item has custom targeting, the request’s `targeting` must match it. The user in the request must also satisfy any frequency cap.

These are the basic checks. Whether an ad is finally served also depends on the ad selection logic and other operating conditions. For placement and allocation settings, see Create and Manage Placements, Request an Allocation, and Review Allocations.

Passback is an optional feature that fills the ad area with an external ad tag configured for the ad unit when A2 has no ad. If a tag is configured, the API returns HTTP 200 with ext.passback instead of 204, and the response has no ad or ext.ad_log. Process it only where HTML tags can run, such as the web; in an app, handle it like no ad.

Response (excerpt)

{
  "errorcode": "204",
  "ext": {
    "passback": "<configured fallback ad tag>"
  }
}

Request failures

Decide how long your service waits for an ad, and end ad loading when that time passes or the request fails. Don’t render a response that arrives afterward. With the default settings, A2 returns HTTP 408 for a request it can’t process within 1 second. When you request again, keep in mind that another impression may be recorded. A2 selects an ad anew for each request and, with On Ad Response, records an impression when it returns an ad. A request the client stopped waiting for may already have recorded an impression. For a 4xx response, check the request path, headers, and body. If errors recur, record the time, ad unit ID, HTTP status, and the x-request-id header if the response includes it. See Verification and Troubleshooting for status-specific checks, including cases where an invalid ad unit ID returns 500.

Render the ad

How you render the ad depends on the creative field in the response. A response can contain more than one of these fields, so check them in the order shown in the table.

Order	Creative field	Creative	How to render it
1	`ad.display.adm`	HTML markup (native HTML mode, external ad network ads)	Render it in an iframe separated from your page. The markup includes its own click handling, so don’t add another link around it.
2	`ad.display.banner`	Image banner	Show the image and open the landing URL on click. See Web Integration Tutorial for a runnable example.
3	`ad.display.native`	Native	Connect the title, image, and text to UI components. See the example below.

A native HTML mode response contains ad.display.native along with ad.display.adm, but it holds only impression tracking information, without assets. If you branch on ad.display.native alone, you’ll try to render an HTML mode response with UI components and fail, so check ad.display.adm first. Rendering HTML in an iframe alone does not automatically record an A2 click. Notify the parent document of clicks inside the iframe and send clk with that ad response’s ext.ad_log. See Ad Event Tracking for the event body and delivery instructions.

Connect a native response to your UI

Map each item in a native response’s assets to a UI component by the native format field identifier in ext.field_name. Replace title, main_image, and cta in the example with the identifiers of the native format used for the creative. This applies to native creatives made in A2. Native ads from external ad networks don’t include ext.field_name.

Response (excerpt)

{
  "ad": {
    "display": {
      "native": {
        "ver": "1.2",
        "assets": [
          { "id": 1, "title": { "text": "Up to 30% off new fall arrivals" }, "ext": { "field_name": "title" } },
          { "id": 2, "img": { "url": "https://cdn.example.com/native.jpg" }, "ext": { "field_name": "main_image" } },
          { "id": 3, "data": { "value": "Shop now" }, "ext": { "field_name": "cta" } }
        ],
        "link": { "url": "https://shop.example.com/products/1234" }
      }
    },
    "ext": { "native": { "render_mode": "asset" } }
  },
  "ext": { "message": "success", "ad_log": "<ad tracking identifier returned by A2>" }
}

const native = response.ad.display.native;
const fields = Object.fromEntries(
  (native.assets ?? []).map((asset) => [asset.ext?.field_name, asset])
);
const title = fields.title?.title?.text;
const imageUrl = fields.main_image?.img?.url;
const callToAction = fields.cta?.data?.value;
const landingUrl = native.link?.url;

Getting Started

Ad Integration

Recommendation Integration

Data Integration

Verification and Experiments