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

# Quick Start

> Request and render an image banner, then verify click-event collection.

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](https://docs.aiderx.io/development/en/ad-events-and-logs.md) to send events automatically when users click on a web page.

> [accordion] 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](https://docs.aiderx.io/development/en/api-access-and-auth.md).
* **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](https://docs.aiderx.io/guides/for-retailers/en/placement.md), [Allocation Request](https://docs.aiderx.io/guides/for-advertisers/en/allocation-request.md), and [Allocation Review](https://docs.aiderx.io/guides/for-retailers/en/allocation-review.md).

When the ad unit is ready, find the ID to use in requests.

**1. Select the ad unit**

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

**2. Open Settings**

Select the **Settings** tab on the ad unit detail page.

**3. 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](https://docs.aiderx.io/development/en/ad-events-and-logs.md) 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.

```bash theme={null}
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`.

```json Response (excerpt) theme={null}
{
  "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.

### Render the image banner

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

```html theme={null}
<!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.

```bash theme={null}
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](https://docs.aiderx.io/development/en/integration-verification-and-troubleshooting.md#browser-request-failure).

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

```bash theme={null}
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](https://docs.aiderx.io/development/en/integration-verification-and-troubleshooting.md#event-not-reported).

| 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

**1. Expand the service implementation**

Use [Ad Serving Integration](https://docs.aiderx.io/development/en/serving-ad.md) and [Ad Event and Log Integration](https://docs.aiderx.io/development/en/ad-events-and-logs.md) to implement creative rendering and impression, click, and conversion handling.

**2. Verify completion**

Use the checklist in [Integration Verification and Troubleshooting](https://docs.aiderx.io/development/en/integration-verification-and-troubleshooting.md) to verify API responses and analytics updates.

When using an authenticated API, see [API Access and Authentication](https://docs.aiderx.io/development/en/api-access-and-auth.md) first for token issuance and storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.