Log Integration and Data Migration Guide

Advertising Log Integration

Effective advertising modeling and metric tracking require advertising log integration. Logs in A2 are tracked based on the ext.ad_log field value in the SSP response data. Based on this, the following log integrations are necessary.

1. Click Logs

• Data sent when a user clicks an ad.
• Example

curl --location 'http://localhost:<A2_DATA_PORT>/' \
--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:<A2_DATA_PORT>/' \
--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:<A2_DATA_PORT>/' \
--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:<A2_DATA_PORT>/user' \
	--header 'Content-Type: application/json' \
	--data '{    "id": "<userid>",    "gender": "M",    "yob": 1998,    "keywords": ["IT", "marketing", "game"],    "geo": "Seoul"}'

• User Deletion Example:

curl -X DELETE 'http://localhost:<A2_DATA_PORT>/user' \
	--header 'Content-Type: application/json' \
    --data '{    "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:<A2_DATA_PORT>' \
	--header 'Content-Type: application/json' \
    --data '{    "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.

‍