Server-to-Server Event

    Send In-App/In-Web events in a server-to-server method.


    Send In-app Events

    POST

    https://api.airbridge.io/events/v1/apps/{app_name}/mobile-app/9360

    Send In-App events in a server-to-server method.

    rate limit : 1000 requests per minute.

    User Identifiers

    Attention

    It is recommended to send all available user identifiers as they are crucial for accurate attribution, postback, cohort analysis etc.

    1. Device ID

    Device IDs can be retrieved through the SDK (refer to the data fetching guide).
    Available Device IDs per operating system are as follows:

    123456789101112131415161718
    {
        ... 
    
        "device": {
            "deviceUUID": "542177F1-5C23-438B-8088-82D34C94F6D7",
            "ifa": "542177F1-5C23-438B-8088-82D34C94F6D7",
            "ifv": "37EEC3E0-BF15-412E-ADBA-7D2E82E7A75F",
            "osName": "iOS",
            "osVersion": "18.0.1"
        },
        "user": {
            "externalUserID": "19443",
            "externalUserEmail": "example@ab180.co",
            "externalUserPhone": "821012341234"
        }
    
        ...
    }
    123456789101112131415161718
    {
        ...
    
        "device": {
            "deviceUUID": "2dfca632-86f3-4d22-9746-cdfe7985c471",
            "gaid": "2dfca632-86f3-4d22-9746-cdfe7985c471",
            "appSetID": "7c4681ef-97c6-4ebd-9c04-e22f584b3746",
            "osName": "Android",
            "osVersion": "5.0.2"
        },
        "user": {
            "externalUserID": "19443",
            "externalUserEmail": "example@ab180.co",
            "externalUserPhone": "821012341234"
        }
    
        ...
    }

    2. User ID(user.externalUserID)

    User IDs may be sent without Device IDs if data fetching is inconvenient.
    In such cases, Airbridge processes events based on the Device IDs mapped to the provided User ID.
    However if no mapping is found, this may lower the accuracy of reports.

    123456789101112
    {
        ...
        
        "user": {
            "externalUserID": "19443",
            "externalUserEmail": "example@ab180.co",
            "externalUserPhone": "821012341234"
        }
    
        ...
    }
    

    Example Payloads

    123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263
    {
        "eventUUID": "9b4b3e4e-2162-4ae6-8986-91ee84644262",
        "user": {
            "externalUserID": "19443",
            "externalUserEmail": "example@ab180.co",
            "externalUserPhone": "821012341234"
        },
        "device": {
            "deviceUUID": "2dfca632-86f3-4d22-9746-cdfe7985c471",
            "gaid": "2dfca632-86f3-4d22-9746-cdfe7985c471",
            "appSetID": "7c4681ef-97c6-4ebd-9c04-e22f584b3746",
            "deviceModel": "SM-0000",
            "manufacturer": "Samsung",
            "osName": "Android",
            "osVersion": "5.0.2",
            "locale": "ko-KR",
            "timezone": "Asia/Seoul",
            "orientation": "portrait",
            "screen": {
                "width": 123
            },
            "location": {
                "latitude": 120.103,
                "speed": "12"
            },
            "network": {
                "carrier": "SKTelecom",
                "cellular": true,
                "wifi": true
            }
        },
        "app": {
            "packageName": "com.ab180.co",
            "version": "1.2.3"
        },
        "eventData": {
            "goal": {
                "category": "airbridge.ecommerce.order.completed",
                "value": 159990,
                "semanticAttributes": {
                    "action": "christmas purchase",
                    "label": "chrismas sale",
                    "transactionID": "12939172",
                    "inAppPurchased": true,
                    "currency": "KRW",
                    "products": [
                        {
                            "quantity": 1,
                            "productID": "CH129",
                            "position": 0,
                            "name": "timeless trench coat",
                            "currency": "KRW",
                            "price": 159990
                        }
                    ]
                },
                "customAttributes": {
                    "season": "chirstmas",
                    "gift": true
                }
            }
        }
    }

    Request

    Headers

    Accept-Language
    string

    You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

    Content-Type
    string

    Represents the media type of the resource. Defaults to application/json.

    Authorization
    string

    The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

    X-Forwarded-For
    Requiredstring

    You can send the user's IP in the X-Forwarded-For header. Without X-Forwarded-For, user behavior is logged with the IP of the server that requested the Server To Server API, not the user's IP (client request IP).

    We accept values in the form of ipv4 (123.123.123.123), ipv6 (2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d).

    Path Params

    app_name
    Requiredstring

    Airbridge App Name. (Unique ID)

    Body Params

    eventUUID
    string

    Random UUID v4 string.

    Accepts a random string in UUID4 format.

    The event uuid is used for duplication as a unique ID for the event, and will be generated automatically by the event api if not provided.

    eventTimestamp
    number

    The time the event occurred. (default: current timestamp)

    A Unix timestamp in milliseconds (13 digits in Unixtime).

    If the eventTimestamp is older than 24 hours from the time the event was sent, it will not be processed by the server.

    user
    object

    User information.

    user.externalUserID
    Conditionally Requiredstring

    User ID.

    *required if device.deviceUUID is not sent.

    user.externalUserEmail
    string

    User email.

    user.externalUserPhone
    string

    User phone number.

    user.attributes
    object

    Custom user attributes.

    Accepts data in JSON format.

    { "age_group": "30", "brand": "Nike" }

    device
    Conditionally Requiredobject

    Device Information.

    *required if user.ExternalUserID is not sent

    device.deviceUUID
    Conditionally Requiredstringnullable

    Airbridge Device ID.

    Accepts GAID, IDFA, IDFV, Randomly Generated UUID, or AppSetId.

    *required if user.ExternalUserID is not sent

    device.gaid
    stringnullable
    device.ifa
    stringnullable
    device.appSetID
    stringnullable

    AppSetId provided by Google.

    device.ifv
    stringnullable
    device.limitAdTracking
    boolean

    The limit ad tracking setting configured on the Android devices. This value must be collected from the Airbridge SDK, and defaults to true if absent. When set to true, the amount of information shared with integrated ad channels via postback may be limited.

    device.deviceModel
    stringnullable

    Device model name Android iOS

    device.appTrackingTransparency
    integer

    App Tracking Transparency

    device.deviceIdentifier
    string

    A specific device identifier, such as iPhone11,2 (iPhone only).

    device.manufacturer
    string

    Device manufacturer Android iOS

    device.osName
    Conditionally Requiredenum

    Device OS name. (e.g. "Android", "iOS") (Case sensitive)

    *required if device.deviceUUID is sent.

    ENUM VALUES
    Android

    Android OS

    iOS

    iOS

    device.osVersion
    Conditionally Requiredstring

    Device OS version Android iOS

    *required if device.deviceUUID is sent.

    device.locale
    string

    Device Locale in BCP 47 language tag format. (eg. ko-KR, en-US, ja-JP)

    Airbridge recognizes the country and language of the event based on this field.

    device.timezone
    string

    Device Timezone. Use a Timezone Name defined by the IANA Database. (eg. Asia/Seoul, America/Los_Angeles, Asia/Tokyo)

    device.orientation
    string

    Device orientation Android iOS

    device.screen
    string

    Device screen information.

    device.screen.density
    string

    Device screen density Android iOS

    device.screen.height
    number

    Device screen height Android iOS

    device.screen.width
    number

    Device screen width Android iOS

    device.alias
    object

    You can share the user consent necessary to comply with the Digital Markets Act (DMA) with Airbridge. For detailed information about the DMA, refer to this article.

    device.alias.eea
    string

    Indicates whether the user is in the EEA and the DMA applies. Values other than "0" and "1" will not be processed. The value is neither a direct response from the user nor automatically filled in by Airbridge. Determine the appropriate value based on whether the user is in the EEA and the DMA applies.

    If 0, it is advised not to share the other field values with Airbridge.

    • 0: The user is in the EEA, and DMA does not apply

    • 1: The user is in the EEA, and DMA does apply

    device.alias.adPersonalization
    string

    Indicates whether the user gave Google consent to use their data for ad personalization. Values other than "0" and "1" will not be processed.

    • 0: The user did not give consent

    • 1: The user gave consent

    device.alias.adUserData
    string

    Indicates whether the user gave consent to send their data to Google for ad-related purposes. Values other than "0" and "1" will not be processed.

    • 0: The user did not give consent

    • 1: The user gave consent

    app
    Requiredobject

    User app information.

    app.packageName
    Requiredstring

    The package name of the app registered on Google Play Store or Apple App Store. (Android: Package Name, iOS: Bundle ID)

    app.version
    string

    Version of the app. Android iOS

    eventData
    Requiredobject

    Event information.

    eventData.goal
    Requiredobject

    An object that can contain information about an event. It can contain categories, actions, labels, values, and semantic attributes. (Related Guide)

    eventData.goal.category
    Requiredstring
    eventData.goal.value
    number

    Event's value.

    This may represent the product value of purchase events, or revenue for ad impressions etc.

    eventData.goal.customAttributes
    object

    Custom event attribute.

    { "color": "red" }

    eventData.goal.semanticAttributes
    object

    Semantic Attributes. Predefined attributes for which Airbridge is supposed to collect data.

    eventData.goal.semanticAttributes.currency
    string

    The currency for the payment event. You can use the currency used for the actual payment, as it will be converted to the currency set in your dashboard during event processing.

    eventData.goal.semanticAttributes.action
    string

    Airbridge event property 1

    eventData.goal.semanticAttributes.label
    string

    Airbridge event property 2

    eventData.goal.semanticAttributes.productListID
    string

    Product list ID.

    eventData.goal.semanticAttributes.cartID
    string

    Cart ID.

    eventData.goal.semanticAttributes.transactionID
    string

    Transaction ID.

    eventData.goal.semanticAttributes.inAppPurchased
    boolean

    In-app purchases or not.

    true for in-app purchase, false for not an in-app purchase.

    eventData.goal.semanticAttributes.products
    object[]

    Product list.

    eventData.goal.semanticAttributes.products[0].currency
    string

    Currency.

    eventData.goal.semanticAttributes.products[0].productID
    string

    Product ID.

    eventData.goal.semanticAttributes.products[0].price
    number

    Product Price.

    eventData.goal.semanticAttributes.products[0].name
    string

    Product name.

    eventData.goal.semanticAttributes.products[0].position
    string

    Product position.

    eventData.goal.semanticAttributes.products[0].quantity
    integer

    Product quantity.

    Request
    123456
    curl -X POST 'https://api.airbridge.io/events/v1/apps/{app_name}/mobile-app/9360' \
      -H 'Accept-Language: ko' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \
      -H 'X-Forwarded-For: 2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d' \
      -d '{"eventUUID":"9b4b3e4e-2162-4ae6-8986-91ee84644262","user":{"externalUserID":"19443","externalUserEmail":"example@ab180.co","externalUserPhone":"821012341234"},"device":{"deviceUUID":"2dfca632-86f3-4d22-9746-cdfe7985c471","gaid":"2dfca632-86f3-4d22-9746-cdfe7985c471","ifa":"542177F1-5C23-438B-8088-82D34C94F6D7","appSetID":"7c4681ef-97c6-4ebd-9c04-e22f584b3746","ifv":"37EEC3E0-BF15-412E-ADBA-7D2E82E7A75F","limitAdTracking":true,"deviceModel":"LG-H542","appTrackingTransparency":0,"deviceIdentifier":"iPhone11,2","manufacturer":"Samsung","osName":"Android","osVersion":"5.0.2","locale":"ko-KR","timezone":"Asia/Seoul","orientation":"portrait","screen":{"width":123}},"app":{"packageName":"com.ab180.co","version":"1.2.3"},"eventData":{"goal":{"category":"airbridge.ecommerce.product.addedToCart","value":159990,"semanticAttributes":{"currency":"KRW","action":"shoes","label":"nike","transactionID":"12939172","inAppPurchased":true,"products":[{"currency":"KRW","productID":"30372425","price":10990,"name":"나이키 커스텀","position":"1","quantity":1}]}}}}'
    Payload
    12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455
    {
      "eventUUID": "9b4b3e4e-2162-4ae6-8986-91ee84644262",
      "user": {
        "externalUserID": "19443",
        "externalUserEmail": "example@ab180.co",
        "externalUserPhone": "821012341234"
      },
      "device": {
        "deviceUUID": "2dfca632-86f3-4d22-9746-cdfe7985c471",
        "gaid": "2dfca632-86f3-4d22-9746-cdfe7985c471",
        "ifa": "542177F1-5C23-438B-8088-82D34C94F6D7",
        "appSetID": "7c4681ef-97c6-4ebd-9c04-e22f584b3746",
        "ifv": "37EEC3E0-BF15-412E-ADBA-7D2E82E7A75F",
        "limitAdTracking": true,
        "deviceModel": "LG-H542",
        "appTrackingTransparency": 0,
        "deviceIdentifier": "iPhone11,2",
        "manufacturer": "Samsung",
        "osName": "Android",
        "osVersion": "5.0.2",
        "locale": "ko-KR",
        "timezone": "Asia/Seoul",
        "orientation": "portrait",
        "screen": {
          "width": 123
        }
      },
      "app": {
        "packageName": "com.ab180.co",
        "version": "1.2.3"
      },
      "eventData": {
        "goal": {
          "category": "airbridge.ecommerce.product.addedToCart",
          "value": 159990,
          "semanticAttributes": {
            "currency": "KRW",
            "action": "shoes",
            "label": "nike",
            "transactionID": "12939172",
            "inAppPurchased": true,
            "products": [
              {
                "currency": "KRW",
                "productID": "30372425",
                "price": 10990,
                "name": "나이키 커스텀",
                "position": "1",
                "quantity": 1
              }
            ]
          }
        }
      }
    }

    Response

    200SUCCESS

    400ERROR

    Invalid requests (timestamp, sdk signature, app name, etc.).

    401ERROR

    When using an invalid authentication token.

    Response
    1234
    {
      "at": "2020-02-06 16:06:49",
      "data": "Event(9360) is successfully proccessed."
    }
    Response
    12345
    {
      "at": "2020-02-06 16:06:49",
      "error": "invalid_request",
      "ingested": 0
    }
    Response
    12345
    {
      "at": "2020-02-06 16:06:49",
      "error": "unauthorized",
      "ingested": 0
    }

    Send In-web Events

    POST

    https://api.airbridge.io/events/v1/apps/{app_name}/web/9320

    Send In-Web events in a server-to-server method.

    rate limit : 1000 requests per minute.

    User Identifiers

    Attention

    It is recommended to send all available user identifiers as they are crucial for accurate attribution, postback, cohort analysis etc.

    Cookie IDs can be retrieved through the SDK(refer to the data fetching guide).
    The following attribution data must be sent along with the Cookie ID for proper attribution.

    12345678910111213141516171819202122232425262728
    {
      ...
    
      "browser": {
        "clientID": "05609013-bb5a-4594-bbc3-832cb1b87072"
      },
      "eventData": {
        "shortID": "aef04",
        "trackingData": {
          "channel": "blog",
          "params": {
            "ad_creative": "ad_creative",
            "ad_group": "ad_group",
            "campaign": "ad_campaign",
            "content": "ad_content",
            "medium": "ad_medium",
            "tracking_template_id": "ad_tracking_template_id"
          }
        }
      },
      "user": {
        "externalUserID": "19443",
        "externalUserEmail": "example@ab180.co",
        "externalUserPhone": "821012341234"
      }
      
      ...
    }

    2. User ID(user.externalUserID)

    User IDs may be sent without Cookie IDs if data fetching is inconvenient.
    In such cases, Airbridge processes events based on the Cookie IDs mapped to the provided User ID.
    However, if no mapping is found, this may lower the accuracy of reports.

    123456789101112
    {
        ...
        
        "user": {
            "externalUserID": "19443",
            "externalUserEmail": "example@ab180.co",
            "externalUserPhone": "821012341234"
        }
    
        ...
    }
    

    Request

    Headers

    Accept-Language
    string

    You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.

    Content-Type
    string

    Represents the media type of the resource. Defaults to application/json.

    Authorization
    string

    The key value to use for API requests. Instructions for getting API keys are in "how to generate API Keys".

    X-Forwarded-For
    Requiredstring

    You can send the user's IP in the X-Forwarded-For header. Without X-Forwarded-For, user behavior is logged with the IP of the server that requested the Server To Server API, not the user's IP (client request IP).

    We accept values in the form of ipv4 (123.123.123.123), ipv6 (2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d).

    Path Params

    app_name
    Requiredstring

    Airbridge App Name. (Unique ID)

    Body Params

    eventUUID
    string

    Random UUID v4 string.

    Accepts a random string in UUID4 format.

    The event uuid is used for duplication as a unique ID for the event, and will be generated automatically by the event api if not provided.

    eventTimestamp
    number

    The time the event occurred. (default: current timestamp)

    A Unix timestamp in milliseconds (13 digits in Unixtime).

    If the eventTimestamp is older than 24 hours from the time the event was sent, it will not be processed by the server.

    user
    object

    User information.

    user.externalUserID
    Conditionally Requiredstring

    User ID.

    *required if device.deviceUUID is not sent.

    user.externalUserEmail
    string

    User email.

    user.externalUserPhone
    string

    User phone number.

    user.attributes
    object

    Custom user attributes.

    Accepts data in JSON format.

    { "age_group": "30", "brand": "Nike" }

    browser
    object

    Browser Information.

    browser.clientID
    Requiredstring

    Browser cookie ID. The values fetched from the SDK are required. [Docs]

    If data fetching is not an option, sending the User ID(user.externalUserID) will make this field optional.

    browser.userAgent
    string

    Browser's user agent.

    eventData
    Requiredobject

    Event information.

    eventData.shortID
    Requiredstring

    Attribution campaign parameter Short ID. Provide the value fetched from the Airbridge SDK(Android iOS).

    NOTE: This value must be sent to the Airbridge server without processing or filtering.

    If data fetching is not an option, sending the User ID(user.externalUserID) will make this field optional.

    eventData.trackingData
    Requiredobject

    Tracking data from SDK.

    eventData.trackingData.channel
    Requiredstring

    Attribution campaign channel. Provide the value fetched from the Airbridge SDK(Android iOS).

    NOTE: This value must be sent to the Airbridge server without processing or filtering. (eg. values such as airbridge.websdk must also be sent)

    If data fetching is not an option, sending the User ID(user.externalUserID) will make this field optional.

    eventData.trackingData.params
    Requiredobject

    Attribution campaign parameters. Accepts data in JSON format.

    Provide the value fetched from the Airbridge SDK(Android iOS).

    NOTE: This value must be sent to the Airbridge server without processing or filtering.

    If data fetching is not an option, sending the User ID(user.externalUserID) will make this field optional.

    eventData.goal
    Requiredobject

    An object that can contain information about an event. It can contain categories, actions, labels, values, and semantic attributes. (Related Guide)

    eventData.goal.category
    Requiredstring
    eventData.goal.value
    number

    Event's value.

    This may represent the product value of purchase events, or revenue for ad impressions etc.

    eventData.goal.customAttributes
    object

    Custom event attribute.

    { "color": "red" }

    eventData.goal.semanticAttributes
    object

    Semantic Attributes. Predefined attributes for which Airbridge is supposed to collect data.

    eventData.goal.semanticAttributes.action
    string

    Airbridge event property 1

    eventData.goal.semanticAttributes.label
    string

    Airbridge event property 2

    eventData.goal.semanticAttributes.query
    string

    User search query.

    eventData.goal.semanticAttributes.productListID
    string

    Product list ID.

    eventData.goal.semanticAttributes.cartID
    string

    Cart ID.

    eventData.goal.semanticAttributes.transactionID
    string

    Transaction ID.

    eventData.goal.semanticAttributes.inAppPurchased
    boolean

    In-app purchases or not.

    true for in-app purchase, false for not an in-app purchase.

    eventData.goal.semanticAttributes.currency
    string

    The currency for the payment event. You can use the currency used for the actual payment, as it will be converted to the currency set in your dashboard during event processing.

    eventData.goal.semanticAttributes.products
    object[]

    Product list.

    eventData.goal.semanticAttributes.products[0].position
    string

    Product position.

    eventData.goal.semanticAttributes.products[0].productID
    string

    Product ID.

    eventData.goal.semanticAttributes.products[0].name
    string

    Product name.

    eventData.goal.semanticAttributes.products[0].price
    number

    Product Price.

    eventData.goal.semanticAttributes.products[0].quantity
    integer

    Product quantity.

    eventData.goal.semanticAttributes.products[0].currency
    string

    Currency.

    Request
    123456
    curl -X POST 'https://api.airbridge.io/events/v1/apps/{app_name}/web/9320' \
      -H 'Accept-Language: ko' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \
      -H 'X-Forwarded-For: 2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d' \
      -d '{"eventUUID":"9b4b3e4e-2162-4ae6-8986-91ee84644262","user":{"externalUserID":"19443","externalUserEmail":"example@ab180.co","externalUserPhone":"821012341234"},"browser":{"clientID":"05609013-bb5a-4594-bbc3-832cb1b87072","userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302"},"eventData":{"shortID":"aef04","trackingData":{"channel":"blog"},"goal":{"category":"airbridge.ecommerce.product.addedToCart","value":159990,"semanticAttributes":{"action":"shoes","label":"nike","query":"나이키","transactionID":"12939172","inAppPurchased":true,"currency":"KRW","products":[{"position":"1","productID":"30372425","name":"나이키 커스텀","price":10990,"quantity":1,"currency":"KRW"}]}}}}'
    Payload
    12345678910111213141516171819202122232425262728293031323334353637383940
    {
      "eventUUID": "9b4b3e4e-2162-4ae6-8986-91ee84644262",
      "user": {
        "externalUserID": "19443",
        "externalUserEmail": "example@ab180.co",
        "externalUserPhone": "821012341234"
      },
      "browser": {
        "clientID": "05609013-bb5a-4594-bbc3-832cb1b87072",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302"
      },
      "eventData": {
        "shortID": "aef04",
        "trackingData": {
          "channel": "blog"
        },
        "goal": {
          "category": "airbridge.ecommerce.product.addedToCart",
          "value": 159990,
          "semanticAttributes": {
            "action": "shoes",
            "label": "nike",
            "query": "나이키",
            "transactionID": "12939172",
            "inAppPurchased": true,
            "currency": "KRW",
            "products": [
              {
                "position": "1",
                "productID": "30372425",
                "name": "나이키 커스텀",
                "price": 10990,
                "quantity": 1,
                "currency": "KRW"
              }
            ]
          }
        }
      }
    }

    Response

    200SUCCESS

    400ERROR

    Invalid requests (timestamp, sdk signature, app name, etc.).

    401ERROR

    When using an invalid authentication token.

    Response
    1234
    {
      "at": "2020-02-06 16:06:49",
      "data": "Event(9320) is successfully proccessed."
    }
    Response
    12345
    {
      "at": "2020-02-06 16:06:49",
      "error": "invalid_request",
      "ingested": 0
    }
    Response
    12345
    {
      "at": "2020-02-06 16:06:49",
      "error": "unauthorized",
      "ingested": 0
    }