Event Structure

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

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

Nike

364757-103

35

airbridge.events.send("add_to_wishlist", {
   "action": "Nike",
   "label": "364757-103",
   "value": 35000
})

add_to_wishlist

Adidas

679421-480

189

airbridge.events.send("add_to_wishlist", {
   "action": "Adidas",
   "label": "679421-480",
   "value": 189000
})
18501850

Example of an Actuals Report using Event Action and Event Label



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

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

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

[event setCategory:@"purchase_card"];

NSDictionary* semantics = @{
    @"transactionID": @"1458132a-0d09-4944-a686-fcbee81b74f7",
    @"totalValue": @99,
    @"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];
let event = ABInAppEvent()

event?.setCategory("purchase_card")

let semantics: [String: Any] = [
    "transactionID": "1458132a-0d09-4944-a686-fcbee81b74f7",
    "totalValue": 99,
    "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()
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("totalValue", 99);
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 99,
    "products" to mapOf(
      "totalValue" to 99,
      "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".

<Example of sending an event using "Semantic Attributes">

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

<Example of sent results using "Semantic Attributes">

{
  "totalValue": 7500,
  "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.

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



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".

//Example code for customAttributes
airbridge.events.send("purchase_card", {
  "customAttributes": {
    "userRank": "1",
    "itemType": "sword"
  }
})
#import <AirBridge/ABInAppEvent.h>

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

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

event?.setCategory("purchase_card")

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

event?.send()
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
);
Airbridge.trackEvent(
  category = "purchase_card",
  customAttributes = mapOf(
    "userRank" to "1",
    "itemType" to "sword"
  )
)

👍

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.