Ad Spend Ingestion guide

The ad spend CSV file format, schema, and validation rules are detailed here. If you use Excel or Google sheets to create the file, you must see Excel formatting instructions. 

• Example Excel file. 
• Example CSV file.

Before reading further, take note of the most common errors made in preparing the CSV file as depicted in the following screenshot. 

The ad spend CSV file format, schema, and validation rules are detailed in the following sections. If you use Excel or Google sheets to create the file, you must see Excel formatting instructions.

Content rules and schema of ad spend CSV files

The Ad Spend token is used to verify that the email sender is authorized to submit the ad spend ingestion file. Advertiser and ad network tokens are different. 

• Advertiser token:
  • The same token is valid for all apps in the account
  • Any team member can retrieve the Ad Spend token
• Ad network token:
  • The same token is used for all advertisers. 
  • In addition, the advertiser needs to grant the ad network permission to submit ingestion files. 

To retrieve the ad spend token:

1. In AppsFlyer, Go to Integration > Ad Spend Ingestion. 
2. In the upper right-hand of the page, click View Ad Spend token.
   The Ad Spend token is displayed. 
3. Copy and save the Ad Spend token.

To grant the ad network Ad Spend Ingestion permission:

1. In AppsFlyer, the advertiser needs to go to Configuration > Integrated Partners. 
   The Integrated Partner page displays.
2. Select the integrated partner.
3. Go to the Permissions tab. 
   
   
4. Enable Ad Network Permissions if it is not already so.
5. (optional) Add team members.
6. Enable Allow spend ingestion.
   

Email prerequisites:

• Advertisers: Ad Spend token is required.
• Ad networks:
  
  • Ad spend token is required. 
  • The advertiser needs to grant the partner (ad network) ad spend ingestion permission. 

To send the ad spend file by email:

1. Complete the email address fields: 
   • To:adspend-upload@appsflyer.com
   • CC: Users who should get a copy of the automatic feedback
   • Subject: Paste the Ad Spend token in the subject field. 
   • Attachment: CSV file with the data.
2. Send the email.
   • On completion of processing, a status email is sent that summarizes the upload and detailing issues or errors found during processing. The email is sent to all parties on the submission email and to the advertiser admin. Where errors are identified, you should take corrective measures. 
   • You can view the status of files submitted in the Ad Spend Ingestion page

To upload the ad spend file:

1. In AppsFlyer, go to Integration > Ad Spend Ingestion.
   The Ad Spend Ingestion page displays. 
2. Click + Ingest Ad spend file
   The Ingest Ad spend window opens.
   
3. Drag the CSV file to the Ingest Ad spend file window.
   The Processing file message displays.
4. If an error message displays during upload: rectify the error and repeat the relevant steps. 
5. The Ad spend ingestion: file summary window opens.

   

6. Do one of the following:
   • Abort the upload, click Cancel ingestion. 
   • Complete the ingestion process, click Ingest file.
     The message, All set! displays.
7. Click Ingest another file or Done.

 To view the ingestion status at the file level:

• Go to Integration > Ad Spend Ingestion.
  The Ad Spend Ingestion page displays the list of uploaded files.
• If you have app permissions to all the apps contained in the file, use the Action command to:
  
  • Download CSV file: This a copy of the CSV file that was uploaded.
  • Download unmatched report for all apps in the file.

To view the ingestion status at the app-level:

• Select the file.
  The app-level page displays. The list of apps in the ad spend file displays.

  

• Perform file-level or app-level actions as described here.
• File-level: If you have app permissions to all the apps contained in the file, you can use the controls in the upper-right right side of the page to: 
  • Revert (cancel) the Ad Spend Ingestion for all apps in the file. 
  • Download a copy of the CSV file that was submitted. 
• App-level: If you have app permission for a specific app you can do so by using the Action command:
  • Download app data.
  • Download unmatched report for the app
  • Revert (cancel) the Ad Spend Ingestion for the selected app. 

