First-event check

Last updated 10/03/2026

This section describes how to use a special data structure of the AE system: the first-event check. The first-event check is a data filtering feature. You add a unique identifier ID to event data, and when the system receives the data, it checks whether that ID has appeared before. Data whose ID has already appeared can't be stored, while data whose ID hasn't appeared is stored and its ID is recorded. This ensures that only the event in which an ID appears for the first time is stored.

warning

The first-event check has a high performance overhead. We don't recommend adding it to all events, and we recommend that you use it with the assistance of ThinkingAI staff

1. Data structure

To use the first-event check feature, you need to make one adjustment to your data:

• Add the ID field #first_check_id, which must be a string. This field is the identifier ID used to check first events: the first record with a given ID is stored, and all records with that ID that appear later can't be stored. The #first_check_id values of different events are independent of each other, so the first-event checks of different events don't interfere with each other

The following is a data sample. Note where #first_check_id is located:

{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "#time": "2017-12-18 14:37:28.527",
  "#first_check_id": "123456",
  "#event_name": "test",
  "properties": {
    "argString": "abc",
    "argNum": 123,
    "argBool": true
  }
}

In the data above, #first_check_id is "123456". If another record of the event "test" with the #first_check_id "123456" has already been stored, this record can't be stored. If no such record has been stored before, this record can be stored

2. Data processing logic

The AE system maintains an ID table for each event, and the ID tables of different events are independent of each other.

When the system receives event data with #first_check_id, it looks up the #first_check_id of the data in the ID table of the corresponding event and handles the data differently based on the lookup result:

1. If the #first_check_id doesn't exist in the ID table, the data passes the check and is stored directly, and the #first_check_id is recorded in the ID table
2. If the #first_check_id already exists in the ID table, the data is discarded directly

If you upload both data with #first_check_id and data without this field for the same event, the data without this field isn't processed by the first-event check and is handled like regular data

tip

In addition to the key logic above, note the following two points:

1. To ensure performance, the system performs the check in scheduled batches with a default interval of 1 hour. Therefore, event data that uses the first-event check has a default query delay of 1 hour

2. "#first_check_id" isn't stored in the database after processing. If you need to keep it, record it in an event property

3. Best practices

New devices

New device data is ideal for the first-event check. Each time the app starts, you can report a "new device" event that uses the device ID as #first_check_id. According to the logic of the first-event check, only the "new device" event in which a device ID appears for the first time is recorded, and all data that appears later is discarded. Therefore, the stored events are exactly the events in which each device ID appears for the first time, which matches the logic of new devices.

The following is a sample of a "new device" event that uses the first-event check:

{
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#time": "2017-12-18 14:37:28.527",
  "#first_check_id": "device_id_123456",
  "#event_name": "new_device",
  "properties": {
    "device_id": "device_id_123456"
  }
}

You can report this event each time the app starts and use the device ID as #first_check_id. You can also add other properties, such as Device model and Source Channel, to add dimensions for analysis. If you use an AE client SDK or server SDK, see the integration guide of the corresponding SDK. The "First events" section of the guide provides detailed API call methods