At a glance: Ad Spend Ingestion provides advertisers with 100% coverage of their spend reporting needs. Advertisers and ad networks can record the ad spend (cost) from media sources that don't report spend by API or click.
Ad spend ingestion for ad networks
Full Ad Spend data
Use Ad Spend Ingestion to record ad spend (cost) from media sources that don't report the spend by click or API. Doing so enables you to have a complete picture of your ad spend and ROI in the Dashboard.
Ad spend can be recorded at the campaign level. This is done by using CSV files. The files are uploaded to the Dashboard and ingested. The updated aggregate ad spend displays in the Dashboard and aggregate data several minutes thereafter.
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 spend incurred originating from networks that do not send spend 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 your ad spend files.
We recommend that initially, 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
| Step | Description | Link |
|---|---|---|
| 1 |
Step for ad networks only: Before an ad network can send files, the advertiser needs to grant the ad networks 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 |
|
| 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 |
| 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 |
|
| 5 | Wait for an email status report from AppsFlyer detailing if the ingest was successful or if any 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 to create the file, you must see Excel formatting instructions.
Note
Don't use Excel 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 |
|---|---|
|
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 |
|
|
Column name (case sensitive) |
Format/remark |
Example |
Mandatory |
|---|---|---|---|
|
date |
|
2019-05-30 |
Yes |
|
app-id |
|
|
Yes |
|
media-source |
|
network_x_int |
Yes |
|
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. |
campaign_a |
Yes |
|
spend |
|
2874.12345
|
Yes |
|
geo |
Two-letter country code compliant with ISO 3166 |
US, GB, CN, AU |
Optional |
|
currency |
|
USD, GBP, EUR, JPY |
Optional. Will default to USD if left empty. |
Getting an Ad Spend token
The Ad Spend token is used to verify that the email sender is authorized to submit the ad spend file. Advertiser and ad networks tokens are different.
Caution
- Advertisers do not share your token with ad networks.
- The ad networks 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:
- Go to Integration > 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 spend ingestion permission
To grant the ad network Ad Spend Ingestion permission:
- The advertiser needs to go to Configuration > Integrated Partners.
The Integrated Partner page displays. - Select the integrated partner.
- Go to the Permissions tab.
- Enable Ad Network Permissions if it is not already so.
- (optional) Add team members.
- 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:
- 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.
- 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:
- In the Dashboard, go to Integration > 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 unmatched rows: The matched rows indicator displays the percentage of matched rows. If unmatched rows are unexpected, you should examine the data, by downloading the unmatched report to identify the root cause.
- 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 displays.
- 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 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. 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 in 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 spend
Previously ingested 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 illustrate ad spend overwrite.
Example: Ad spend overwrite
+ indicates the mandatory fields
Example A
| Date+ | App ID+ | Media Source+ | Campaign+ | Spend |
|---|---|---|---|---|
| 2019-06-01 | com.my.app | network_x | campaign_a | 100 |
| 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 field which for the key are the same. | ||||
Example B
| 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 |
| 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
Using Excel to format date and spend fields of CSV files
When using Excel 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 procedures here 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 ingestion.
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.