Row matching is the process where the ingestion mechanism matches the ad spend rows reported by ingestion with attribution data recorded in the Dashboard. This is done using all dimensions available in file’s schema, such as media source, campaign, adset, ad, etc. 

Names vs IDs

Ad Spend Ingestion identifies a dimension, such as campaign, adset, or ad by its name, without the ID.  These rows are designated as is-matching=TRUE. At present, Ad Spend Ingestion doesn't support spend reporting using IDs. 

Note: Irrespective of the matching status, the spend is recorded.

The percentage of matched rows displays on the ingest page.

If unmatched rows are unexpected, download the unmatched report to investigate the cause. If necessary, cancel the ingestion by reverting it.

The Unmatched report contains a column, is-matched, which can have a value of TRUE (matched) or FALSE (unmatched) rows.

Ad Spend Ingestion page displaying the percentage of matched rows

Previously ingested ad spend can be overwritten by using CSV files that contain data with the identical key of data previously ingested.

The key is formed from the date, media source, and campaign fields. If the keys match, data ingested last overwrites data previously ingested.

The following examples illustrates ad spend overwrite.

Symptom: Cost data does not display after successful ingestion

1. In the dashboard, check to see if the campaign name displays more than once.
2. If so, locate the row where the campaign ID is blank.
   The row with the blank campaign ID contains the cost. 

Symptom: The ingested cost displays in a separate (additional row) without performance (installs) data. The campaign ID in the row is blank.

Cause: When using Ad Spend Ingestion, you identify the campaign using the campaign name only. You can't ingest the campaign ID. As a result, the ingested ad spend displays in a separate row without campaign ID or performance data.

When using Excel/Google sheets to create a CSV file, the date and spend columns need to be formatted correctly before you save the file as a CSV file. Use the following procedures to format the date and spend fields correctly. 

After saving the CSV file, verify that the content is formatted correctly. Note: Don't use Excel to do the verification, rather use an editor. 

Formatting date cells in Excel

To format date cells in Excel with the format YYYY-MM-DD:

1. Select the cells to be formatted.
2. Right-click, select Format cells.
   The format cells window opens.
   

   

3. Select Custom.
4. In the Type field, enter YYYY-MM-DD
5. Click OK.
   The date is formatted.

Formatting Spend cells in Excel

Excel usually formats value cells with a comma to separate the thousands, as shown in the figure. This format is not suitable for ad spend ingestion files. 

You can correct this by formatting the cells in Excel. 

To format the spend amounts without a 1000 separator: 

1. Select the cells to be formatted.
2. Right-click, select Format cells.
   The format cells window opens.
3. Select Number.
   

   

1. Clear Use 1000 separator (,). 
2. (Optional) Set the number of Decimal places. The default is 2. The maximum permitted is 5. 
3. Click OK.
   The cells are formatted correctly.

To examine the content of the CSV file, use an editor to view the file. 

• Windows: Notepad, Notepad++
• macOS: TextEdit

The following contains a screenshot of the example CSV file displayed in an editor. 

Editor view

Using an editor, examine the CSV file. Pay special attention to the following:

• Blank spaces: Ensure that there are no leading or trailing blank spaces before or after the commas that separate the fields. In Excel, use the @trim command to remove blank spaces. 
• Date: Ensure that the date field has the format YYYY-MM-DD. 
• Spend: Ensure that there is no comma in the spend field.
  

   

If Excel creates CSV file with a semi-colon ";" or other character as a delimiter but not a comma:

• This occurs when your computer's regional settings are set to a language/region that is not English.
• This issue is particularly prevalent when German is selected in the regional settings.
• The solution differs depending on your computer operating system (macOS or Windows).
• To resolve this issue, search for the latest guidance from Microsoft or other forums to revolve. Use the following search terms: Operating system (macOS or Windows) Excel change delimiter for CSV files.

If field names in the campaign hierarchy do not match the field names as they appear in the attribution data, they will be counted separately. 

For example, if the campaign names do not match, then even though the campaign IDs are the same, they will be counted as different campaigns.