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

    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

    1234567891011121314151617181920
    // 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
        }]
      }
    });

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

    123456789101112131415161718
    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
    });

    <Example of sent results using "Semantic Attributes">

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

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

    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?