At a glance: Ad Spend Ingestion, part of AppsFlyer ROI360, 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
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 within 4 hours of ingestion.
Advertisers and ad networks can send and manage spend files. Agencies can prepare files for ingestion, but the advertiser must upload the files for them.
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 ROI360 > Ad Spend Ingestion. Note: The Ad Spend Ingestion page is an account-level page. This means that advertisers manage ingestions for all apps in the account using the same page.
Preparing, uploading, and ingesting ad spend files
There are 2 workflows you can use to prepare, upload, and ingest ad spend files:
- Upload file in the user interface.
Note:- We recommend you try this method first. This is because error messages due to file format and content issues display immediately, making it simpler for you to resolve issues.
- This method isn't available for apps on CTV, PC, and console platforms.
- Upload file by email.
- For apps on CTV, PC, and console platforms, use only this method.
Both workflows are explained in the sections that follow.
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 Note: Agencies can also prepare files for their data. Learn more |
CSV file format and schema |
3 |
Upload and ingest the file in the user interface |
|
4 |
On completion of the ingestion, use the interface to monitor the ingestion:
|
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 Note: Agencies can also prepare files for their data. Learn more |
CSV file format and schema |
4 |
Send the file by email |
|
5 | AppsFlyer emails a status report; it notes if the ingestion was successful or if issues were found. | |
6 | Use the interface to monitor the ingestion:
|
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.
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
Item | Requirement |
---|---|
Prohibited characters |
Fields in string format can't have |
Media source |
|
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 |
|
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 |
|
2019-05-30
|
✓ |
app-id |
|
|
✓ |
media-source |
|
network_x_int |
✓ |
campaign |
|
campaign_a |
✓ |
spend |
|
2874.12345
|
✓ |
geo |
Format: String Two-letter country code compliant with ISO 3166. For the United Kingdom use UK, not GB. |
US, CN, AU
|
No |
currency |
|
USD, GBP, EUR, JPY |
No. Will default to USD if left empty. |
campaign-id |
Format: String |
abc1234def |
No. Note: If attribution data exists with both name and ID, the CSV must contain both in order to match. |
campaign |
Format: String |
campaign_name |
|
adset |
Format: String | my_adset_1 | |
adset-id |
Format: String | id5678ghi | |
ad |
Format: String | my_ad_name | |
ad-id |
Format: String | id91011jkl | |
site-id |
Format: String | id1213mno | No |
channel |
Format: String | video | No |
keywords |
Format: String |
|
No |
agency |
|
AgencyName | 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 its own unique token.
-
Advertiser token:
- The same token is valid for all apps in the account
- Any account user 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:
- In AppsFlyer, Go to ROI360 > Ad Spend Ingestion.
- In the upper right-hand of the page, click View Ad Spend token.
The Ad Spend token is displayed. - Copy and save the Ad Spend token.
Granting an ad network ingestion permission
To grant the ad network Ad Spend Ingestion permission:
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:
- 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.
-
To:
-
Send the email.
- On completion of processing, a status email is sent that summarizes the upload and details 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. Note: If the status mail was not received see here.
- You can view the status of files submitted on the Ad Spend Ingestion page
Uploading ad spend files
To upload the ad spend file:
- In AppsFlyer, go to ROI360 > Ad Spend Ingestion.
The Ad Spend Ingestion page displays. - Click + Ingest Ad spend file
The Ingest Ad spend window opens.
- Drag the CSV file to the Ingest Ad spend file window.
The Processing file message displays. - If an error message displays during upload: rectify the error and repeat the relevant steps.
- The Ad Spend Ingestion: file summary window opens.
- Do one of the following:
- Abort the upload, click Cancel ingestion.
- Complete the ingestion process, click Ingest file.
The message, All set! displays.
- 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 account users can access the Ad Spend Ingestion page
- Access to detailed information is restricted to account users who have app permission.
- If a file contains the data of multiple apps, the account user 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 ROI360 > 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.
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.
|
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 attribution data recorded in the Dashboard. This is done using all dimensions available in the file’s schema, such as media source, campaign, adset, ad, etc. If they all match, the rows are designated as is-matching=TRUE.
Names vs IDs
Ad Spend Ingestion identifies a dimension, such as campaign, adset, or ad by its name, without the ID. Currently, Ad Spend Ingestion doesn't support spend reporting using just IDs.
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 |
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
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
Error messages and solutions
The following table lists all possible Ad Spend Ingestion error messages and corresponding solutions.
Error message | Description | Solution |
---|---|---|
None of the app IDs provided in the file exist in AppsFlyer. Please verify the correctness of app IDs. | App ID does not exist in the account. | Change app ID and resubmit. |
Line [line name] has the wrong number of columns. Expected [number] columns, received [number] columns. |
All columns in the file must have a value. | Change the values populated in the file based on the headers you defined. |
Missing 'media-source' in file header. |
|
Add media-source as a header name. |
The file can contain only one media source. Multiple media sources encountered in the file: [number of media sources]. | Cannot upload a file with more than one media source. | Split the upload into one file for each media source. |
The value provided [value] for [field] is not a valid value for this column. | Data format in the column is incorrect. For example, the date is dd-mm-yy instead of yyyy-mm-dd. | Correct the format and resubmit. |
Multiple currencies identified for the app. Please use a single currency for each app in the file. Encountered currencies: %number of currencies%. | Only one currency can be used for an app. | Use one currency in the upload and resubmit. |
The following columns in the file header are not supported: [file headers] |
File header does not match the scheme. Meaning, the column name needs to be exactly as it is in the scheme. |
Remove the unsupported columns and resubmit. |
Missing required columns in file header: [file headers] | File header is missing a mandatory column. | Add the missing column and its values and resubmit. |
The app contains a future date: [date] | Future dates are not allowed. | Correct the date to today's date or earlier, and resubmit. |
The file is empty. There is no data to process. | The file is empty. | Populate data in the file and resubmit. |
The following two rows conflict due to identical dimensions. Please provide a single row of spend per set of dimensions. [conflicting rows] | There is more than one row with the same key (mandatory) fields. | Remove the duplicate rows and resubmit. |
The file can contain data only from a single advertiser account. Different advertisers encountered in file: [advertiser names] | For partners, an upload cannot be for more than one advertiser. | Split the upload into one file per advertiser. |
The app [app ID] doesn't exist in the account. Please verify the app ID. | App ID does not exist. | Correct the app ID and resubmit. |
Geo (country) code was not found for app [app ID]. Use an ISO 3166 2-letter code | Geo does not exist. | Correct the geo and resubmit. |
Currency code was not found for app [app ID]. Use an ISO 4217 3-letter code. | Currency does not exist | Change the currency to a valid currency and resubmit. |
There were validation errors for one or more apps in the file. Please review the file information for more details. | There is more than one error in the file. | Download the file and review for errors. |
There was an internal error processing the file, please try uploading it again. |
|
Wait 1 hour and upload again. |
Ingested cost data does not display or displays in a separate row
Symptom 1: Cost data does not display after successful ingestion
- In the dashboard, check to see if the campaign name displays more than once.
- If so, locate the row where the campaign ID is blank.
The row with the blank campaign ID contains the cost.
Symptom 2: The ingested cost displays in a separate (additional row) without performance (installs) data. The campaign ID in the row is blank.
Cause: When both campaign ID and campaign name exist in attribution data, the CSV must contain both in order for AppsFlyer to correctly to match the cost data and avoid separate line items.
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:
- Select the cells to be formatted.
- Right-click, select Format cells.
The format cells window opens.
- Select Custom.
- In the Type field, enter YYYY-MM-DD
- 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:
- Select the cells to be formatted.
- Right-click, select Format cells.
The format cells window opens. - Select Number.
- Clear Use 1000 separator (,).
- (Optional) Set the number of Decimal places. The default is 2. The maximum permitted is 5.
- 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
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.
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.
After emailing the ad spend files, no status email is received
Probably it means that the ad spend file was not processed. It can happen for a variety of reasons:
Wrong content-type
AppsFlyer only processes messages with the multipart/mixed
content-type. Other types are not processed and consequently no status email is generated and sent back. In the normal case emails with attachment are automatically set to multipart/mixed
by the mail client.
To make sure that the email message content-type is multipart/mixed
view the content-type value in the email header.
- To view the email message header in Gmail follow the Gmail documentation.
- To view the email message header in Outlook follow the Outlook documentation.
The email message HTML is not properly formatted
HTML errors can prevent the correct processing of the email. For example the tag is empty or missing. Check your script for HTML errors.
Additional information
Preparing a CSV file with agency data
Advertisers and agencies can prepare CSV files to upload and ingest cost data. To do so, the CSV files must contain an Agency column with the agency name (the agency name is the value in the af_prt parameter). See CSV schema
Consider:
- Only one agency can be included in a file. And only campaigns managed by that agency can be included in the file.
- The agency name is mandatory per row. No blank cells are allowed in the agency column.
- The agency must have permission to all the apps included in the file.
- Only advertisers can upload the file. Agencies can't upload data. They can prepare their files and send them to the advertiser to upload.
Traits and limitations
Trait | Ad Spend Ingestion supports | Remarks |
---|---|---|
Ad networks | ✓ | |
Agencies | ✓ |
Agencies can't upload data. They can prepare their files and send them to the advertiser to upload. |
Agency transparency | x | |
App-specific time zone | ✓ | |
App-specific currency | ✓ | Campaign costs are converted to the app-specific currency. |
Campaign name | N/A | The same campaign name can't be used for multiple apps, or the cost of one app will apply to both. |
Field names | N/A |
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. |
File size | N/A |
When uploading a CSV ad spend ingestion file the size limit is:
|
Organic data | ✓ | |
Non-organic data | ✓ | |
Data freshness | Ad spend | |
Historical data | ✓ |
Cost reported can be reverted, and corrected data submitted, for up to 90 days. |
Retargeting | x | |
Account user access | ✓ | Not available for users with geo or media source restrictions. |