Ad Spend Ingestion guide

At a glance: Ad Spend Ingestion provides advertisers with 100% coverage of their campaign cost reporting needs. Advertisers and ad networks can record the campaign cost from media sources that don't report spend by API or click. 

Ad spend Ingestion

AdspendIngestion.jpg

 Watch Using Ad Spend Ingestion

Full campaign cost data

Use Ad Spend Ingestion to aggregate campaign costs from media sources that don't report cost by click or API. Doing so enables you to have a complete picture of your campaign costs and ROI in the Dashboard. 

Cost must be recorded at the campaign level with other dimensions in the advertising hierarchy being optional. The spend (cost) is reported by using CSV files uploaded to the dashboard for ingestion. Updated aggregate cost data are available in the Dashboard, and aggregate reports several minutes later.

Advertisers and ad networks can send and manage spend files. Agency support is on the roadmap. 

Previously ingested ad spend data can be overwritten if required.

Example use cases:

  • Record the costs incurred originating from networks that do not send cost data by API or attribution link
  • Offline channels, like radio campaigns and billboards
  • Influencers

To manage Ad Spend Ingestion go to Integration > Ad Spend Ingestion. Note: The Ad Spend Ingestion page is an account level page. This means you manage ingestions for all apps in the account using the same page. 

Preparing, uploading and ingesting ad spend files

Use one of the following workflows to prepare, upload, and ingest ad spend files. 

We recommend that at first, you use the file upload method. This is because error messages due to file format and content issues display immediately, making it simpler for you to resolve issues.

Upload workflows 

Workflow: Upload file in the user interface
Step Description Link
1

Step for ad networks only: Before an ad network can send files, the advertiser needs to grant the ad network permission

Grant spend ingestion permission
2

Prepare the CSV file 

CSV file format and schema
3

Upload and ingest the file in the user interface

Uploading ad spend files

4

On completion of the ingestion, use the interface to monitor the ingestion:

  • Status
  • Matched rows (In many cases a low matched rows percentage means you have errors in the data)
 Ad spend ingestion actions
 

Additional procedure: Overwrite previous ingestion

Overwrite previously ingested spend
Workflow: Upload file by email
Step Description Link
1

Prerequisite step for ad networks: Before an ad network can send files, the advertiser needs to grant them permission. 

Grant spend ingestion permission
2

Prerequisite: Get an ad spend token

Get an Ad Spend token
3

Prepare the CSV file

CSV file format and schema
4

Send the file by email 

Email

5 AppsFlyer emails a status report; it notes if the ingest was successful or if issues were found.  
6  Use the interface to monitor the ingestion:
  • Status 
  • Matched rows (In many cases a low matched rows percentage means you have errors in the data)
Ad spend ingestion actions
 

Additional procedure: Overwrite previous ingestion

Overwrite previously ingested spend

Procedures

CSV file format and schema

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. 

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

ingestionfile_en-us.png

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.

 Note

Don't use Excel or Google Sheets to either view or verify that CSV file is formatted correctly. Instead, use an editor

Content rules and schema of ad spend CSV files

File structure and content rules
Item Requirement

Prohibited characters

Fields in string format can't have =, +, -, or @ as the first character. For example, @example_campign or =123 are prohibited.

Media source

  • One media source per file
  • Multiple apps for the same media source are permitted
  • Limitations:
    • Don't send cost data from a media source that has an existing Cost API integration with AppsFlyer. Ingestion is not allowed from these sources. This includes Facebook Ads, Apple Search Ads, and Snapchat.

App owner 

One advertiser (app owner) per file permitted. This means that multiple apps from the same advertiser are permitted. 

Filename extension

CSV Example: abc123.csv

