Log Integration and Data Migration Guide

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 <div id="a2plct1"></div> code where you want the ad to appear. You can modify the a2plct1 part as needed

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 SSP 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

curl --location 'http://localhost/app/v0/log' \
    --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:

curl --location 'http://localhost/app/v0/log' \
    --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:

curl --location 'http://localhost/app/v0/log' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "ad_log",
        "action": "vimp",
        "ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8YjM4M2M4YWYtZWUzZi00MDljLTlmOWYtODgxYTI4YWZjYmVjfDk3NGIwOGI4LTc1MjYtNDFkMC04MTg5LWQ4MTVkNTFlZGNlZnw"
    }'

Data Migration

Since A2 is provided on-premise, you can fully utilize first-party data. This section explains how to integrate first-party data.

1. User Data

User data includes the gender, age, interests, and activity region of service users. Each field required for data integration is explained below. If the service does not have all the data, not all fields need to be integrated.

• Data Fields
  • id: User identifier. It must be the same value as the one called by the SSP.
  • gender: User’s gender. Use M for male, F for female, and O for others.
  • yob: User’s year of birth.
  • keywords: User’s interests. Not limited to specific categories.
  • geo: User’s activity region.
• User Update Example:

curl -X PUT 'http://localhost/app/v0/log' \
    --header 'Content-Type: application/json' \
    --data '{    
        "type": "user_log",
        "id": "<userid>",    
        "gender": "M",    
        "yob": 1998,    
        "keywords": ["IT", "marketing", "game"],    
        "geo": "Seoul"
    }'

• User Deletion Example:

curl -X DELETE 'http://localhost/app/v0/log' \
    --header 'Content-Type: application/json' \
    --data '{    
        "type": "user_log",
        "id": "<userid>"
    }'

2. Service Log Integration

If there are service activity logs of users in the existing service, A2 can utilize the data to make advertising targeting more precise. Here is how to integrate the data.

• Action Types
  • The actions of users are defined differently and considered important for each service. For example, in a commerce service, activities such as purchasing or adding to cart are important, whereas in a content service, the user’s content clicks are important. A2 has defined the following types, and this list will continue to be updated.
    • clk: Click
    • srch: Search
    • vw: Pageview
    • prch: Purchase
    • crt: Add to cart
• Data Fields
  • user_id: User identifier. It must be the same value as the one called by the SSP.
  • action_type: Action type. See above for details.
  • item_id: The item where the user’s activity occurred. For example, the item ID for a purchase, the keyword for a search, the content ID for a click, etc.
  • timestamp: The time when the user’s activity occurred. If this field is not available, the log’s incoming time will be used. This is only needed for integrating past logs.

• Example

curl --location 'http://localhost/app/v0/log' \
    --header 'Content-Type: application/json' \
    --data '{    
        "type": "action_log",
        "user_id": "<userid>",    
        "action_type": "clk",    
        "item_id": "content-1234",    
        "timestamp": "2024-07-07T12:23:34.105203Z"
    }'

I hope this guide helps with advertising log integration and data migration tasks. If you have any further questions or need additional support, please feel free to contact us. Thank you.

‍