Developer Guide
Getting Started
Event Structure

Event Structure

Last updated February 12, 2024

Event Structure

Event Category（string，必填）：事件名称，所有事件都必须具有Event Category（事件名称）。Airbridge 收集的事件中不存在不具有Event Category（事件名称）的事件。
- Event Action（string，可选）：事件属性 1。
- Event Label（string，可选）：事件属性 2。
Event Value（float，可选）：事件值（numeric）属性。在汇总（aggregation）发生的事件价值时很有用。
Semantic Attributes（map，可选）：Airbridge 中预先定义的事件的键值属性。根据Event Category，有预先定义的Semantic Attributes。请参阅下面的 Semantic Attributes 部分以获取详细说明。
Custom Attributes（map，可选）：可以自由添加并使用的事件的键值属性。请参阅下面的 Custom Attributes 部分以获取详细说明。

有关 Event Category、Action、Label 的验证规范，请查看 FAQ 部分。

在设计Event Taxonomy时，不要过分关注 Category、Action、Label 这些属性名称。
Event Action并不意味着一定要放入表示用户行为的值，Event Label也并不一定要放入类似标签的值。需要记住的是Event Category（事件名称）是必需属性，Action和Label是在Actual Report中更详细地区分事件时使用的属性。如果只想通过Event Category（事件名称）来区分所有事件，那么可以不使用Action和Label。请参考下面的Event Taxonomy示例。

使用Action和Label（而非Custom Attributes）的理由
Event Category, Event Action, Event Label通过索引它们的值来快速提供聚合值的情况下很有用。
如果只存在使用 Raw Data Export 或 S3 Integration 直接解析 JSON String 格式的Custom Attributes来进行数据分析的情况的话，这样做也是可以的。但是，如果您希望在Actual Report中查看聚合值或在 Raw Data Export 中查看按属性分隔的列时，我们建议您使用Action和Label。

Event Taxonomy 示例

不使用Action和Label的示例

Event Category	Event Action	Event Label	Event Value	Sample Code (Web)
purchase_card	-	-	35000	airbridge.events.send("purchase_card", { "value": 35000 })
purchase_cash	-	-	55000	airbridge.events.send("purchase_cash", { "value": 55000 })

使用Action和Label的示例

Event Category	Event Action	Event Label	Event Value	Sample Code (Web)
add_to_wishlist	Shoe	364757-103	35000	airbridge.events.send("add_to_wishlist", { "action": "Nike", "label": "364757-103", "value": 35000 })
add_to_wishlist	Cloth	679421-480	189000	airbridge.events.send("add_to_wishlist", { "action": "Adidas", "label": "679421-480", "value": 189000 })

Semantic Attributes

Semantic Attributes是 Airbridge 系统中预先定义的键值属性。Airbridge 利用Semantic Attributes提供 Raw Data Export 列，或填充媒体的预期参数值以发送回传。至于对应各Event Category的Semantic Attributes，请参考此链接。

Key	Type	Description
totalValue	float	总销售额（总商品价值）
contributionMargin	float	贡献利润销售额
currency	string	货币
totalQuantity	int	总数量
transactionID	string	交易 ID
cartID	string	购物车 ID
productListID	string	商品列表 ID
inAppPurchased	boolean	是否为In-app 购买 true：In-app 购买 false：非 In-app 购买
query	string	用户搜索查询语句
products	array	商品列表
products.$0.productID	string	商品 ID
products.$0.name	string	商品名称
products.$0.price	float	商品价格
products.$0.quantity	int	商品数量
products.$0.currency	string	货币单位
products.$0.position	int	商品位置

12345678910111213141516171819
// Example code for semanticAttributes                     
airbridge.events.send("purchase_card", {
  semanticAttributes: {
    transactionID: '1458132a-0d09-4944-a686-fcbee81b74f7',
    products: [{
      productID: "1234",
      name: "Nike 1",
      price: 55,
      currency: "USD",
      quantity: 1
    }, {
      productID: "1235",
      name: "Nike 2",
      price: 44,
      currency: "USD",
      quantity: 1
    }]
  }
});