File structure

  • Format: Files have a CSV format meaning that each column is separated by a comma. Note this is the way that Excel format CSV files by default. If Excel formats the file with a semi-colon this is related to the regional setting of your computer. 
  • Header row: The first row is a header row that matches the schema
  • Data rows: Contain the mandatory columns. Note: Ensure that there are no trailing blanks in your data. For example, [USD ] (a blank follows the D should be changed to [USD].
  • Blank rows: Not permitted
  • Duplicate rows having the same key: Not permitted. The key is derived from using the mandatory fields.
  • Blank cells: Empty values are not allowed in the file. If you do not want to upload certain fields, they should not be in the file.

Advertising hierarchy 

Any partial data that is uploaded at a lower hierarchy will override all data from the campaign level down.

For example: If you ingest a file with campaign cost for adset 1, and separately ingest another file for adset 2 of the same campaign, the total cost of the campaign will be replaced and show only adset 2 data. For total campaign cost, the file you ingest needs to include adset 1 and adset 2. 

Ad Spend CSV schema

Column name 

(case sensitive)

Format/remark

Example

Mandatory

date

  • The date the spend was incurred
  • Format: String:
    (Best practice) YYYY-MM-DD
    YYYY/MM/DD
    MM-DD-YYYY 
    MM/DD/YYYY 
  • Future dates not permitted
  • Note: Are you using Excel/Google sheets to prepare the file? Read this

2019-05-30
2019/05/30
5-30-2019 
5/30/2019
05-30-2019
05/30/2019

 

app-id

  • Format: String
  • App ID as it appears in the Dashboard.
  • Multiple apps are allowed in a single file
  • All apps need to belong to the same advertiser
  • com.app.name 
  • id12356789

media-source

  • Format: String
  • Media source name exactly as it appears in the Dashboard. Note: Include the _int suffix if it displays in the Dashboard.
  • Only one media source per file permitted.

network_x_int

campaign

Campaign name. If the campaign name appears in the ad network, it should match (case sensitive) to the name as it appears in the ad network.

Format: String

campaign_a

spend

  • Monetary spend
  • Five digits allowed after the decimal point
  • The value 0 (zero) is permitted
  • Note:
    • The format "2,874.12" is not permitted.
    • Are you using Excel/Google sheets to prepare the file? Read this.

2874.12345

 

 

geo

Format: String

Two-letter country code compliant with ISO 3166

For the United Kingdom use UK not GB.
Note: Ensure that you send two characters with no blanks.

US, CN, AU

 

No

currency

  • Format: String
  • Three-letter currency code compliant with ISO 4217. Note: Ensure that you send three characters with no leading or trailing blanks.
  • One currency code per app in the file allowed. Different apps can have different currency codes. 

USD, GBP, EUR, JPY

No.

Will default to USD if left empty.

campaign-id

Format: String

abc1234def

No

adset

Format: String  my_adset_1 No

adset-id

Format: String id5678ghi No

ad

Format: String  my_ad_name No

ad-id

Format: String  id91011jkl No

site-id

Format: String  id1213mno No

channel

Format: String   video No

keywords

Format: String

  • better
  • better you app
  • better you online
No

Note: Names having non-English characters must be encoded using UTF-8.

Getting an Ad Spend token

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. 

 Caution

  • Advertisers do not share your token with ad networks.
  • The ad network has their own unique token. 
  • 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.

Granting an ad network ingestion permission

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. 
    PermissionAdNetwork.png
  4. Enable Ad Network Permissions if it is not already so.
  5. (optional) Add team members.
  6. Enable Allow spend ingestion.

Sending ad spend files by email

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

Uploading ad spend files

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.

    AdspendInestionFileSummary.png

  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.

Managing Ad Spend Ingestions

On the Ad Spend Ingestion page, you can perform the following actions. 

  • Monitor the status of ingested files: To identify ingestion files that require your attention as the data may not have been ingested or was ingested partially. You may need to resubmit these files.
  • Monitor the unmatched rows indicator: If the matched rows percentage is low, this can be a symptom of data with errors.
  • Download copies of CSV files submitted
  • Revert (cancel) the ingestion

Permission to view uploaded files and unmatched reports:

  • All team members can access the Ad Spend Ingestion page 
  • Access to detailed information is restricted to team members who have app permission.
  • If a file contains the data of multiple apps, the team member requires access to all the apps referenced in the file.

Ad Spend Ingestion actions

 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.

    Adspendingestions2.png

  • 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. 

Status indicators

Status Remarks
Applied Action completed successfully
Reverted Action completed successfully 
Error processing data

AppsFlyer system problem. Wait 10 minutes and try again. If it fails again, contact AppsFlyer support.

No permissions

The token is not approved for this app.

  • Advertisers: check to that that app id is correct.
  • Partner: confirm with the advertiser that they have enabled allow spend ingestion in the integrated partners permission tab. 

Validation error

 

 

Row matching and the unmatched report

Row matching is the process where the ingestion mechanism matches the ad spend rows reported by ingestion with campaign performance rows already recorded in the Dashboard. This is done using the media source, campaign, date fields as a key. 

Campaigns with campaign IDs

Ad Spend Ingestion identifies a campaign by campaign name without the campaign ID. If a campaign has both a name and ID, the ingested spend displays in a separate row without campaign ID. These rows are designated as is-matching=TRUE. Note: At present, Ad Spend Ingestion doesn't support spend reporting using campaign ID. 

 

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

 Example: Matched and unmatched rows

Date Media source Campaign Impressions Clicks Cost Matching status
2019-01-01 example abc 5000 100 $1000 is-matching = TRUE
Performance information found
2019-01-02 example abc       is-matching = FALSE
No performance information on 2019-01-02
2019-01-02 example influencer     $2500

is-matching = FALSE
No performance information on 2019-01-02

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

Adpsendmatching.png

Overwrite (correct) previously ingested ad spend

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.

 Example: Ad spend overwrite

+ indicates the mandatory fields

Example A

Spend1.csv ingested on Monday
Date+ App ID+ Media Source+ Campaign+ Spend
2019-06-01 com.my.app network_x campaign_a 100
Spend2.csv ingested on Tuesday
Date+ App ID+ Media Source+ Campaign+ Spend
2019-06-01 com.my.app network_x campaign_a 200
The spend data from spend1.csv was overwritten by the spend data in spend2.csv. This is because spend2.csv was ingested last, and the mandatory fields which form the key are the same. 

Example B

Spend3.csv ingested on Monday
Date+ App ID+ Media Source+ Campaign+ Spend Geo
2019-05-01 com.my.app network_x campaign_a 100 US
2019-05-01 com.my.app network_x campaign_a 200 CN
Spend4.csv ingested on Tuesday
Date+ App ID+ Media Source+ Campaign+ Spend
2019-05-01 com.my.app network_x campaign_a 50
The spend data from spend3.csv was overwritten by the spend data in spend4.csv. This is because spend4.csv was ingested last, and the mandatory fields which form the key are the same. Note: Both spend3.csv rows are overwritten. 

Troubleshooting

Ingested cost data does not display or displays in a separate row

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) dataThe 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.

Using Excel to format date and spend fields of CSV files

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.

    Formatdate..png

  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. 

mceclip1.png

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.

    Formatnumbers.png

  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.

Visual inspection of the CSV file without Excel

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

mceclip1.png

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.

    mceclip1.png 

CSV files generated by Excel don't have commas as delimiters

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.

Traits and limitations

Traits

Ad Spend Ingestion traits
Trait Ad Spend Ingestion supports Remarks 
Ad networks    
Agencies x  
Agency transparency x  
App-specific time zone  
App-specific currency  Campaign costs are converted to the app-specific currency 
Size limitations N/A  
Organic data  
Non-organic data  
Data freshness Ad spend  
Historical data N/A

 

Team member access  

Limitations

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.

Was this article helpful?