Getting Started

This guide shows you how to quickly and easily run A2 in your local environment.

NOTE
For a deeper understanding of the A2 architecture, check out A2 Architecture Overview
If you're planning to use A2 in a production environment, refer to A2 Development

Requirements

Platform
- Linux Architecture: x86_64
- MacOS Architecture: x86_64
- (AMD64 support coming soon)
Docker Engine and Docker Compose

Getting Starated

1. Create docker-compose.yml

---
services:
  a2:
    image: "[TO_BE_ANNOUNCED]"
    ports:
      - 3001:3001 # A2 Supply-side Platform API
      - 8000:8000 # A2 Campaign Management System Web
      - 30000:30001 # A2 Event and Log Entrypoint API

2. Run the Container

$> docker-compose up -d

You're now ready to use A2.

Using A2-CMS(Campaign Management System)

1. How to access

To access A2-CMS (Campaign Management System):

**Open your browser and go to http://localhost:8000
Log in
- The default admin account credentials are a2@aiderx.io/password.
- A2-CMS accounts are categorized as either retailer or seller based on roles and permissions.
- For convenience, we'll use the default admin account in this guide.

Note:
For initial ID setup, refer to A2 Development
For details on account roles and permissions, see A2 Development

2. Create a site

After logging in to A2-CMS with a retailer account, create a site where ads can be served:

3. Create a placement

Create an ad placement as follows:

4. Create a creative

5. Create a campaign

Next, register an ad campaign using the creative you've just created, and link the creative to it:

You've now completed the ad serving setup.

Requesting Ads from A2-SSP (Supply-Side Platform)

You can now request ad creatives from the A2-SSP Endpoint (http://localhost:3001) and receive results.

1. Send a request

$> curl -X GET \
   -H "Content-type: Application/json" \
   http://localhost:3001/v0/ad/{placement_uuid} \
   -d '{
         "version": "0.1.0",
         "device": {
             "ua": (
                 "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) "
                 "AppleWebKit/537.13 (KHTML, like Gecko) Versi on/5.1.7 Safari/534.57.2"
             )
         },
         "user": {"id": "test_user_id"},
       }'

2. Check the response

If you see output like this, it's working correctly:

{
  "ad": {
    "display": {
      "h": 250,
      "w": 300
    },
    "id": "{YOUR_CREATIVE_ID}"
  },
  "ext": {
    "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm",
    "message": "success"
  },
  "version": "0.1.0"
}

‍

For detailed API specifications, refer to A2 API Specification

Sending Adlogs to A2-Event API

Let's learn how to send user-related logs using the A2 Event API.

The API endpoint is http://localhost:30001.

1. sending ad logs

An ad log is an event that occurs after showing an ad to a user. You need to include the ad_log from the A2-SSP response.
A2 uses the ad_log to distinguish ad-related information

$> curl -X POST \
   -H "Content-type: Application/json" \
   http://localhost:30001 \
   -d '{
         "type": "ad_log",
         "action": "conv",
         "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm",
       }'

2. sending action logs

An action log records various user behaviors such as clicks, impressions, views, purchases, cart additions, searches, etc.

$> curl -X POST \
   -H "Content-type: Application/json" \
   http://localhost:30001 \
   -d '{
         "type": "action_log",
         "action": "purchase",
         "user_id": "test_user_u0",
         "item_id": "test_item_i1",
       }'

‍