Skip to main content
Sign in

Search

Flight Control Help Center

App Event Setup

  • Updated

General

App Events data sources record page visits and actions on an advertiser's mobile application.

The process of configuring this data source entails the following steps:

  1. Creating a data source "skeleton" in Flight Control.
  2. Enabling Clinch in the partner's platform. (This is needed to forward the required event types and their parameters to Flight Control.)
  3. Confirming that event data is being received.
  4. Mapping the vendor's or application's parameter names and values in Flight Control to align with Flight Control naming conventions.

Configuring an App Events Data Source

Step 1: Create the Data Source

  1. Go to Account > Data Sources.
  2. Click Create > App Event Pixel.
  3. Enter a data source name.
  4. Select a partner.
  5. Select a product type for the data source.
  6. Click Add.
    • The new data source will be added to the Data Sources Table.
    • After creating the data source, Flight Control will generate a Client ID (CID) and Data Source ID (DSID). These encoded IDs are needed to enable Clinch in a partner's platform (see Step 2 for details).
  7. Click on the data source Get Instructions quicklink to access the Client ID (CID) and Data Source ID (DSID).

Step 2: Enable Clinch in the Partner's Platform

Most app event data source setups entail sending event data from the app code to the partner's servers. This step is required on the partner side to enable forwarding the required event types (some or all) to Flight Control servers and defining which parameters to include in these events.

For Flight Control partners:

  1. Locate your App Events data source in the table and click its Get Instructions quicklink.
  2. Provide your partner with the Clinch client ID (CID) and data source ID (DSID).
  3. Follow partner-specific instructions for enabling and sending application event data to Flight Control.
    • In general, "install," "reinstall," and all in-app events should be sent to Flight Control. However, Clinch account managers must define what these events will be used for in Flight Control (for ad decisioning, attribution, and so on) to determine the event types and parameters to include.

Important: To save time, it is recommended that you consult with the app owner or IT team, who is familiar with the events being sent from the app.

For "Other" partners:

If you select "Other" as your app-events pixel partner, you'll need to implement event tracking manually:

  1. To use partners not explicitly listed in the Flight Control UI, please contact your Clinch account representative.

Step 3: Validate the Events Being Received in Flight Control

After the events have been enabled on the partner side, the events should start coming into the Flight Control servers. The purpose of this step is to ensure that the events are coming in and to verify which event types and parameters have been received before moving to the next step of mapping the incoming event parameters to Flight Control naming conventions.

  1. Validating events are being received:
    • Go to Account > Data Sources
    • On the respective data source, the Statistics column will show you the distribution of the events being received yesterday. Note: This is relevant only if you enabled the events on the partner side at least 1 day before
    • If you enabled the events on the partner side the same day, you can click on the Insights Data quicklink, which opens a modal where you can see events data by any date range, including today
      • You may see a single event type called "Other" since the mapping for the Flight Control naming convention has not been done yet (Reference Step 4 for details).
    • If the partner enabled Clinch in their dashboard, but no events are recorded after several hours, then go back to Step 2 to review and fix any setup issues.
  2. Validating the received events keys and values:
    • Before you continue to Step 4, it is important to understand which parameters and values have been received along with the events, so that you will know what to map.
    • Currently, this is a manual process and requires Clinch Account Manager involvement; however, in the near future, Flight Control will provide you with this data in the Data Source insights
    • Reach out to your Clinch Account Manager or Customer Success Team to request an App Events Pre-mapping report for this Data Source ID
      • This report should outline all the event parameter keys and values that have been recorded by Flight Control. The most important key is the "event type"; you want to make sure that all expected types have been received
    • If event parameters keys or values are not as expected, you will have to go back to Step 2 to review and fix any setup issues

Note: Depending on the partner, you might need to wait several hours before you see data in Flight Control.

Step 4: Map Parameter Names and Values to Flight Control Naming Conventions

After you know exactly which events and parameters have been received in Flight Control, for each event, you can map individual incoming event parameters to names configured in your account’s taxonomy.

This allows you to use custom values in a campaign - by mapping custom values to specific product attributes - e.g., for a cruise line campaign, mapping "Text Field 1" to ship name or departure port - you can retarget users with products that share the exact characteristics they previously engaged with in the app.

The "key name" for each parameter in the incoming events, and if needed, the values from the advertiser/partner taxonomy, must be mapped to the Flight Control taxonomy (naming conventions).

To map parameter names:

  1. Go to Account > Data Sources.
  2. Hover over the data source and click Mapping.
    • This opens the Event Configuration pane.
  3. Enter the event key (field name) that was received in the app event. (This is the parameter name on the partner's side.)
  4. Configure events.
    1. Click Add Event.
    2. If needed, change the product funnel event type (e.g., Purchase, Add to Card, Details, Custom).
      • Important: To prevent duplicate tracking, standard funnel event types (e.g., Search, Add to Cart) can only be selected once per pixel. Once chosen, that type is removed from the dropdown of event types you can select. However, you may create multiple Custom or Purchase events per pixel.
    3. Optional. If needed, configure the event's parameters.
      1. Select a Flight Control parameter name. These are configured in your account’s taxonomy.
      2. Enter the expected parameter key name in the pixel.
        • Note: Selecting a Flight Control name automatically populates this field in lowercase with underscores (e.g., Body Style becomes “body_style”), which can be edited as needed.
      3. For subtype event parameters: Enter a subtype name and value.
      4. Optional. Click Advanced Mapping Settings to configure a rule that modifies the parameter's incoming app events pixel data, such as changing capitalization, replacing values, using Regex, and more. These settings are for advanced use cases.
      5. Optional. Click Add Parameter to include an additional parameter for the event.
    4. Repeat previous steps as needed to continue creating events for the app events pixel.
  5. Click Submit.

Step 5: Validating the Mapping

After the mapping is completed, you will need to verify that the data is recorded correctly using Flight Control's naming convention. The steps below must be performed at least four hours after the mapping is done:

  1. Hover over the data source in the table and click Insights Data.
  2. Ensure that the event types are recorded as needed.
  3. Confirm that other required parameters are recorded correctly.

Note: The mapping will only apply to events received after mapping (not retroactively).

Monitor App Events in Real Time

Use the Monitoring diagnostic tool (📈), located in the Events Configuration pane, to validate that your app events pixel ingestion matches your configured mappings.

The Monitoring Events table shows the most recent pixel payloads received by the server (defaulting to a sample size of 3 hits per event type), prioritized by those that contain mapping discrepancies.

It also validates live data against your active configuration based on the following logic:

  • Green Check (No Issues): The event type is recognized, and all parameters received in the raw pixel match your configuration perfectly.
  • Red Triangle (Discrepancy Detected): This status is triggered when:
    • An event parameter is received but not mapped. Add this parameter to the 1P Data taxonomy and use it within the relevant event parameter mapping.
    • A mapped parameter isn't received in the pixel event.
    • An unrecognized event name is received.