Developer Quick Start

Goals of this guide

In 10 minutes:

✅ Find your Placement ID
✅ Send your first ad request
✅ Check the ad response

Prerequisites

What you need:

An A2 account (with Developer Portal access)
curl or Postman
A Placement ID for testing

Step 1: Open the Developer Portal (1 min)

Go to the A2 Developer Portal.

https://{customer_id}.a2cloud.aiderx.app/developers/

Select the Developer Portal tab on the login screen. You can sign in with the same account you use for AD Manager.

Step 2: Find your Placement ID (2 min)

In AD Manager, find the Placement ID (tagid) of the Placement where you want to serve ads.

Open AD Manager (https://{customer_id}.a2cloud.aiderx.app - same domain as the Developer Portal)
Click the Placement menu
Copy the ID of the Placement you want to test

The Placement ID is used in the ad request URL. Make sure the Placement is active.

Step 3: Send an ad request (3 min)

Run the following curl command in your terminal.

curl -X POST \
  -H "Content-type: application/json" \
  https://{customer_id}.a2cloud.aiderx.app/app/v0/ad/{tagid} \
  -d '{
    "version": "0.1.0",
    "user": {
      "id": "test_user_123"
    },
    "device": {
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
    }
  }'

Parameters:

{customer_id}: Your customer ID
{tagid}: Placement ID (found in AD Manager)

The ad serving API does not require authentication. The device.ua field is recommended and helps improve Targeting accuracy.

Step 4: Check the response (2 min)

On success, you receive a JSON response like this:

{
  "version": "0.1.0",
  "ad": {
    "id": "ad_123456",
    "display": {
      "w": 300,
      "h": 250,
      "banner": {
        "img": "https://example.com/ad-image.jpg"
      }
    }
  },
  "ext": {
    "message": "success",
    "ad_log": "encrypted_tracking_data..."
  }
}

Response fields:

version: API version (e.g., "0.1.0")
ad.id: Ad ID
ad.display.w, ad.display.h: Ad size
ad.display.banner.img: Banner image URL (or HTML markup may be returned in ad.display.adm)
ext.message: Response status message
ext.ad_log: Encrypted tracking data (handled automatically by the SDK)

Step 5: Integrate the SDK (optional, 2 min)

Installing the SDK on your website makes serving ads easier.

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Where the ad will be displayed -->
  <div id="a2-placement"></div>
  
  <!-- A2 SDK -->
  <script src="https://{customer_id}.a2cloud.aiderx.app/a2-sdk.js"></script>
  <script>
    // Initialize the SDK
    // If port is not specified, the build-time default (VITE_PORT) or 8000 is used
    // You may need to specify port depending on your deployment environment
    let app = new A2_SDK.A2({
      base_url: "https://{customer_id}.a2cloud.aiderx.app"
    });
    
    // Register a user (optional)
    app.register_user({
      id: "user_123",
      yob: 1990,
      gender: "M"  // "M" | "F" | "O"
    });
    
    // Register an ad
    // register_ad(tagid, element, width, height, responsive)
    // responsive: "fixed" (default) | "resized"
    // Note: element must exist (see the SDK guide for null checks)
    let placement = document.getElementById("a2-placement");
    app.register_ad("your-tagid", placement, 300, 250, "fixed");
  </script>
</body>
</html>

Done! 🎉

You’ve successfully sent your first ad request!

Next steps

API Reference

View the full API documentation and detailed parameters

SDK guide

Advanced SDK features and customization

Event log integration

Send impression, click, and conversion events

Campaign management API

Create and manage Campaigns via the API

FAQ

When do I need an API token?

The ad serving API (/app/v0/ad/{tagid}) can be used without authentication. The ad requests covered in this Quick Start do not require a token.API tokens are required only for the Campaign management API (creating, updating, and deleting Campaigns, etc.). If you need a token, you can issue one from the Settings menu in ADM. For details, see the token issuance guide.

What response do I get when there is no ad?

When there is no ad, HTTP status code 204 is returned (the response body is ignored). With the SDK, a 204 is handled as a NoBidError and no ad is displayed. If you set the collapse_nobid: true option when initializing the SDK, the ad area is hidden automatically. If you call the API directly, handle no-bid based on the 204 status code (do not rely on the body).

How do I track impressions?

Call the impression_url from the response when the ad is displayed on screen. The SDK handles this automatically.

How do I track clicks?

When a user clicks the ad, redirect to the click_url. A2 tracks the click automatically and then sends the user to the final landing page.

Is there a rate limit?

By default, up to 100 requests per second are allowed. If you need a higher limit, contact support.

Troubleshooting

401 Unauthorized

This error occurs only with the Campaign management API (not the ad serving API)
The ad serving API (/app/v0/ad/{tagid}) does not require authentication - the requests covered in this Quick Start never return 401
When using the Campaign management API: check your token in ADM Settings (token issuance guide)

404 Not Found

Check that the Placement ID is correct
Check that the Placement is active

500 Internal Server Error

Check that the request JSON format is valid
If the problem persists, contact support

Get Started

Core Concepts

Placement Management

Campaign Management

Allocation Management

Analytics & Reports

System Management

Goals of this guide

Prerequisites

Step 1: Open the Developer Portal (1 min)

Step 2: Find your Placement ID (2 min)

Step 3: Send an ad request (3 min)

Step 4: Check the response (2 min)

Step 5: Integrate the SDK (optional, 2 min)

Done! 🎉

Next steps

API Reference

SDK guide

Event log integration

Campaign management API

FAQ

Troubleshooting

401 Unauthorized

404 Not Found

500 Internal Server Error

​Goals of this guide

​Prerequisites

​Step 1: Open the Developer Portal (1 min)

​Step 2: Find your Placement ID (2 min)

​Step 3: Send an ad request (3 min)

​Step 4: Check the response (2 min)

​Step 5: Integrate the SDK (optional, 2 min)

​Done! 🎉

​Next steps

API Reference

SDK guide

Event log integration

Campaign management API

​FAQ

​Troubleshooting

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

Goals of this guide

Prerequisites

Step 1: Open the Developer Portal (1 min)

Step 2: Find your Placement ID (2 min)

Step 3: Send an ad request (3 min)

Step 4: Check the response (2 min)

Step 5: Integrate the SDK (optional, 2 min)

Done! 🎉

Next steps

FAQ

Troubleshooting

401 Unauthorized

404 Not Found

500 Internal Server Error