# Deploying A2 OnPrem on AWS Source: https://docs.aiderx.io/development/en/deployment-aws This guide explains how to deploy A2 OnPrem on Amazon Web Service (AWS). There are various ways to deploy Docker images on AWS platforms, such as [AWS EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/concepts.html), [AWS App Runner](https://docs.aws.amazon.com/apprunner/latest/dg/what-is-apprunner.html), [AWS Lightsail](https://docs.aws.amazon.com/lightsail/latest/userguide/amazon-lightsail-container-services.html), and [AWS EKS](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html). This article will explain the simplest method, which is deploying on [AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html). ### Registering Docker Image in ECR To use Docker images in AWS, you need to register the image in the Elastic Container Registry (ECR). For detailed instructions on image registration, refer to the [official AWS document](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html), which covers repository creation and Docker image push. Upon completion, you will see a screen like this in your ECR repository: image From now on, use the value in the URI column to deploy the image. ### Setting up AWS ECS #### 1. Creating a Cluster To use AWS Elastic Container Service (ECS), you first need to create a cluster. In the ECS `Clusters` > `Create Cluster` menu, you will see the following screen: image 1. Enter an appropriate name in `Cluster name`. 2. To maintain volume, select Amazon EC2 instances, and it's recommended to choose an instance type of `c5.2xlarge` (8 vCPU, 16GB RAM) or higher. 3. Set the Desired capacity to Minimum: 1, Maximum: 1. 4. Create the cluster. #### 2. Defining a Task To use the image, you need to define a task first. In the ECS `Task definition` > `Create new task definition` menu, configure the following: 1. **Task definition configuration** * Enter an appropriate task name. 2. **Infrastructure requirements** * Set the `Launch type` to `AWS EC2 Instances`. * Choose `Linux/X86_64` for `Operating system/Architecture`. * Leave `Task size` blank. image 3. **Container** * Enter an appropriate container name and the image URI registered in ECR. * Open the port `8000` for service. * Allocate all resources to the container within the task. * Enable the `Use log collection` option in `Logging`. * Leave the CPU/GPU configuration blank. * Set memory limits as follows: * If the EC2 instance has N GB of memory (e.g., 16GB), set the hard limit to N and the soft limit to N/2 - 1. * This soft limit configuration is to allow two tasks to run briefly during a rolling deployment. image 4. **Volume** * A2's data is stored in `/data`. To retain the data, define appropriate storage and mount it to this path. * To retain data using AWS EBS, set `Configuration Type` to `Configure at task definition creation` and choose bind mount for the volume type. * Enter `/data` as the source path. image #### 3. Creating Security Groups Now, create two security groups to set inbound rules between the microservices. One is for the task, and the other is for the load balancer. Search for 'security group' in the AWS console's search bar to navigate to the security groups page. image Click the 'Create security group' button in the top right corner to begin the setup. 1. **Security Group for Load Balancer** image * Set the security group name and inbound rules. * Example: `security-lb` * Add inbound rules for port 8000. * In the example, the source is set to `Anywhere`, but for better security, it's recommended to specify a particular IP. 2. **Security Group for Task** image * Add inbound rules for port 8000, and set the source as the security group of the load balancer. #### 4. Creating Target Groups Create target groups for the load balancer to forward requests. Search for `Target group` in the AWS console and navigate to the page. image 1. **Target Group for Task** image * Create a target group for port 8000. * Choose IP addresses as the target type and set the port to 8000. image * Enter `/api/health` as the health check path. * Click `Next` and complete the target group creation. #### 5. Creating a Load Balancer Search for `Load Balancers` in the AWS console and navigate to the page. image Click the `Create Load Balancer` button in the top right corner, then choose `Application Load Balancer`. 1. **Basic Configuration** image * Select `Internet-facing` for the scheme. * Set the IP address type to `IPv4`. 2. **Network Mapping & Security Groups** image * Select all availability zones for the relevant region (e.g., ap-northeast-2). * Copy and save the VPC ID and Subnet ID as they will be needed when creating services. * Choose the security group created earlier for the load balancer. 3. **Listeners** image * Connect the listeners to the created target groups. 4. **Finished** image * Once the load balancer is created, save the DNS name highlighted in the red box in the image above. This address will be used to access services like the ADM. #### 6. Creating a Service Instead of using the console GUI, we will use CloudFormation to create the service. This is because the GUI does not support associating multiple container ports with the load balancer. More details can be found on [Medium](https://medium.com/@faisalsuhail1/exposing-multiple-ports-for-an-aws-ecs-service-64b9821c09e8). Search for `CloudFormation` in the AWS console and navigate to the page. image 1. **Create Stack** * Click the `Create Stack` button in the top right corner. image * Choose `Upload a template file` and use the following JSON format for the template file, uploading it afterward. Modify the commented sections to fit your environment (enter the values saved earlier). * Enter the task security group's ID in `SecurityGroupIDs`. ```json theme={null} { "AWSTemplateFormatVersion": "2010-09-09", "Description": "The template used to create an ECS Service from the ECS Console.", "Parameters": { "SecurityGroupIDs": { "Type": "CommaDelimitedList" // "Default": "sg-0f21b327b83e33c46" }, "SubnetIDs": { "Type": "CommaDelimitedList" // "Default": "subnet-0b7b40c10645ff898,subnet-059809f716cb81e9e,subnet-013907b4eb89d521f,subnet-020323a92b4d44e1e" }, "VpcID": { "Type": "String" // "Default": "vpc-0ab885f61636987ee" }, "LoadBalancerName": { "Type": "String" // "Default": "lb-test" } }, "Resources": { "ECSService": { "Type": "AWS::ECS::Service", "Properties": { // "Cluster": "cluster-test", // "TaskDefinition": "arn:aws:ecs:ap-northeast-2:339...", "LaunchType": "EC2", // "ServiceName": "service-test", "SchedulingStrategy": "REPLICA", "DesiredCount": 1, "LoadBalancers": [ { // "ContainerName": "container-test", "ContainerPort": 8000, "LoadBalancerName": { "Ref": "AWS::NoValue" } // "TargetGroupArn": "arn:aws:elasticloadbalancing:ap-northeast-2:339..." } ], "NetworkConfiguration": { "AwsvpcConfiguration": { "SecurityGroups": { "Ref": "SecurityGroupIDs" }, "Subnets": { "Ref": "SubnetIDs" } } }, "DeploymentConfiguration": { "MaximumPercent": 200, "MinimumHealthyPercent": 100, "DeploymentCircuitBreaker": { "Enable": true, "Rollback": true } }, "DeploymentController": { "Type": "ECS" }, "ServiceConnectConfiguration": { "Enabled": false }, "PlacementStrategies": [ { "Field": "attribute:ecs.availability-zone", "Type": "spread" }, { "Field": "instanceId", "Type": "spread" } ], "PlacementConstraints": [], "Tags": [], "EnableECSManagedTags": true } } }, "Outputs": { "ECSService": { "Description": "The created service.", "Value": { "Ref": "ECSService" } } } } ``` 2. **Health Check** * Click `Next`, enter a stack name, then continue clicking `Next` until you can submit the service creation request. * Navigate to the cluster page and open the service page. Click the button highlighted in red in the image below. image * Once the service is successfully created, all items highlighted in red in the image below will be marked as `healthy`. image #### 7. Completion You can now access the ADM page by navigating to `:8000`, as shown below. image All settings are complete, and you can use A2 through the assigned DNS after deployment. *** By following this manual, you can successfully deploy A2 on AWS. If you have any additional questions, please feel free to contact our support team. # Deploying A2 OnPrem to GCP Source: https://docs.aiderx.io/development/en/deployment-gcp This guide explains how to deploy A2 OnPrem to Google Cloud Platform (GCP). This guide describes how to deploy A2 using Google Cloud Platform (GCP)'s Compute Engine. ### Setting up GCP Compute Engine #### 1. Prerequisites You need to set up a GCP project and enable the Compute Engine API. This process can be easily performed in the GCP console. #### 2. Creating an Instance 1. Navigate to `Compute Engine` > `VM instances` menu. 2. Click the `CREATE INSTANCE` button. 3. Configure the following settings: * `Name`: Instance name (e.g., "a2-ce") * `Region`: Choose a nearby region (e.g., "asia-northeast3 (Seoul)") * `Machine configuration` > `Machine type`: * Recommend CPU 8 vCPU, memory 16GB or higher. (e.g., e2-standard-8) * Click the `CHANGE` button under `Boot disk`: * `Operating system`: Select "Container Optimized OS" * Verify that the auto-selected `Version` is "x86/64" architecture * (optional) To preserve the disk permanently, select `Keep disk` under `SHOW ADVANCED CONFIGURATION` > `Deletion rule` * click the `SELECT` button. * `Firewall`: Check `Allow HTTP traffic` and `Allow HTTPS traffic` * Expand `Advanced options`: * `Networking` > `Network tags`: Enter "a2-ce" * `Networking` > `Network interfaces` > Expand `default` > `External IPv4 address`: Select `RESERVE STATIC EXTERNAL IP ADDRESS` * Enter "a2-ce" for `name` and click `RESERVE` 4. Click the "CREATE" button at the bottom of the screen to create the instance. #### 3. Setting up Firewall Rules 1. Go to `VPC network` > `Firewall` menu. 2. Click the `CREATE FIREWALL RULE` button. 3. Configure the following settings: * `Name`: Specify a name for the rule (e.g., "allow-a2-ce") * `Targets`: Select `Specified target tags` and enter the previously used tag (e.g., "a2-ce") * `Source filter`: Select `IPv4 ranges` and enter "0.0.0.0/0" (allows access from all IPs) * `Protocols and ports`: Select `Specified protocols and ports`, check `TCP` and enter ports **"8000,8080"** 4. Click the "CREATE" button to create the rule. #### 4. Deploying Docker Image 1. Connect to the instance using the SSH button in the GCP console. 2. Install docker compose ```sh theme={null} curl -s https://gist.githubusercontent.com/kurokobo/25e41503eb060fee8d8bec1dd859eff3/raw/0d7cd29472f0eaa26ce424071456ad84b24fb318/installer.sh | bash source ~/.bashrc docker-compose version ``` 3. Create a docker-compose.yml file: ```yml theme={null} --- services: a2-ce: image: { TO_BE_REPLACED } restart: unless-stopped logging: options: max-file: "1" max-size: "512m" volumes: - /data:/var/a2/data ports: - 8000:8000 - 8080:8080 ``` 4. Run docker compose: ```sh theme={null} docker compose up -d ``` #### 5. Verifying the Service 1. Open a web browser. 2. Access `http://[YOUR_STATIC_EXTERNAL_IP]:8000`. 3. Verify that the service is running normally. ### Reference Images * settings 1 image * settings 2 image * network image * firewall image *** By following this guide, you can successfully deploy A2 to GCP Compute Engine. If you need additional configuration or optimization, please refer to the GCP documentation or contact our support team anytime. # Ad Log Integration Guide Source: https://docs.aiderx.io/development/en/log-integration-data-migration This guide introduces methods for advertising log integration. ## Advertising Log Integration To achieve effective ad modeling and metric tracking, **Advertising Log Integration** is essential. This integration can be performed through two methods: web-based and API-based. Each method allows the collection and analysis of logs for ad requests, impressions, clicks, and conversions. Below, we explain each approach. ### Method Using Web SDK For web-based retail media, you can automatically handle ad requests and log integration (impressions and clicks) by following these steps: 1. Log in to **Admin** and navigate to the **Placement** menu. 2. Select the desired placement from the **Placement List** and click on **Get Placement Tag**. 3. Copy the **footer tag** provided on the page (see screenshot below) and paste it at the bottom of your web app's HTML source. 4. Insert the provided `
` code where you want the ad to appear. You can modify the `a2plct1` part as needed. ‍image.png Once set up, the logs for ad impressions and clicks will be automatically integrated. The conditions for each log transmission are as follows: * **Ad Request Log**: The ad request log is recorded when the ad is ready to be displayed to the user, meaning the likelihood of the ad appearing on the screen has increased. Specifically, this log is sent when the user’s view approaches within about four times the height of the ad, just before the ad appears on the screen. * **Impression Log (vimp)**: The impression log is recorded when the ad actually appears on the user’s screen and becomes visible. More specifically, it’s logged when at least 50% of the ad is visible on the screen for over one second. Compared to the ad request log, which logs when the ad is likely to appear, the impression log records when the ad is actually visible on the screen. * **Click Log**: The click log is sent when the ad is clicked by the user. This captures the exact moment when the user interacts with the ad, allowing for the analysis of ad engagement performance. With this type of log integration, you can gain a more accurate understanding of ad performance and make improvements to enhance ad efficiency effectively. ### Method Using API The API-based advertising log integration method allows direct logging of various actions, such as ad impressions, conversions, and clicks. The A2 system tracks logs based on the `ext.ad_log` field in the Edge response data, and impression logs can also be integrated for in-depth ad performance analysis. 1. Click Logs * Data sent when a user clicks an ad. * Example ```bash theme={null} curl --location 'http://localhost:/' \ --header 'Content-Type: application/json' \ --data '{ "type": "ad_log", "action": "clk", "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8YjM4M2M4YWYtZWUzZi00MDljLTlmOWYtODgxYTI4YWZjYmVjfDk3NGIwOGI4LTc1MjYtNDFkMC04MTg5LWQ4MTVkNTFlZGNlZnw" }' ``` 2. Conversion Logs * Logs sent when a user completes a desired activity (conversion) after viewing an ad. * Conversions can include, but are not limited to, the following activities: * Product purchase * Adding to cart * App installation * Service subscription * Download * Link click * Content consumption for a certain period * Example: ```bash theme={null} curl --location 'http://localhost:/' \ --header 'Content-Type: application/json' \ --data '{     "type": "ad_log",     "action": "conv", "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8YjM4M2M4YWYtZWUzZi00MDljLTlmOWYtODgxYTI4YWZjYmVjfDk3NGIwOGI4LTc1MjYtNDFkMC04MTg5LWQ4MTVkNTFlZGNlZnw" }' ``` 3. (Optional) Impression Logs * Impression logs are not mandatory in A2, but are recommended for accurate metric measurement. * Impression logs are sent when an ad is actually displayed to a user. * It is recommended to measure whether an ad is displayed based on whether more than 50% of the ad is visible on the user’s screen for at least one second. * If the above criteria cannot be met due to system constraints or other reasons, it is recommended to measure impressions using at least the same criteria. * Example: ```bash theme={null} curl --location 'http://localhost:/' \ --header 'Content-Type: application/json' \ --data '{ "type": "ad_log", "action": "vimp", "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8YjM4M2M4YWYtZWUzZi00MDljLTlmOWYtODgxYTI4YWZjYmVjfDk3NGIwOGI4LTc1MjYtNDFkMC04MTg5LWQ4MTVkNTFlZGNlZnw" }' ``` *** I hope this guide helps with advertising log integration. If you have any further questions or need additional support, please feel free to contact us. Thank you. # Monitoring: Prometheus Exporter Integration Source: https://docs.aiderx.io/development/en/prometheus-exporter-monitoring image ## A2 Monitoring Overview: Prometheus Exporter Integration The A2 platform provides real-time monitoring metrics through the [Prometheus](https://prometheus.io) Exporter feature. By using Prometheus, you can easily view and manage key performance metrics via dashboards or alert settings, enabling continuous monitoring of the platform’s health. A2's Prometheus Exporter operates on port `29100` by default. ### Metrics by Namespace The monitoring metrics provided by A2 are categorized by namespace, with each namespace offering different types of log and status information. #### Ad and Service Event Logs Metrics related to ad and service events can be found under the following two namespaces: **ad\_log**: This namespace records data related to ad activities such as ad delivery, impressions, clicks, and conversions. It is useful for monitoring the performance of ad campaigns. **event\_log**: This namespace tracks service event logs and includes user activities such as page views, purchases, likes, and cart additions. It can be used to analyze user behavior on the platform. #### Monitoring Internal Modules (ADM, DSP, Edge) The status and performance metrics of internal modules like ADM, DSP, and Edge are provided under the following namespaces: **a2\_stats**: This namespace contains performance data for A2's internal modules, such as Edge's average response time, ad delivery volume, and ad request counts. Metric names follow the `a2_stats_*` format and are useful for assessing system performance and efficiency. **a2\_error**: This namespace provides information on system errors, including HTTP errors and internal processing errors. It helps in identifying the status of errors and assists in troubleshooting. ### Using Prometheus Metrics The data collected through Prometheus can be queried and viewed in real-time, allowing you to explore metrics under each namespace. For instance, `a2_stats_edge:req_total` represents the total number of requests for the Edge module, while `a2_error_edge:http_total` shows the total count of HTTP errors that occurred within the Edge module. *** A2’s monitoring features can be used as needed, offering flexible data insights to help you manage your system effectively. # Serving ADs Source: https://docs.aiderx.io/development/en/serving-ad Serving ADs with A2 ## A2 Ad Request Guide This guide provides instructions on how to retrieve ads for serving after creating ad campaigns, creatives, and placements, and completing ad setup on the A2 platform. ## Prerequisites Before making ad requests, ad setup must be completed. Please refer to the following guide: * [Getting started with A2: Preparation](/guides/get-started/en/preparation) * [Getting started with A2: Basic Usage](/guides/get-started/en/basic-usage) ## Methods for Requesting Ads There are two methods to request ads from the A2 platform: 1. Direct server API call 2. Using the Web SDK ### Direct Server API Call To request ads by directly calling the server API, follow these steps: **1. API Base URL** * HTTPS: `https://{customer_id}.aiderx.app` * To verify server accessibility, send a GET request to the following endpoint: `/healthcheck` **2. Request Path** * `/app/v0/ad/{tagid}` * The `tagid` is the `id` value found in the `Placement Information` section on the details page, accessible via `Advertising > Placement > Placement List > (Click on Placement)` ![tagid](https://aiderx-public.s3.ap-northeast-2.amazonaws.com/public/media/serving-ad/tagid-en.png) **4. Detailed API Specification** * An OpenAPI Specification page is provided to view detailed API specifications and test requests directly. * Access it at the following URL: * `https://{customer_id}.aiderx.app/docs` * This page allows you to examine all parameters, request bodies, response formats, and send actual requests to the server for verification. **5. API Test Request Example** * Click `Test Request` on the right side of the page ![api-spec-0](https://aiderx-public.s3.ap-northeast-2.amazonaws.com/public/media/serving-ad/api-spec-0.png) * Enter the tagid value in `Path Variables`, set the `version` to `0.0.1` in the `Body`, and click `Send` * Review the results ![api-spec-1](https://aiderx-public.s3.ap-northeast-2.amazonaws.com/public/media/serving-ad/api-spec-1.png) ### Using the Web SDK For detailed information on requesting ads using the Web SDK, refer to the "Using the Web SDK" section in the [Log Integration and Data Migration Guide](/development/en/log-integration-data-migration). ## Conclusion This guide has introduced two methods for requesting ads from the A2 platform. Choose the method that best suits your needs: either direct server API calls or using the Web SDK. For further assistance, you can reach out to the A2 support team through the following channels: * Email: [a2support@aiderx.io](mailto:a2support@aiderx.io) * Slack: [https://a2cloudsupporthub.slack.com](https://a2cloudsupporthub.slack.com) * To join the Slack workspace, use this invitation link: [https://join.slack.com/t/a2cloudsupporthub/signup](https://join.slack.com/t/a2cloudsupporthub/signup) # System Error Resolution Guide Source: https://docs.aiderx.io/development/en/troubleshooting Detailed explanation of troubleshooting methods for various errors occurring in the A2 system. This document provides solutions to common issues that may arise when using A2. Users can use this document to easily check system settings and limitations, quickly diagnose issues, and maintain operational stability. ## Checking License Limits A2 applies various limitations, such as API limits, based on the user’s license tier. To view the applied limitations and current usage, log in to the Admin page with an administrator account, click the **Settings** menu at the bottom of the right sidebar, and you will see a screen displaying the current settings and usage. ‍image.png ‍ ## Guide for Resolving No Content Responses When Calling Edge If a **No Content** response is received when sending an ad request from the Edge(Supply Side Platform) to a media placement, it may indicate an issue with the assignment or settings of the placement. At least one active assignment must be published for the content to display correctly. Follow the steps below to ensure the placement is configured correctly and to avoid No Content responses: 1. Log in to the Admin page with the **Retailer Account** that created the placement. 2. Navigate to the **Placement** menu on the Admin dashboard. 3. Select the placement you want to check. 4. On the selected placement page, verify that there is at least one assignment marked as **Published**. If the placement is not linked to any assignments, or if all linked assignments are inactive (e.g., if all campaigns registered in the media have exhausted their budgets or reached their end dates and thus have been marked as completed), the ad request will not be able to retrieve content, resulting in a No Content response. Ensure that each placement has active, published assignments linked to it for ads to display correctly. ## Troubleshooting in an On-Premise Environment In an on-premise environment, you can directly access the server to diagnose and resolve issues. This section focuses on troubleshooting methods that can be performed by physically accessing the server. By analyzing local logs and other resources, you can respond more quickly and in greater detail. ### Supervisord A2 uses [supervisord](http://supervisord.org) to manage processes. If a Docker container is marked as `Unhealthy`, it indicates that there is an issue with one of the processes managed by Supervisord. In such cases, you can diagnose the problem by checking the logs recorded in `/opt/supervisord.log`. For example, if a specific process is marked as FATAL, it means that the process has exited and failed to restart. You can identify the exact cause of the issue by reviewing the logs. For general process management, you can access supervisorctl as follows: ```bash theme={null} root@5f2769832e02:/opt# supervisorctl -s http://localhost:23231 -u a2 -p a2 a2-adm-backend RUNNING pid 74, uptime 2 days, 5:13:37 a2-docs RUNNING pid 75, uptime 2 days, 5:13:37 a2-dsp RUNNING pid 76, uptime 2 days, 5:13:37 a2-edge RUNNING pid 77, uptime 2 days, 5:13:37 a2_sinker RUNNING pid 78, uptime 2 days, 5:13:37 event_stream RUNNING pid 85, uptime 2 days, 5:13:37 nginx RUNNING pid 96, uptime 2 days, 5:13:37 redis RUNNING pid 97, uptime 2 days, 5:13:37 vector RUNNING pid 98, uptime 2 days, 5:13:37 supervisor> restart ``` Key supervisord commands: * **status**: Check the status of all processes. * **start \**: Start a specific program. * **stop \**: Stop a specific program. * **restart \**: Restart a specific program. * **tail \**: View the log of a specific program in real-time. For more detailed commands, enter help or check the official supervisord documentation. ### Process Logs A2 consists of the following major components, and their logs can be found at these paths: 1. ADM (Advertising Manager) * /var/log/nginx.log: ADM frontend related logs * /var/log/a2-adm-backend.log: ADM backend related logs 2. DMP (Data Management Platform) * /var/log/a2-sinker.log: Data collection related logs * /var/log/event\_stream.log: Event streaming related logs * /var/log/redis.log: Event streaming related logs * /var/log/vector.log: Log and metric collector related logs 3. Edge/DSP (Supply-Side Platform / Demand-Side Platform) * /var/log/a2-edge.log: Edge related logs * /var/log/a2-dsp.log: DSP related logs 4. Modeling * /var/log/a2-train.log: Machine learning model training related logs Please inquire via [Slack](https://a2cloudsupporthub.slack.com) with log snippets. # Campaign creation and publication request processing by api Source: https://docs.aiderx.io/development/tutorial/en/campaign-management Describes how to create campaigns and handle approval requests by API # Campaign Management A campaign is an advertising activity unit that allows advertisers to execute specific ads and measure performance according to their set goals. A2 provides the essential APIs needed to manage campaigns, including creating new campaigns, retrieving campaigns, and modify and deleting in existing campaigns, as well as APIs related to approvals for campaigns. ## Create Campaign First, you need to create a campaign to ads. When you create a campaign, you can set a number of settings, including the duration of the campaign, the budget to use, the bidding strategy, and the campaign goals. ```bash Create Campaign Example theme={null} curl --request POST \ --url https://your_a2_service/campaigns \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "test campaign", "description": "test campaign", "start_date": "2025-04-12 16:47:03.773", "end_date": "2025-05-13 16:47:03.773", "goal": "impression", "sub_goal": "maximize_volume", "status": "okay", "budget": "10000", "bid_strategy": "bid_cap", "owner_id": "{owner-user-id}" }' ``` ## Create Creative Creating a campaign isn't enough to run an ad. You can prepare to run an ad by registering the creative that you want to show on the placement. Campaigns can have a variety of creative types, including images, video, native. However, if the creative in your campaign doesn't match the type of creative required by the placement, you won't be able to allocate. ```bash Create Creative Example theme={null} curl --request POST \ --url https://your_a2_service/creatives \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "test creative", "type": "banner", "staatus": "inactive", "width": 300, "height": 100, "banner": { "img": "https://example.com/creative.png" }, "cid": "{campaign-id}", "owner_id": "{owner-user-id}" }' ``` # Approvement of a Campaign Once you've created a campaign, you can request to run it as an ad. The requested campaign will be reviewed based on own criteria, and if approved, it will begin running immediately. ## Request Publish Once your campaign has been successfully created, you can request that your ad appear in placement. At this point, you must have at least one activated creative, and it must match the creative format of the placement. ```bash Create Allocation Example theme={null} curl --request POST \ --url https://your_a2_service/allocations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "tagid": "{placement-id}", "status": "pending", "cid": "{campaign-id}", "crid": "{creative-id}", "owner_id": "{owner-user-id}" }' ``` ## Approve and Reject The creatives or links used in the campaign may not meet your standards. At this point, you need to go through a review before you can approve. If the campaign is approved or rejected, you can update the results using the campaign update API. \\ You can also set the **last\_comment** to reply the reason for the rejection. ### Status Code | code | description | | - | - | | pending | Initial state | | requested | publish requested | | published | published | | rejected | Rejected | | canceled | canceled | | finished | finished | ```bash Update Allocation Example theme={null} curl --request PATCH \ --url https://your_a2_service/allocations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "tagid": "{placement-id}", "status": "published", "cid": "{campaign-id}", "crid": "{creative-id}", "owner_id": "{owner-user-id}" }' ``` # Metric of Campaign Once your campaign is approved, the ad will start showing immediately. Campaign metrics are collected and managed for each ad served. This data can help to be more effective campaign strategy. ## Metric Analysis You can see how your campaigns are performing by metric APIs for any timeframe, including daily, hourly, and more. ```bash Get Campaign Hourly Metric Example theme={null} curl --request POST \ --url https://your_a2_service/metric/campaigns_hourly \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "campaign_id": "{campaign_id}", "tagid": "{placement-id}", "from_datetime": "2025-03-14 16:47:03.773", "to_datetime": "2025-04-13 16:47:03.773" }' ``` # How to get access token for api usage Source: https://docs.aiderx.io/development/tutorial/en/get-token Describes how to get the access tokens you need to use A2's APIs. ### Access token Access tokens are essential for using the A2 Platform's APIs. For security, access token must be attached to the API call of A2 Platform, otherwise you will get an authorization error. You can use only one access token in A2. #### Initial issuance of access token The A2 starts with no access token issued. Therefore, if you want to integrate through the API, you need to issue an access token. The APIs is not available because the access token has not yet been issued, so you can issue it in ADM. image.png #### Regenerate access token by API You can also change the access token as needed. This can be done through the API as well as ADM. ```bash Regenerate Access Token theme={null} curl --request POST \ --url https://your_a2_service/settings/access_token \ --header 'Authorization: Bearer ' ``` As soon as a new token is issued, the parts of the application that were linked using the previously issued access token will not work. ```json Response theme={null} { "access_token": { "access_token": "", "token_type": "Bearer" }, "created_at": "2023-11-07T05:31:56Z", "currency": "usd", "external_channel_url": "", "language": "en", "tls_domain": "", "tls_enable": true, "updated_at": "2023-11-07T05:31:56Z", "yield_optimization": { "ceiling_cpm": 123, "floor_cpm": 123, "yield_roas_balance": 0.5 } } ``` # Ads Integration with SDK Source: https://docs.aiderx.io/development/tutorial/en/sdk-usage This guide introduces methods for requesting ads and advertising log integration. # Ads Integration There are two ways to request ads on the A2 platform: by calling the server API directly and by using the web SDK. Using the server API directly has the advantage of giving you direct control over most aspects of the ad request, but it's a bit more complicated because you'll need to develop both the process of requesting and serving ads and integrating logs. We provide a web SDK to make it easy and convenient to apply these pieces. ## Ads Request ### By Web SDK The Web SDK is a package that can be embedded into web page that contains a placement. It is configured to allow you to request ads with easy setup. To use the Web SDK, you need to embed the SDK in a web page. The insertion of the SDK is done by following these steps: 1. Log in to ADM and navigate to the **Placement** menu. 2. Select the desired placement from the **Placement List** and click on **Get Placement Tag**. 3. Copy the footer tag provided on the page (see screenshot below) and paste it at the bottom of your web app's HTML source. 4. Insert the provided `
` code where you want the ad to appear. You can modify the `a2plct1` part as needed. get_placement_tag Once set up, the ad will be automatically integrated. ### By Server APIs You can use Serving an ad API to get ads. To learn more about the serving an ad, check this [Serving ADs](/development/en/serving-ad). ## Ads Log Integration ### By Web SDK Log integration is automatic with the web SDK. The conditions for each log transmission are as follows: * **Ad Request Log**: The ad request log is recorded when the ad is ready to be displayed to the user, meaning the likelihood of the ad appearing on the screen has increased. Specifically, this log is sent when the user’s view approaches within about four times the height of the ad, just before the ad appears on the screen. * **Impression Log (vimp)**: The impression log is recorded when the ad actually appears on the user’s screen and becomes visible. More specifically, it’s logged when at least 50% of the ad is visible on the screen for over one second. Compared to the ad request log, which logs when the ad is likely to appear, the impression log records when the ad is actually visible on the screen. * **Click Log**: The click log is sent when the ad is clicked by the user. This captures the exact moment when the user interacts with the ad, allowing for the analysis of ad engagement performance. With this type of log integration, you can gain a more accurate understanding of ad performance and make improvements to enhance ad efficiency effectively. ### By Server APIs The API-based advertising log integration method allows direct logging of various actions, such as ad impressions, conversions, and clicks. The A2 system tracks logs based on the ext.ad\_log field in the Edge response data, and impression logs can also be integrated for in-depth ad performance analysis. # A2: Aider for Advertising Source: https://docs.aiderx.io/guides/about-a2/en/a2-introduction A2 is a **Retail Media Platform (RMP)** designed to help efficiently manage and operate advertisements on online shopping malls or retail sites. Through this platform, site owners can set up and manage various ad placements, and collaborate with advertisers to run effective ad campaigns. ## A2 Overview image The above image shows an example of ad management using A2. This site has three main ad locations: 1. Top video banner 2. Right-side banner 3. Ads within product listings In A2, these locations where ads are displayed are called **placements**. Placement managers can configure the following settings for each ad placement: * Types of ads that can be displayed * Ad sizes Ads are operated in **campaign** units. Each campaign has the following characteristics: * Includes one or more **creatives** * Campaign managers can set: * Ad display period * Ad budget * Ad target metrics * Can be **allocated** to desired placements * Ad display proceeds through approval by each placement manager For example, when creating a campaign to promote a new summer product line, the campaign manager can request to allocate a campaign with video creative to the top banner, and a campaign with image creative to the side banner and in-product list ads. By using creatives that match the characteristics of each placement, ad effectiveness can be optimized. A2 provides various technologies and features to make this ad operation even more effective: * **Utilization of machine learning technology**: A2 uses the latest machine learning technology to display the most suitable ads for each placement. * **Utilization of first-party data**: By integrating user click, purchase, and conversion data along with retail catalog items with A2, more sophisticated targeting and efficient ad creative generation becomes possible. * **Data-driven insights**: A2 can analyze the performance of each campaign and placement. For example, you can compare and analyze the click-through rate of side banner placements, the conversion rate of campaigns within product listings, etc., to determine which forms of advertising are most effective. This allows advertisers to focus their budget on the most efficient placements and creatives. Through these features, A2 functions as an intelligent advertising platform that utilizes data and technology, beyond a simple ad management tool. Advertisers can reach more accurate target customers, and site operators can optimize ad revenue without compromising user experience. A2 offers three types of accounts: 1. **Administrator**: Has full permissions of both retailer and advertiser accounts, budget allocation, and system configuration. 2. **Retailer**: Placement management, placement analysis, allocation approval 3. **Advertiser**: Campaign management, campaign analysis, allocation requests You can systematically operate the platform by issuing appropriate types of accounts according to specific needs. For example, administrators who oversee the advertising strategy for the entire site, retailers who manage ads on specific placements, and external advertisers who directly promote their products can each utilize permissions and features tailored to their roles. Customers who wish to operate A2 conveniently without distinguishing between retailer and advertiser accounts can simply use an administrator account. In summary, A2 provides the following functions: 1. **Efficient Ad Management** * Integrated management of various ad placements in one place * Improved ad operation efficiency 2. **Flexible Campaign Settings** * Free setting of budget, period, creative, etc. * Support for customized campaign operation 3. **Transparent Performance Analysis** * Provision of real-time click, impression, conversion logs * Transparent analysis of ad performance possible 4. **Personalized Ad Delivery** * Customized ad delivery through user log integration * Maximization of ad effectiveness ## Detailed Feature List 1. **Placement Management** * Management of displayed campaigns * Setting of ad types and sizes * Provision of Web SDK (for ad display and log integration) * Performance analysis by placement 2. **Campaign Management** * Setting of display creatives, period, budget * Campaign performance analysis * Creative management (image upload, display approval, etc.) 3. **Account Management** * Creation and management of accounts by permission (placement management, campaign management, etc.) * Budget allocation by advertiser account 4. **Data Utilization** * User information integration (gender, age, etc.) * User activity log integration (purchases, conversions, clicks, etc.) *** A2 is a comprehensive platform that can efficiently manage the entire process of ad operation. It supports smooth collaboration between administrators, retailers, and advertisers, and enables systematic performance analysis through API ad requests and log integration. Additionally, by providing user-customized ads through personalized ad settings, it can maximize ad effectiveness. Upgrade your online advertising operation to the next level with A2! # A2 OnPrem Source: https://docs.aiderx.io/guides/about-a2/en/a2-vs-saas-vs-inhouse Comparing A2, SaaS, and in-house development. ## 1. A2 OnPrem's Price Competitiveness ### Diverse Pricing Structure A2 OnPrem, as a on-premise product, offers different pricing structures based on the deployment environment. | | Self-hosted | Private Cloud | Public Cloud | | - | - | - | - | | License | ✓ | ✓ | ✓ | | Operation & Maintenance | ✓ | Optional\* | Optional\* | | Infrastructure | - | - | Pay-as-you-go\* | * *Ad revenue sharing fees are flexible depending on the pricing plan.* If you already have a self-hosted server or private cloud infrastructure, you can minimize A2 OnPrem's maintenance costs. When using public cloud services, infrastructure costs are billed proportionally to usage, ensuring a transparent pricing structure. Should you require maintenance support from A2 experts, we offer additional services including basic operations, incident handling, and product upgrades. This is a valuable option for companies with limited in-house development resources or those aiming for timely deployment and stable operations. ### Plans with Different Pricing Structures A2 OnPrem offers several paid plans to meet diverse customer needs: Starter, Professional, and Enterprise. * **Starter**: Accessible with a fixed annual license fee. * **Professional**: No annual license fee; charges based on a commission of the client's ad revenue. * **Enterprise**: Offers a more competitive pricing structure compared to Professional, suitable for large-scale retail operations. ### Total Cost of Ownership Differs As a on-premise product, A2 allows you to reap the benefits of technology investment. Over time, various tangible and intangible assets accumulate, effectively reducing the total cost of ownership: * Customer data and ML models built with A2 * Advertising performance data * Machine learning system integration and operational expertise ## 2. Price Comparison: A2 OnPrem vs. 3rd-Party SaaS Solutions and In-House Development A2 reduces the implementation costs and time required for in-house development. In the long term, it offers competitive maintenance costs compared to SaaS and the benefits of technology investment, providing optimized value for clients. | | SaaS | In-House Development | A2 OnPrem | | - | - | - | - | | Initial Investment | **Low** | High | **Low** | | Implementation Time | **Short** | Requires significant time for specialized personnel and infrastructure setup | **Short** | | Maintenance Cost | **Low** | High costs for maintaining specialized infrastructure personnel | **Low** | | Long-term Costs | High long-term cost burden due to revenue-based pricing | **Low long-term maintenance costs** | **Competitive long-term costs compared to SaaS** | | Customization | Difficult | **High flexibility** | **High flexibility** | | Technology Investment | - | **Data internalization/technical independence** | **Data internalization/technical independence** | # Account & Budget Source: https://docs.aiderx.io/guides/about-a2/en/account-and-budget Detailed guide on account types and budget allocation. ### Account Types A2 offers three types of accounts: 1. **Administrator**: Has full permissions of both retailer and advertiser accounts, budget allocation, and system configuration. 2. **Retailer**: Placement management, placement analysis, allocation approval 3. **Advertiser**: Campaign management, campaign analysis, allocation requests You can systematically operate the platform by issuing appropriate types of accounts according to specific needs. For example, administrators who oversee the advertising strategy for the entire site, retailers who manage ads on specific placements, and external advertisers who directly promote their products can each utilize permissions and features tailored to their roles. Customers who wish to operate A2 conveniently without distinguishing between retailer and advertiser accounts can simply use an administrator account. ### Budget #### What is A2 Advertising Budget? Advertising budget refers to the amount you wish to spend on exposing your advertising campaigns to people. When an administrator or retailer allocates a budget to an advertiser account, the advertiser can use it for their campaigns. #### How to Allocate Budget From an administrator or retailer account, navigate to the "Advertiser List" menu and click the edit information button of the advertiser to whom you want to allocate budget. ```html theme={null}
``` ### Credits Credits are free funds that allow advertisers to run advertising campaigns without paying actual cash. Credits serve as promotional or compensatory amounts that advertisers receive without additional cost, which can be used for purposes such as new registration rewards, special promotion participation, loyal customer rewards, compensation for system errors, and trial experiences. The credit system provides advertisers with opportunities to experience the service without risk and to try more campaigns. More flexible system operation is possible by managing budgets and credits separately. Credits can be granted in the same way as budgets. # Allocation Source: https://docs.aiderx.io/guides/about-a2/en/allocation Introduction to Allocation ## A2: Allocation Guide ### What is Allocation? "Allocation" refers to the process required to display an advertising campaign on a specific placement. Advertisers can create campaigns and request allocation for the desired placements. The retailer, who manages the placements, reviews and approves the requests before the campaigns are finally displayed. > Depending on account permissions, campaigns can also be displayed without retailer approval. **Purpose of Allocation** * Establishing clear roles and responsibilities between advertisers and retailers. * Providing management features for ad placement and display. * Controlling campaign exposure and preventing fraudulent activities, such as ad fraud or abuse (Ad Fraud/Abusing). This document explains the step-by-step process of requesting and approving allocations to support successful ad campaign operations. *** ### Requesting and Approving Allocation