12345678910111213141516171819202122232425
#import <AirBridge/ABInAppEvent.h>

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

[event setCategory:@"purchase_card"];

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

[event send];

1234567891011121314151617181920212223
let event = ABInAppEvent()

event?.setCategory("purchase_card")

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

event?.send()

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

Map<String, Object> product2 = new HashMap<>();
product1.put("productID", "1235");
product1.put("name", "Nike 2");
product1.put("price", 44);
product1.put("currency", "USD");
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("product", products);

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

123456789101112131415161718192021222324
Airbridge.trackEvent(
  category = "purchase_card",
  semanticAttributes = mapOf(
    "transactionID" to "1458132a-0d09-4944-a686-fcbee81b74f7",
    "products" to mapOf(
      "product" to listOf(
        mapOf(
          "productID" to "1234",
          "name" to "Nike 1",
          "price" to 55,
          "currency" to "USD",
          "quantity" to 1
        ),
        mapOf(
          "productID" to "1235",
          "name" to "Nike 2",
          "price" to 44,
          "currency" to "USD",
          "quantity" to 1
        )
      )
    )
  )
)

semanticAttributes.totalQuantity 在通过 SDK 或 API 等收集事件时，即使不提供，只要products 列表中的 quantity（semanticAttributes.products.$.quantity）存在，那么这些值的总和会自动进入并提供给 Raw Data Export。
＜事件发送示例＞

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

＜事件发送结果 Semantic Attributes＞

12345678910111213141516171819202122
{
  "totalQuantity": 5,   // Total quantity of items are automatically summed
  "cartID": "73926365",
  "products": [
    {
      "quantity": 3,
      "productID": "1",
      "price": 1500,
      "name": "MacBook Pro",
      "currency": "USD",
      "position": 1
    },
    {
      "quantity": 2,
      "productID": "2",
      "price": 1500,
      "name": "MacBook Air",
      "currency": "USD",
      "position": 2
    }
  ]
}

退款和换货事件相关说明

在收集退款和换货等事件时，可以将负数放入 products.$0.price 值中进行使用。例如，客户购买了12,000韩元的鞋子，然后用10,000韩元的物品进行了交换，此时可以按照以下示例使用。

12345678
airbridge.events.send("exchange", {
    semanticAttributes: {
        products: [{
            "name": "shoe",
            "price": -2000
       }]
    }
})

Custom Attributes

通过使用Custom Attributes，您可以自由定义和使用未在Semantic Attributes中提供的属性值。您可以使用Custom Attributes将事件的自定义属性值发送给媒体回传或在 Raw Data Export 中使用。

1234567
//Example code for customAttributes
airbridge.events.send("purchase_card", {
  "customAttributes": {
    "userRank": "1",
    "itemType": "sword"
  }
})

123456789101112
#import <AirBridge/ABInAppEvent.h>

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

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

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

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

使用Semantic Attributes而非Custom Attributes的优点
在 Raw Data Export（包括 S3 Dump）中提供事件属性列。（Search Query、Transaction ID、Product ID 等各个属性以各别列的形式提供数据，而使用Custom Attributes时以 JSON String 形式提供。）
在媒体回传和第三方解决方案事件传输时，事件属性会自动映射。例如，接收用户搜索查询语句值的媒体在与Airbridge集成回传时，已经设置了 semanticAttributes.query接入，因此在使用Semantic Attributes时，广告主不需要进行任何额外操作。

Was this page helpful?

Have any questions or suggestions?

Event Structureself.__wrap_n!=1&&self.__wrap_b(":R96fnkv79uuba:",0.5)

Event Structure

在设计Event Taxonomy时，不要过分关注 Category、Action、Label 这些属性名称。

使用Action和Label（而非Custom Attributes）的理由

Event Taxonomy 示例

不使用Action和Label的示例

使用Action和Label的示例

Semantic Attributes

退款和换货事件相关说明

Custom Attributes

使用Semantic Attributes而非Custom Attributes的优点

Event Structure