Developer Guide
Getting Started
Event Structure

Event Structure

Last updated June 27, 2024

Event Structure

Event Category (string, required): It is the name of the event, and all events collected by Airbridge will have an "Event Category". Events without an "Event Category" will not be collected by Airbridge.
- Event Action (string, optional): Event property 1.
- Event Label (string, optional): Event property 2.
Event Value (float, optional): A numeric value that is useful when aggregating the worth of an event.
Semantic Attributes (map, optional): Pre-defined key-value pairs by Airbridge. There are set Semantic Attributes depending on the "Event Category". Please refer to Semantic Attributes below for more information.
Custom Attributes (map, optional): User-defined key-value pairs for an event. Please refer to Custom Attributes below for more information.

Please refer to FAQ for more information on the validation specifications for "Event Category", Action and Label.

You can be flexible when using Event Category, Action, Label properties when designing your Event Taxonomy.
"Event Action" does not require a value that reflects an user action, nor does "Event Label" require a value that labels the event. Please note that "Event Category" is the only part that is mandatory, and "Event Action" and "Event Label" is used to filter events for the "Actuals Report". If you wish to filter your events by using "Event Category" only, you do not have to use "Event Action" or "Event Label". Please see the below example of an event taxonomy.

Why use "Action" and "Label" instead of Custom Attributes
"Event Category", "Event Action" and "Event Label" values will be indexed accordingly, allowing for faster aggregation of data.
If you only want to parse custom attributes in JSON string format by extracting data from "Raw Data Exports" or S3 Integrations, using custom attributes should not be a problem. However, if you want to see aggregation data in the "Actuals Report" or see property defined columns in your "Raw Data Export", we recommend you to use "Event Action" and "Event Label".

Event Taxonomy Examples

Example of "Event Action", "Event Label" not being used

Event Category	Event Action	Event Label	Event Value	Sample Code (Web)
purhcase_card	-	-	35	`airbridge.events.send("purchase_card", { "value": 35 })`
purchase_cash	-	-	55	`airbridge.events.send("purchase_cash", { "value": 55 })`

Example of an Actuals Report not using Event Action and Event Label

Example of "Event Action" and "Event Label" being used

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

Semantic Attributes

Semantic Attributes are key-value paired properties pre-defined by Airbridge. Airbridge uses "Semantic Attributes" for "Raw Data Export" columns, or to fill in parameters when sending postbacks to media channels. Please refer to this sheet for details on "Semantic Attributes" per "Event Category".

Key	Type	Description
totalValue	float	Total revenue (Total worth of products)
currency	string	Currency
totalQuantity	int	Total quantity
transactionID	string	ID of transaction
cartID	string	ID of cart
productListID	string	ID of product list
inAppPurchased	boolean	true: In-app purchase false: Not an in-app purchase
query	string	Query used to search
products	array	Product list
products.$0.productID	string	ID of product
products.$0.name	string	Name of product
products.$0.price	float	Price of product
products.$0.quantity	int	Quantity of product
products.$0.currency	string	Currency
products.$0.position	int	Location of product

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

You do not have to send semanticAttributes.totalQuantity through the SDK or API if semanticAttributes.products.$.quantity is being sent. Airbridge will calculate and provide the total quantity in the "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"
});

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
    }
  ]
}

For refund and exchange events

When collecting refund and exchange events, you can use negative numbers for products.$0.price.
For example, if a customer bought a 120 USD shoe, and then exchanges for something else worth 100 USD, you can use the below example.

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

Custom Attributes

"Custom Attributes" can be used to define properties not provided by "Semantic Attributes".
Please note that the values for "Custom Attributes" can not be used as postbacks to media channels or in "Raw Data Exports".

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];

1234567891011
let event = ABInAppEvent()

event?.setCategory("purchase_card")

let customs : [String: Any] = [
    "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
);

Advantages when using "Semantic Attributes" over "Custom Attributes"
1. Columns are created per event when using "Raw Data Export" or S3 dumps. ("Search Query", "Transaction ID", "Product ID" and other columns will be created, while JSON strings will be provide when using "Custom Attributes")
2. Event properties are automatically mapped when sending postbacks to media channels or third party solutions. For example, postbacks for user search queries are configured to automatically be recognized by the media channels when using semanticAttributes.query.

Was this page helpful?

Have any questions or suggestions?

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

Event Structure

You can be flexible when using Event Category, Action, Label properties when designing your Event Taxonomy.

Why use "Action" and "Label" instead of Custom Attributes

Event Taxonomy Examples

Example of "Event Action", "Event Label" not being used

Example of "Event Action" and "Event Label" being used

Semantic Attributes

For refund and exchange events

Custom Attributes

Advantages when using "Semantic Attributes" over "Custom Attributes"

Event Structure