> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send In-app Events

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

rate limit : 1000 requests per minute.

<h3 id="user-identifiers">
  User Identifiers
</h3>

<div id="attention" />

<Danger>
  **Attention**

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

<h4 id="a-1-device-id">
  **1. Device ID**
</h4>

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

| Request Body Key  | Data Fetching Field          | Operating System |
| ----------------- | ---------------------------- | ---------------- |
| device.deviceUUID | Airbridge Device ID          | All              |
| device.gaid       | GAID (Google Advertising ID) | Android          |
| device.appSetID   | App Set ID                   | Android          |
| device.ifa        | IDFA                         | iOS, iPadOS      |
| device.ifv        | IDFV                         | iOS, iPadOS      |

<Accordion title="Request Example">
  <CodeGroup>
    ```json iOS lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    {
        ... 

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

        ...
    }
    ```

    ```json Android lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    {
        ...

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

        ...
    }
    ```
  </CodeGroup>
</Accordion>

<h4 id="a-2-user-id-user-externaluserid">
  **2. User ID(`user.externalUserID`)**
</h4>

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.

<Accordion title="Request Example">
  ```json lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
      ...
      
      "user": {
          "externalUserID": "19443",
          "externalUserEmail": "example@ab180.co",
          "externalUserPhone": "821012341234"
      }

      ...
  }

  ```
</Accordion>

<h3 id="precautions-for-ad-channel-integration">
  Precautions for Ad Channel Integration
</h3>

<div id="fields-needed-for-ad-optimization" />

<Note>
  **Fields needed for Ad Optimization**

  When using channel integration, the event information can also be used for ad optimizations.
  Due to this, it is strongly recommended to send all available event information through the API.
  The fields below are generally used for optimization:

  * app.packageName
  * device.osName
  * device.osVersion
  * device.appTrackingTransparency
  * device.limitAdTracking
</Note>

<h3 id="example-payloads">
  Example Payloads
</h3>

<Accordion title="Product Purchase">
  ```json lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
      "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
              }
          }
      }
  }
  ```
</Accordion>

<Card title="Try API Request" icon="rectangle-api" horizontal href="https://www.postman.com/airbridge-engineering/workspace/airbridge-api/request/22395869-0fde7701-9f8c-42bd-a7a2-d25cd4bef2ec" />

```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
https://api.airbridge.io/events/v2/apps/{app_name}/mobile-app/9360
```

<h2 id="send-in-app-events-request">
  Request
</h2>

***

<h3 id="send-in-app-events-headers">
  Headers
</h3>

<ParamField header="Accept-Language" type="string">
  You can specify the language to use for API requests and responses. It follows the ISO-639-1 format.
</ParamField>

<ParamField header="Content-Type" type="string">
  Represents the media type of the resource. Defaults to `application/json`.
</ParamField>

<ParamField header="Authorization" type="string">
  The key value to use for API requests. Instructions for getting API keys are in "[how to generate API Keys](/en/references/introduction#authorization)".
</ParamField>

