Data Clean Room—Creating In-app event reports

Premium

At a glance: Create In-app event reports to focus on user activity occurring after an app has been installed. Extract specific event parameters from your in-app event raw data, optionally match the data with custom sources, then process and present it in aggregated form.

Creating an In-app event report

To create an In-app event report, follow the steps detailed in the tabs below.

Note: These steps are divided into tabs for ease of reading. All steps must be completed in order to create the report. (Certain steps, as indicated, are not relevant for reports that don't use custom sources.)

Perform preliminary steps

  1. Go to the Reports tab of the DCR.
  2. Click the + New report button.
  3. Select In-app events as the type of source data, then click Next in the bottom right corner of the screen.
  4. Enter a name for the report.
    • This can be any name that will help you identify the report in the DCR platform.
    • Important! Ensure that the report name is different from all other reports in your account or you will not be able to save the report.
    • Report name requirements:
      • Length: 2-80 characters
      • Valid characters:
        • letters (A-Z, a-z)
        • numbers (0-9), cannot be the first character of a name
        • a hyphen (-), cannot be the first character of a name
      • Invalid characters:
        • spaces
        • all other symbols or special characters

Select sources

Specify the source data to be used for the report:

In-app event sources

  • Apps: Select one or more of the apps in your AppsFlyer account.
  • Timeframe: Select the number of days of historical data you want the DCR to search for in-app events (from 1 to 30 days).
  • Events: Select one or more in-app events to include in the report.
    • The available events include all in-app events from the selected apps that have been configured to report data to AppsFlyer via the SDK or the server-to-server API (S2S).
  • Source types: Select one or more types of in-app event data:
    Installs

    In-app events related to install attributions

    • An install is recorded when a user downloads, installs, and launches a mobile app.
    Re-engagements

    In-app events related to re-engagements

    • A re-engagement is recorded when an inactive user of a specific app engages with a retargeting campaign for the app and subsequently launches it.
    Reattributions

    In-app events related to re-attributions

    • A re-attribution is recorded when a former user of a specific app (who had uninstalled it) engages with a retargeting campaign for the app and subsequently reinstalls it.

Data sources

  1. [Optional] Add more sources to use in the report. When choosing whether to more sources, note the significant difference between reports that do and do not use custom sources.
    • A report that doesn't use custom sources extracts specific event parameters and values from the in-app event raw data.
    • A report that does use custom sources extracts specific event parameters and values from the in-app event raw data, then matches this data with user-level data from your custom sources (such as data from your BI or CRM systems).
  2. Complete the next steps based on whether or not your report uses custom sources:
    • If your report doesn't use custom sources, skip to Select dimensions, then continue with the steps in all remaining tabs.
    • If your report does use custom sources, continue with the steps in the Join sources tab (immediately following) and all remaining tabs.

The following step is relevant only for reports that use custom sources.

Join sources (only for reports containing custom sources)

In order to match data among sources, each of the custom sources used in the report must include an identifier mapped to a key identifier in the in-app event data.

  • In-app event reports include all selected events matching the key identifier during the selected timeframe.

What is a key identifier?

You can map to either of these in-app event data identifiers as key identifiers:

  • AppsFlyer ID (af_id): A unique app identifier generated by AppsFlyer at installation
    • This ID appears in all events recorded by AppsFlyer.
    • A new AppsFlyer ID is generated if an app is deleted and then reinstalled.
  • Customer User ID (CUID): A unique user identifier usually generated and set by the app owner at the time of user registration.
    • Using CUID to map data requires that your app is configured to send the CUID to AppsFlyer via the SDK or the server-to-server API (S2S).

 Important!

Not all media sources permit matching using CUID. It is highly recommended to use AppsFlyer ID.

Mapping schemes (direct/indirect)

If the report includes more than one custom source, only one of them needs to be mapped directly to an in-app event key identifier. Other custom sources can be mapped either directly or indirectly, as illustrated in the following example:

 Example

dcr_mapping_identifiers_in-app events.png

In the scenario shown above:

  • Custom source #1 identifier AF is mapped directly to the in-app event key identifier af_id.
  • Custom source #2 is mapped indirectly: user_code --> AF --> af_id.
  • Custom source #3 is mapped indirectly (through a longer chain):
    user_id --> user_code --> AF --> af_id.
  • Custom source #4 identifier ID is mapped directly to the in-app event key identifier af_id.
    • Note that it could have been mapped indirectly instead (through custom source #3 identifier user_id), but either option works fine.

This mapping scheme works to match data among all the sources since each custom source is mapped either directly or indirectly to the in-app event key identifier af_id.

The remaining tabs are relevant for all in-app event reports, whether or not they include custom sources.

Select dimensions

Recall that user-level data cannot be reported by the DCR. Instead, it provides you with the decision-making insights you need by aggregating (or grouping) the data by the dimensions you choose.

A dimension is generally an attribute by which you categorize app users (for example, geo, install date, campaign, etc.)

Extracting dimensions from event_value

When in-app events are reported to AppsFlyer via the SDK or the S2S API, much of the raw data is contained in a single field called event_value. This structured data field includes all of the specific in-app event parameters that have been configured for the events that your apps send to AppsFlyer.

One of the major advantages of In-app event reports is that they allow you to extract specific parameters and their values from the event_value field for the events you choose.

To extract dimensions from the event_value field for use in DCR reports:

  1. In the Dimensions from sources list, click the extract_dimension_button.png button.

    The Extract field from event_value window opens.

  2. In the Report field box, enter the name of the extracted dimension as you would like it to appear in your report.
  3. From the Event_value parameter list, select the in-app event parameter that should be mapped by default to the report field (dimension) you defined in step 2.
    • The available parameters include those that have been configured in the selected in-app events in the selected apps.
  4. It may be that the default mapping differs by app and/or event. If this is the case:
    1. Click the Add exception button
    2. Select the app and event for which the report field should be mapped differently.
    3. Select the in-app event parameter that should be mapped to the report field for this combination of app/event.
    4. Follow these steps for as many exceptions as you want to set up.
  5. When you are finished setting up the mapping for the extracted dimension, click Save and add another to extract another dimension from the event_value field or Save to return to the main screen.

To edit extracted dimensions:

  1. In either the Dimensions from sources or the Report dimensions list, hover over the name of the dimension you want to edit.
  2. Click the more_options_button.png button that displays to the right of the dimension.
  3. Select Edit extracted field.
  4. Make changes to the Report field name and/or parameter mapping as necessary.
  5. Click Save to save your changes.

To delete extracted dimensions:

  1. In either the Dimensions from sources or the Report dimensions list, hover over the name of the dimension you want to delete.
  2. Click the more_options_button.png button that displays to the right of the dimension.
  3. Select Delete field.
    • Caution! If you delete an extracted field from the Report dimensions list, it will delete the definition of the extracted field. If you wish to remove the field from the report while preserving its definition, select the field and use the Remove button instead.

Selecting report dimensions

In-app event report dimensions can include:

To select the dimensions to include in your report:

  1. Select one or more dimensions in the Dimensions from sources list on the left and use the Add button in the middle of the screen to add them to the list of Report dimensions.
    • You can use the search bar to search for dimensions in the lists.
  2. To remove a dimension, select it from the Report dimensions list and use the Remove button to return it to the Dimensions from sources list.
  3. Repeat this process until you have added each dimension you want to include in the report.

Note: By default, all reports are grouped by the in-app event dimension media_source. If you do not wish to use this dimension in your report, you can remove it from the Report dimensions list.

[Optional] Customizing dimension display names

By default, dimension names are displayed in your report exactly as they are named in the in-app event data or your custom sources. If you wish, you can customize dimension names for your report.

To customize dimension display names:

  1. In the Report dimensions list, hover over the name of the dimension whose display name you want to edit.
  2. Click the edit button edit_button.png that displays to the right of the dimension.
  3. Change the name to the dimension display name to be used in your report (up to 50 characters).
  4. Click OK to save the display name, or X to cancel it.

Note: If you want to change the name of an extracted dimension, use the steps for editing extracted dimensions (above).

Preserving privacy while grouping by dimension (regrouping)

Depending on the size of your data set, the number of dimensions you choose, and other factors, it's possible that a report would include one or more groups containing too few users to allow reporting. If the data were reported this way, it would violate restrictions against providing user-level data.

However, instead of removing or hiding the data from the report completely, the DCR uses a regrouping mechanism to provide as much detail as possible while maintaining user privacy.

 Regrouping example

Assume you have set up a report according to the following dimensions (in order):

  • In-app event dimensions:
    • media source
    • campaign
    • adset_name
    • ad_id
  • Custom source dimensions:
    • user_type

Before regrouping

After initial analysis of the data, the DCR determines that the data would break down as follows:

media
source
campaign adset
name
ad
id
user
type
rev
D0
rev
D7
count reportable?
media_source UA_100 green kjh867 buyer 1 4 120

media_source UA_101 green jkj987 ultra 2 23 220

media_source UA_200 green lkh123 beg 6 7 x

X

media_source UA_200 green ilk945 beg 3 21 x

X

media_source UA_200 green plm654 beg 8 17 x

X

As it stands, the final 3 rows are not reportable because there are too few users in each. (This media source requires a minimum of y users in order to be reportable. Here, we have only x.)

According to the regrouping logic, the DCR first "eliminates" the last-listed in-app event dimension (in this case, ad_id). It then analyzes the data again to see which rows are reportable.

After regrouping

After applying the regrouping logic, the report appears as follows:

media
source
campaign adset
name
ad
id
user
type
rev
D0
rev
D7
count reportable?
media_source UA_100 green kjh867 buyer 1 4 120

media_source UA_101 green jkj987 ultra 2 23 220

media_source UA_200 green RESTRICTED beg 17 45 y (x+x+x)

Results:

  • The last row now combines the data that had previously been on 3 rows. Now, the combined row has a user count equal to y and can be reported.
  • The dimension that was eliminated is now reported as RESTRICTED.
  • Had there still been unreportable rows (fewer than y users), the DCR would continue to analyze the data on an iterative basis, eliminating one dimension after another until it either:
    • can report all rows; or
    • runs out of in-app event dimensions to eliminate

Note: By default, the DCR applies regrouping only to default in-app event dimensions (not to extracted in-app event dimensions or custom source dimensions). If data grouped by a default in-app event dimension would result in a row containing fewer than y users, the data in that row will be reported as RESTRICTED.

  • See below for an advanced option you can use to apply regrouping to custom source dimensions as well.

[Optional] Managing dimension priority

By default, in-app event dimensions are eliminated in reverse order from the order in which they appear in the Report dimensions list. However, you can modify the default sequence and/or apply regrouping to selected custom source dimensions (if applicable) in order to preserve the dimensions most important to you.

To change the order in which dimensions are eliminated:

  1. Click the Manage dimension priority button.
  2. Select a dimension and drag it to the desired position in the list (or use the arrow buttons on the right to move it).
    • The dimension labeled as Highest priority (at the top of the list) means it's the last to be eliminated if regrouping is required.
  3. [Optional] To apply regrouping to custom source dimensions (for reports using custom sources):
    1. Click Use advanced options to refine regrouping
    2. Select custom source dimensions to which you'd like to apply regrouping.
    3. The selected dimensions are added to the Manage dimension priority list.
      • By default, these dimensions are added to the bottom of the list, as Lowest priority for regrouping. However, you can reorder them just like in-app event dimensions as described above.
  4. Click OK to save your changes.
    • The Report dimensions list on the main screen remains in its original order, but the revised order has been saved. (Click again on the Manage dimension priority button if you wish to review or edit your selection.)

Select metrics

Metrics are the numeric data you have collected with respect to an app user (examples might include revenue, number of app opens, LTV, etc.) and can be any numeric data field from your sources that you have categorized as a metric.

Extracting metrics from event_value

Just as you can for report dimensions, you can extract in-app event parameters from the event_value field for use as metrics in your reports.

To extract dimensions from the event_value field for use in DCR reports:

  1. In the Metrics from sources list, click the extract_metric_button.png button.

    The Extract field from event_value window opens.

  2. In the Report field box, enter the name of the extracted metric as you would like it to appear in your report.
  3. From the Event_value parameter list, select the in-app event parameter that should be mapped by default to the report field (metric) you defined in step 2.
    • The available parameters include those that have been configured in the selected in-app events in the selected apps.
  4. It may be that the default mapping differs by app and/or event. If this is the case:
    1. Click the Add exception button
    2. Select the app and event for which the report field should be mapped differently.
    3. Select the in-app event parameter that should be mapped to the report field for this combination of app/event.
    4. Follow these steps for as many exceptions as you want to set up.
  5. When you are finished setting up the mapping for the extracted metric, click Save and add another to extract another metric from the event_value field or Save to return to the main screen.

To edit extracted metrics:

  1. In either the Metrics from sources or the Report metrics list, hover over the name of the metric you want to edit.
  2. Click the more_options_button.png button that displays to the right of the metric.
  3. Select Edit extracted field.
  4. Make changes to the Report field name and/or parameter mapping as necessary.
  5. Click Save to save your changes.

To delete extracted metrics:

  1. In either the Metrics from sources or the Report metrics list, hover over the name of the metric you want to delete.
  2. Click the more_options_button.png button that displays to the right of the metric.
  3. Select Delete field.
    • Caution! If you delete an extracted field from the Report metrics list, it will delete the definition of the extracted field. If you wish to remove the field from the report while preserving its definition, select the field and use the Remove button instead.

Select report metrics

To select the metrics to include in your report:

  1. Select one or more metrics in the Metrics from sources list on the left and use the Add button in the middle of the screen to add them to the list of Report metrics.
    • You can use the search bar to search for metrics in the lists.
  2. For each metric in the Report metrics list, select whether you want the data reported as either:
    • a sum of numeric values; or
    • a count of distinct values
  3. To remove a metric, select it from the Report metrics list and use the Remove button to return it to the Metrics from sources list.
  4. Repeat this process until you have added each metric you want to include in the report.

[Optional] Customizing metric display names

By default, metric names are displayed in your report exactly as they are named in the in-app event data or your custom sources. If you wish, you can customize metric names for your report.

To customize metric display names:

  1. In the Report metrics list, hover over the name of the metric whose display name you want to edit.
  2. Click the edit button edit_button.png that displays to the right of the metric.
  3. Change the name to the metric display name to be used in your report (up to 50 characters).
  4. Click OK to save the display name, or X to cancel it.

Note: If you want to change the name of an extracted metric, use the steps for editing extracted metrics (above).

[Optional] Select identifiers to count

By default, each row of the report ends with a column containing a count of the distinct AppsFlyer IDs grouped in that row's data.

If you wish to add columns for the distinct counts of other identifiers from your sources, do so as follows:

  1. Select one or more identifiers in the Identifiers from sources list on the left and use the Add button in the middle of the screen to add them to the list of Distinct count identifiers.
    • You can use the search bar to search for identifiers in the lists.
  2. To remove an identifier, select it from the Distinct count identifiers list and use the Remove button to return it to the Identifiers from sources list.
  3. Repeat this process until you have added each identifier you want counted in the report.

Configure report settings and save the report

Schedule (only for reports without custom sources)

Reports without custom sources are run according to the schedule you define.

To define the report schedule:

  1. Select whether to run the report daily or on one or more days each week.
  2. Select the time at which to run the report (timezone is UTC).

 Important!

Scheduling options are disabled for reports that use custom sources. This type of report runs whenever new versions of all of the custom sources it uses are detected:

  • For sources located in data warehouses (BigQuery and Snowflake), the DCR recognizes that a new version of a source has been created when it detects a new value in the v column of the source table.
    • Important! To ensure the completeness of your report, be sure to populate the source table with a complete set of data whenever the column value is changed.
  • For sources located in cloud storage buckets (Amazon S3 and GCS), the DCR recognizes that a new version of a source has been created when it detects that a new version of a source file has been uploaded along with its accompanying _SUCCESS file.

AppsFlyer continually scans for new versions of sources for the current date and 2 days prior.

Report destination

The DCR delivers reports to your selected cloud services using AppsFlyer Data Locker. Therefore, specifying the report destination involves selecting or creating a Data Locker connection.

  • Note: Receiving DCR reports does not require a premium subscription to Data Locker. If you are interested in receiving other AppsFlyer reports via Data Locker, contact your CSM or send an email to hello@appsflyer.com.

To set the report destination and save the report:

  1. Select from the list of Data Locker connections available in your AppsFlyer account.
    • If there are no connections defined in your account:
      • A new tab will open in your browser (showing the AppsFlyer Data Locker page)
      • A New connection dialog will open. Follow these instructions to create the connection.
    • If you have existing connections but want to use a new one, click the dcr_new_connection_data_locker_button.png button:
      • A new tab will open in your browser (showing the AppsFlyer Data Locker page)
      • A New connection dialog will open. Follow these instructions to create the connection.
    • After creating the connection, return to the DCR tab in your browser and select the newly created connection from the list of Data Locker connections.
  2. Click Save to save the report.
  3. The new report is now displayed in the Reports tab of the Data Clean Room.

Reference

Default in-app event dimensions

In addition to dimensions extracted from event_value and dimensions from your custom sources (if applicable), the following in-app event dimensions can be used to group reports:

  • media_source (included as a report dimension by default)
  • ad
  • ad_id
  • ad_type
  • adset_id
  • adset_name
  • app_id
  • app_version
  • attributed_touch_time
  • attributed_touch_type
  • brand
  • campaign
  • campaign_id
  • channel
  • city
  • conversion_type
  • country
  • device_type
  • dma
  • event_name
  • event_revenue_currency
  • event_time
  • geo_region
  • install_time
  • is_attributed
  • keywords
  • match_type
  • model
  • partner
  • platform
  • site_id

Default in-app event metrics

In addition to metrics extracted from event_value and metrics from your custom sources (if applicable), the following in-app event metrics can be included in reports:

  • event_revenue
  • event_revenue_u_s_d