Developer Docs
DashboardUser GuideDataspecStatus Page

Event Structure

Suggest Edits

Event Structure

  • Event Category (string, required): 이벤트의 이름이며, 모든 이벤트는 Event Category(이벤트 이름)가 필수적으로 존재합니다. Airbridge가 수집하는 이벤트 중 Event Category(이벤트 이름)가 존재하지 않는 이벤트는 없습니다.
    • Event Action (string, optional): 이벤트 속성 1 입니다.
    • Event Label (string, optional): 이벤트 속성 2 입니다.
  • Event Value (float, optional): 이벤트 값(numeric) 속성 입니다. 발생한 이벤트의 가치를 집계(aggregation)할 때 유용합니다.
  • Semantic Attributes (map, optional): Airbridge에서 미리 정의해둔 이벤트의 Key Value 속성들입니다. Event Category에 따라 정해진 Semantic Attributes들이 있습니다. 자세한 설명은 아래 Semantic Attributes 섹션을 참고해주세요.
  • Custom Attributes (map, optional): 자유롭게 넣어 사용할 수 있는 이벤트의 Key Value 속성입니다. 자세한 설명은 아래 Custom Attributes 섹션을 참고해주세요.

Event Category, Action, Label의 Validation Spec은 FAQ 섹션을 확인해주세요.

📘

Event Taxonomy 설계시 Category, Action, Label라는 속성 이름을 크게 신경쓰지 마십시오.

Event Action이라고 해서 꼭 사용자 행동을 의미하는 값을 넣고, Event Label이라고 해서 꼭 라벨스러운 값을 넣어야하는 것은 아닙니다. 기억해야할 것은 Event Category(이벤트 이름)은 필수 속성이고, Action과 Label은 Actual Report에서 더 상세하게 이벤트들을 구분하여 보고 싶을때 사용하는 속성이라는 것입니다. Event Category(이벤트 이름)으로 모든 이벤트를 구분하고 싶은 경우, Action, Label은 사용하지 않으셔도 됩니다. 아래 Event Taxonomy 예를 참고해주세요.

📘

Custom Attributes를 대신 Action, Label을 사용하는 이유

Event Category, Event Action, Event Label은 그 값들을 Indexing하여 빠르게 Aggregration 값을 제공할 수 있기 때문에 활용도가 높습니다.

Raw Data Export나 S3 Integration을 사용하여 직접 JSON String 포맷의 Custom Attributes를 파싱하여 데이터 분석에 활용하는 경우만 존재한다면 그렇게 해도 괜찮습니다만 Actual Report에서 Aggregation 값을 보고 싶다거나, Raw Data Export에서 속성별로 구분된 컬럼을 확인하고 싶다면 Action, Label을 사용하실 것을 권장드립니다.

Event Taxonomy 예

Action, Label 미사용 예

Event CategoryEvent ActionEvent LabelEvent ValueSample Code (Web)
purchase_card--35000airbridge.events.send("purchase_card", { "value": 35000 })
purchase_cash--55000airbridge.events.send("purchase_cash", { "value": 55000 })
1848

Action, Label 미사용 Actual Report 예

Action, Label 사용 예

Event CategoryEvent ActionEvent LabelEvent ValueSample Code (Web)
add_to_wishlistShoe364757-10335000airbridge.events.send("add_to_wishlist", { "action": "Nike", "label": "364757-103", "value": 35000 })
add_to_wishlistCloth679421-480189000airbridge.events.send("add_to_wishlist", { "action": "Adidas", "label": "679421-480", "value": 189000 })
1850

Action, Label 사용 Actual Report 예

Semantic Attributes

Semantic Attributes는 Airbridge System에서 미리 정의된 Key Value 속성입니다. Airbridge는 Semantic Attributes를 활용하여, Raw Data Export 컬럼을 제공하거나 매체에서 의도한 파라미터 값을 채워 포스트백을 전송합니다. Event Category별 Semantic Attributes는 링크를 참고해주세요.