<ParamField header="X-Forwarded-For" type="string" required>
  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`).
</ParamField>

<ParamField header="x-airbridge-use-client-ip" type="number">
  Can use `device.clientIP` to decide user's IP when can't send device IP at `X-Forwarded-For.`

  Required when: When device.clientIP is configured at Request Body
</ParamField>

<h3 id="send-in-app-events-path-params">
  Path Params
</h3>

<ParamField path="app_name" type="string" required>
  Airbridge App Name. (Unique ID)
</ParamField>

<h3 id="send-in-app-events-body-params">
  Body Params
</h3>

<ParamField body="eventUUID" type="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.
</ParamField>

<ParamField body="eventTimestamp" type="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.**
</ParamField>

<ParamField body="user" type="object">
  User information.

  <Expandable title="child attributes">
    <ParamField body="user.externalUserID" type="string">
      User ID.

      Required when: required if device.deviceUUID is not sent.
    </ParamField>

    <ParamField body="user.externalUserEmail" type="string">
      User email.
    </ParamField>

    <ParamField body="user.externalUserPhone" type="string">
      User phone number.
    </ParamField>

    <ParamField body="user.attributes" type="object">
      Custom user attributes.

      Accepts data in JSON format.

      `{ "age_group": "30", "brand": "Nike" }`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="device" type="object">
  Device Information.

  Required when: required if user.ExternalUserID is not sent

  <Expandable title="child attributes">
    <ParamField body="device.deviceUUID" type="string">
      Airbridge Device ID.

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

      Required when: required if user.ExternalUserID is not sent
    </ParamField>

    <ParamField body="device.gaid" type="string">
      [Advertising ID provided by Google](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#gaid-google-advertising-id)
    </ParamField>

    <ParamField body="device.ifa" type="string">
      [Advertising ID provided by Apple](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#idfa)
    </ParamField>

    <ParamField body="device.appSetID" type="string">
      AppSetId provided by Google.
    </ParamField>

    <ParamField body="device.ifv" type="string">
      [Device ID provided by Apple](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#idfv)
    </ParamField>

    <ParamField body="device.clientIP" type="string">
      Required when User's Device IP can't be passed via X-Forwarded-For Request Header. Make sure to include `x-airbridge-use-client-ip: 1` at Request Header.

      Required when: Required when User's Device IP can't be passed via X-Forwarded-For Request Header
    </ParamField>

    <ParamField body="device.limitAdTracking" type="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.
    </ParamField>

    <ParamField body="device.deviceModel" type="string">
      Device model name [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#device-model) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#device-model)
    </ParamField>

    <ParamField body="device.appTrackingTransparency" type="integer">
      App Tracking Transparency

      | Value | ATT Status     |
      | ----- | -------------- |
      | 0     | Not Determined |
      | 1     | Restricted     |
      | 2     | Denied         |
      | 3     | Authorized     |
    </ParamField>

    <ParamField body="device.deviceIdentifier" type="string">
      A specific device identifier, such as iPhone11,2 (iPhone only).
    </ParamField>

    <ParamField body="device.manufacturer" type="string">
      Device manufacturer [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#device-manufacturer) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#device-manufacturer)
    </ParamField>

    <ParamField body="device.osName" type="enum">
      Device OS name. (e.g. "Android", "iOS") (Case sensitive)

      Required when: required if device.deviceUUID is sent.

      | Value     | Description |
      | --------- | ----------- |
      | `Android` | Android OS  |
      | `iOS`     | iOS         |
    </ParamField>

    <ParamField body="device.osVersion" type="string">
      Device OS version [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#os-version) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#os-version)

      Required when: required if device.deviceUUID is sent.
    </ParamField>

    <ParamField body="device.locale" type="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.
    </ParamField>

    <ParamField body="device.timezone" type="string">
      Device Timezone. Use a Timezone Name defined by the IANA Database. (eg. `Asia/Seoul`, `America/Los_Angeles`, `Asia/Tokyo`)
    </ParamField>

    <ParamField body="device.orientation" type="string">
      Device orientation [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#orientation) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#orientation)
    </ParamField>

    <ParamField body="device.screen" type="string">
      Device screen information.

      <Expandable title="child attributes">
        <ParamField body="device.screen.density" type="string">
          Device screen density [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#screen-density) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#screen-density)
        </ParamField>

        <ParamField body="device.screen.height" type="number">
          Device screen height [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#screen-height) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#screen-height)
        </ParamField>

        <ParamField body="device.screen.width" type="number">
          Device screen width [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#screen-width) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#screen-width)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="device.alias" type="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](/en/guides/supporting-the-updated-google-eu-user-consent-policy).

      <Expandable title="child attributes">
        <ParamField body="device.alias.eea" type="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
        </ParamField>

        <ParamField body="device.alias.adPersonalization" type="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
        </ParamField>

        <ParamField body="device.alias.adUserData" type="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
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="app" type="object" required>
  User app information.

  <Expandable title="child attributes">
    <ParamField body="app.packageName" type="string" required>
      The package name of the app registered on Google Play Store or Apple App Store. (Android: Package Name, iOS: Bundle ID)
    </ParamField>

    <ParamField body="app.version" type="string">
      Version of the app. [Android](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-android-sdk#version) [iOS](https://developers.airbridge.io/v1.1-en/docs/data-fetching-guide-for-ios-sdk#application-version)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="eventData" type="object" required>
  Event information.

  <Expandable title="child attributes">
    <ParamField body="eventData.goal" type="object" required>
      An object that can contain information about an event. It can contain categories, actions, labels, values, and semantic attributes. ([Related Guide](/en/guides/airbridge-event))

      <Expandable title="child attributes">
        <ParamField body="eventData.goal.category" type="string" required>
          [The name of the Airbridge event ](/en/guides/airbridge-event-types)
        </ParamField>

        <ParamField body="eventData.goal.value" type="number">
          Event's value.

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

        <ParamField body="eventData.goal.customAttributes" type="object">
          Custom event attribute.

          `{ "color": "red" }`
        </ParamField>

        <ParamField body="eventData.goal.semanticAttributes" type="object">
          [Semantic Attributes.](https://abit.ly/recomended-semantic-attributes) Predefined attributes for which Airbridge is supposed to collect data.

          <Expandable title="child attributes">
            <ParamField body="eventData.goal.semanticAttributes.currency" type="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.
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.action" type="string">
              Airbridge event property 1
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.label" type="string">
              Airbridge event property 2
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.productListID" type="string">
              Product list ID.
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.cartID" type="string">
              Cart ID.
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.transactionID" type="string">
              Transaction ID.
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.inAppPurchased" type="boolean">
              In-app purchases or not.

              `true` for in-app purchase, `false` for not an in-app purchase.
            </ParamField>

            <ParamField body="eventData.goal.semanticAttributes.products" type="object[]">
              Product list.

              <Expandable title="child attributes">
                <ParamField body="eventData.goal.semanticAttributes.products[0].currency" type="string">
                  Currency.
                </ParamField>

                <ParamField body="eventData.goal.semanticAttributes.products[0].productID" type="string">
                  Product ID.
                </ParamField>

                <ParamField body="eventData.goal.semanticAttributes.products[0].price" type="number">
                  Product Price.
                </ParamField>

                <ParamField body="eventData.goal.semanticAttributes.products[0].name" type="string">
                  Product name.
                </ParamField>

                <ParamField body="eventData.goal.semanticAttributes.products[0].position" type="string">
                  Product position.
                </ParamField>

                <ParamField body="eventData.goal.semanticAttributes.products[0].quantity" type="integer">
                  Product quantity.
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  curl -X POST 'https://api.airbridge.io/events/v2/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' \
    -H 'x-airbridge-use-client-ip: 1' \
    -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",
      "clientIP": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
      "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
            }
          ]
        }
      }
    }
  }'
  ```
</RequestExample>

<h2 id="send-in-app-events-response">
  Response
</h2>

***

### 200

### 400

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

### 401

When using an invalid authentication token.

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "at": "2020-02-06 16:06:49",
    "data": "Event(9360) is successfully proccessed."
  }
  ```

  ```json 400 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "at": "2020-02-06 16:06:49",
    "error": "invalid_request",
    "ingested": 0
  }
  ```

  ```json 401 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
  {
    "at": "2020-02-06 16:06:49",
    "error": "unauthorized",
    "ingested": 0
  }
  ```
</ResponseExample>