Quick Start

Run a web example that requests an image banner, renders it, and records a click. You will follow the ad tracking identifier from the ad response through event delivery, then confirm the click count in Ad Manager. In this exercise, you click the banner to confirm that its landing page opens, then send one click event from the terminal. See Ad Event and Log Integration to send events automatically when users click on a web page.

Compare direct API integration and the Web SDK

A2 supports direct Decision API calls and Web SDK integration. The direct API path is the default in these documents because it works in app and server environments and gives you control over request and response handling.

Category	Direct API	Web SDK
Environment	Server, web, and app	Web browser
Ad request	Your code controls timing and body	The SDK requests an ad from `register_ad`
Rendering	Your code renders each creative type	The SDK renders image banners and HTML markup creatives in the ad slot and can hide the ad area on no-ad responses when configured
Events	Your code sends the impression tracking, clicks, and conversions your settings require	The SDK sends a click event automatically when an image banner is clicked
Best fit	Apps, server-side requests, custom UI, and detailed error handling	Standard web ad areas using a provided SDK bundle

The Web SDK uses the browser DOM and localStorage, so the same integration does not run in an app or server environment. Available SDK bundles and settings can vary by environment; confirm the bundle and options provided for your A2 environment before implementation. A guide to installing and using the Web SDK is in preparation.

Before you begin

This exercise doesn’t need an access token. Prepare the following before you start.

A2 address: See API Access and Authentication.
Ad unit: The ad unit, the area where the ad appears, must have an allocated ad with an image banner creative that can currently serve. Use a verification ad unit so that you can tell your results apart from other traffic.
Ad settings: The ad must be selectable by an empty {} request with no custom targeting, and the allocation’s Impression Tracking Mode must be On Ad Response (the default).
Ad Manager account: An Admin or Operator account is required to find the ad unit ID and view AdUnit Analytics.
Tools: curl, a text editor, a web browser, and Python 3 to run a local web server

If you don’t have an ad unit ready, ask your ad operations team for one. For setup, see Create and Manage Placements, Allocation Request, and Allocation Review. When the ad unit is ready, find the ID to use in requests.

Select the ad unit

In Ad Manager, go to Inventory > Ad Units and select the ad unit to use.

Open Settings

Select the Settings tab on the ad unit detail page.

Copy the ad unit ID

Copy the ID shown under Basic Information.

With On Ad Response, A2 records an impression when it selects an ad and builds the response, so the example doesn’t send a separate impression event. See Ad Event and Log Integration for other tracking modes. Before you start, go to Analytics > Inventory Analytics > AdUnit Analytics in Ad Manager and note today’s click count for the selected ad unit. Replace these two values in the examples.

Example value	Replace with
`https://your_a2_service`	Your A2 address
`<tagid>`	The ad unit ID you copied

Request and render an ad

Request an ad

Send an empty JSON object as the ad request.

curl -X POST "https://your_a2_service/app/v0/ad/<tagid>" \
  -H "Content-Type: application/json" \
  -d '{}'

When A2 selects an ad, it returns HTTP 200 with the ad response. For an image banner, find the image and landing URL in ad.display.banner, and the ad tracking identifier for events in the top-level ext.ad_log.

Response (excerpt)

{
  "ad": {
    "id": "7c4f2b18-e9a6-4d3f-b821-56a09c73e4fd",
    "display": {
      "w": 300,
      "h": 250,
      "banner": {
        "img": "https://cdn.example.com/banner.jpg",
        "link": {
          "url": "https://shop.example.com/products/1234"
        }
      }
    }
  },
  "ext": {
    "message": "success",
    "ad_log": "<ad tracking identifier returned by A2>"
  }
}

HTTP 204 is a successful response that means no ad was available. Do not parse the response body as JSON; check the ad configuration. The example below sends a new ad request. It may return a different ad from the earlier curl request, so use the ad_log of the ad shown on the web page for the click event. Save the following as quick-start.html and replace baseUrl and tagid.