KeyTypeDescription
totalValuefloat총 매출액 (총 상품 가치)
contributionMarginfloat공헌이익 매출액
currencystring통화
totalQuantityint전체 수량
transactionIDstring거래 ID
cartIDstring장바구니 ID
productListIDstring상품 리스트 ID
inAppPurchasedbooleanIn-app 구매 여부
true : In-app 구매
false : In-app 구매 아님
querystring사용자 검색 쿼리
productsarray상품 리스트
products.$0.productIDstring상품 ID
products.$0.namestring상품 이름
products.$0.pricefloat상품 가격
products.$0.quantityint상품 수량
products.$0.currencystring화폐 단위
products.$0.positionint상품 위치
// semanticAttributes 활용 예                     
airbridge.events.send("purchase_card", {
  semanticAttributes: {
    transactionID: '1458132a-0d09-4944-a686-fcbee81b74f7',
    totalValue: 99000,
    products: [{
      productID: "1234",
      name: "Nike 1",
      price: 55000,
      currency: "KRW",
      quantity: 1
    }, {
      productID: "1235",
      name: "Nike 2",
      price: 44000,
      currency: "KRW",
      quantity: 1
    }]
  }
});

#import <AirBridge/ABInAppEvent.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];

[event setCategory:@"purchase_card"];

NSDictionary* semantics = @{
    @"transactionID": @"1458132a-0d09-4944-a686-fcbee81b74f7",
    @"totalValue": @99000,
    @"products": @[@{
        @"productID": @"1234",
        @"name": @"Nike 1",
        @"price": @55000,
        @"currency": @"KRW",
        @"quantity": @1,
    }, @{
        @"productID": @"1235",
        @"name": @"Nike 2",
        @"price": @44000,
        @"currency": @"KRW",
        @"quantity": @1,
    }],
};
[event setSemantics:semantics];

[event send];

let event = ABInAppEvent()

event?.setCategory("purchase_card")

let semantics: [String: Any] = [
    "transactionID": "1458132a-0d09-4944-a686-fcbee81b74f7",
    "totalValue": 99000,
    "products": [[
        "productID": "1234",
        "name": "Nike 1",
        "price": 55000,
        "currency": "KRW",
        "quantity": 1,
    ], [
        "productID": "1235",
        "name": "Nike 2",
        "price": 44000,
        "currency": "KRW",
        "quantity": 1,
    ]]
]
event?.setSemantics(semantics)

event?.send()

Map<String, Object> product1 = new HashMap<>();
product1.put("productID", "1234");
product1.put("name", "Nike 1");
product1.put("price", 55000);
product1.put("currency", "KRW");
product1.put("quantity", 1);

Map<String, Object> product2 = new HashMap<>();
product1.put("productID", "1235");
product1.put("name", "Nike 2");
product1.put("price", 44000);
product1.put("currency", "KRW");
product1.put("quantity", 1);

List<Map<String, Object>> products = new ArrayList<>();
products.add(product1);
products.add(product2);

Map<String, Object> semanticAttributes = new HashMap<>();
semanticAttributes.put("transactionID", "1458132a-0d09-4944-a686-fcbee81b74f7");
semanticAttributes.put("totalValue", 99000);
semanticAttributes.put("product", products);

Airbridge.trackEvent(
  "purchase_card", // Category
  null, // Action
  null, // Label
  null, // Value
  null, // Custom Attributes
  semanticAttributes // Semantic Attributes
);

Airbridge.trackEvent(
  category = "purchase_card",
  semanticAttributes = mapOf(
    "transactionID" to "1458132a-0d09-4944-a686-fcbee81b74f7",
    "totalValue" to 99000,
    "products" to mapOf(
      "totalValue" to 99000,
      "product" to listOf(
        mapOf(
          "productID" to "1234",
          "name" to "Nike 1",
          "price" to 55000,
          "currency" to "KRW",
          "quantity" to 1
        ),
        mapOf(
          "productID" to "1235",
          "name" to "Nike 2",
          "price" to 44000,
          "currency" to "KRW",
          "quantity" to 1
        )
      )
    )
  )
)

📘