<!doctype html>
<html lang="en">
  <body>
    <div id="ad-slot">Requesting an ad</div>
    <p>ad_log: <code id="ad-log">Not yet available</code></p>

    <script>
      const baseUrl = "https://your_a2_service";
      const tagid = "<tagid>";
      const slot = document.querySelector("#ad-slot");
      const adLogView = document.querySelector("#ad-log");

      function showMessage(message) {
        slot.textContent = message;
        adLogView.textContent = "None";
      }

      async function loadAd() {
        const result = await fetch(`${baseUrl}/app/v0/ad/${tagid}`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: "{}",
        });

        if (result.status === 204) {
          showMessage("No ad was returned.");
          return;
        }
        if (!result.ok) throw new Error(`Ad request failed: ${result.status}`);

        const response = await result.json();
        const display = response.ad?.display;
        const banner = display?.banner;
        const adLog = response.ext?.ad_log;
        if (!banner?.img) throw new Error("The response is not an image banner.");
        if (!banner.link?.url) throw new Error("The landing URL is missing.");
        if (!adLog) throw new Error("ad_log is missing.");

        const image = document.createElement("img");
        image.onload = () => {
          adLogView.textContent = adLog;
        };
        image.onerror = () => showMessage("The image failed to load.");
        image.src = banner.img;
        image.alt = "Advertisement";
        if (display.w) image.width = display.w;
        if (display.h) image.height = display.h;

        const link = document.createElement("a");
        link.href = banner.link.url;
        link.target = "_blank";
        link.rel = "noopener";
        link.append(image);
        slot.replaceChildren(link);
      }

      loadAd().catch((error) => showMessage(error.message));
    </script>
  </body>
</html>

Run a local web server in the directory where you saved the file, then open http://localhost:8000/quick-start.html in a web browser.

python3 -m http.server 8000

If the curl request succeeds but the page shows a request failure message, see When requests fail only in the browser. ad_log appears only when the banner image is displayed. If no ad is returned or the request or image load fails, check the message in the ad area and don’t continue to the click event step. When the image appears, click the banner once, confirm that the landing page opens, and copy the displayed ad_log.

Send a click event

Replace <ad_log> with the ad_log you copied from the web page and send the click event once.

curl -i -X POST "https://your_a2_service/dmp/v0/log" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ad_log",
    "action": "clk",
    "ad_log": "<ad_log>"
  }'

After receiving HTTP 200, verify actual collection in the next section.

Verify the result

In Ad Manager, go to Analytics > Inventory Analytics > AdUnit Analytics, select the ad unit you used, and set the date range to today. Confirm that the click count is one higher than the value you noted before the exercise. An impression is recorded for each curl or web page ad request that returned an ad, so the impression count can increase by that number. Requests that receive a no-ad response (HTTP 204) aren’t recorded as impressions. With the default settings, click events are usually reflected within a minute. After about a minute, reload the page in your browser to check, and don’t resend the click event to check. If the count still hasn’t changed after reloading, see When an event request succeeds but reporting doesn’t reflect it.

Check	Completion criterion
Ad request	The HTTP `200` response contains `ad` and `ext.ad_log`
Ad rendering	The image banner appears and opens its landing page when clicked
Event request	The click event request returns HTTP `200`
Event collection	The ad unit’s click count is one higher than before the exercise

Next steps

Expand the service implementation

Use Ad Serving Integration and Ad Event and Log Integration to implement creative rendering and impression, click, and conversion handling.

Verify completion

Use the checklist in Integration Verification and Troubleshooting to verify API responses and analytics updates.

When using an authenticated API, see API Access and Authentication first for token issuance and storage.

Getting Started

Integration Guides

Before you begin

Request and render an ad

Request an ad

Render the image banner

Send a click event

Verify the result

Next steps

​Before you begin

​Request and render an ad

​Request an ad

​Render the image banner

​Send a click event

​Verify the result

​Next steps

Before you begin

Request and render an ad

Request an ad

Render the image banner

Send a click event

Verify the result

Next steps