semanticAttributes.totalQuantity는 SDK나 API 등을 통해 이벤트 수집시 넣어주지 않아도, products 리스트 내 quantity(semanticAttributes.products.$.quantity)가 존재하는 경우, 해당 값들의 총합이 자동으로 들어가 Raw Data Export에 제공됩니다.

<이벤트 전송 예>

airbridge.events.addedToCart({
  products: [
    {
      productID: "1",
      name: "MacBook Pro",
      price: 1500000,
      quantity: 3
    },
    {
      productID: "2",
      name: "MacBook Air",
      price: 1500000,
      quantity: 2
    }
  ],
  cartID: "73926365",
  totalValue: 3000000
});

<이벤트 전송 결과 Semantic Attributes>

{
  "products": [
    {
      "quantity": 3,
      "productID": "1",
      "price": 1500000,
      "name": "MacBook Pro",
      "currency": "KRW",
      "position": 1
    },
    {
      "quantity": 2,
      "productID": "2",
      "price": 1500000,
      "name": "MacBook Air",
      "currency": "KRW",
      "position": 2
    }
  ],
  "totalValue": 3000000,
  "cartID": "73926365",
  "totalQuantity": 5
}

👍

환불 및 교환 이벤트의 경우

환불 및 교환 등의 이벤트를 수집 시 products.$0.price 값에 음수를 넣어서 활용 가능합니다.
예를 들어, 고객이 KRW 12,000원의 신발을 구입후 KRW 10,000원의 물건으로 교환 완료 시, 아래 예시처럼 사용할 수 있습니다. 

airbridge.events.send("교환", {
    semanticAttributes: {
        products: [{
            "name": "신발",
            "price": -2000
       }]
    }
})

Custom Attributes

Custom Attributes를 활용하여, Semantic Attributes로 제공되지 않는 속성값들을 자유롭게 정의하여 사용할 수 있습니다. Custom Attributes을 사용하여 이벤트의 Custom 속성값을 매체로 포스트백 전송하거나, Raw Data Export에서 활용할 수 있습니다.

// customAttributes 활용 예
airbridge.events.send("purchase_card", {
  "customAttributes": {
    "userRank": "1",
    "itemType": "sord"
  }
})

#import <AirBridge/ABInAppEvent.h>

ABInAppEvent* event = [[ABInAppEvent alloc] init];

[event setCategory:@"purchase_card"];
NSDictionary* customs = @{
    @"userRank": @"1",
    @"itemType": @"sord"
};
[event setCustoms:customs];
                      
[event send];

let event = ABInAppEvent()

event?.setCategory("purchase_card")

let customs : [String: Any] = [
    "userRank": "1",
    "itemType": "sord"
]
event?.setCustoms(customs)

event?.send()

Map<String, Object> customAttributes = new HashMap<>();
customAttributes.put("userRank", "1");
customAttributes.put("itemType", "sord");

Airbridge.trackEvent(
  "purchase_card", // Category
  null, // Action
  null, // Label
  null, // Value
  customAttributes, // Custom Attributes
  null, // Semantic Attributes
);

Airbridge.trackEvent(
  category = "purchase_card",
  customAttributes = mapOf(
    "userRank" to "1",
    "itemType" to "sord"
  )
)

👍

Custom Attributes 대신 Semantic Attributes 썼을때 장점

  1. Raw Data Export(S3 덤프 포함)에서 이벤트 속성별 컬럼이 제공됩니다. (Search Query, Transaction ID, Product ID 등 개별 속성별 컬럼으로 데이터가 제공되며, Custom Attributes 사용시 JSON String으로 제공됩니다.)

  2. 매체 포스트백 및 서드파티 솔루션 이벤트 전송시, 이벤트 속성이 자동 매핑됩니다. 예를 들어, 사용자 검색 쿼리 값을 받고 있는 매체에서는 에어브릿지와 포스트백 연동시 semanticAttributes.query를 연동해두었기 때문에, Semantic Attributes를 사용하면 광고주 측에서 따로 액션을 취하지 않아도 됩니다.

Updated over 1 year ago