📘

Beta

Please note that the file ingestor for ROI Hub is currently in Beta. Be aware that there may be unexpected bugs until the full release. ROI Hub is part of our Performance Pro package.

Overview

If you would like to upload your ad partner cost data using the Branch Dashboard, you can do so using ROI Hub's File Ingestion tab.

Uploading this data will pipe it to your Branch Dashboard reports, where you can analyze campaign performance across multiple ad partners in one place.

Please note that you must upload a CSV file containing your data, and the structure of the data within the file must match the formatting requirements of the file ingestor precisely.

Prerequisites

In order to start tracking cost data, you first need to:

1. Create a Branch Dashboard.
2. Enable our Performance product for your Branch account.
   1. Contact your Branch account manager or our sales team to get started.
3. Implement the Branch SDK into your mobile app (iOS | Android).

File Formatting

Before you can upload your CSV file, you need to make sure it is properly formatted and includes all the required information.

Template

To get started, download our cost data template CSV file.

This will give you the structure required by the file ingestor, and also contains the optional columns you can include.

File Requirements

• Your file can have any name, but it must be a CSV file and end with the .csv file extension.
• For every row in your CSV, you must fill out the following columns:
  • date (use the format YYYY-MM-DD)
  • campaign_name
  • cost (enter cost data in the format 1234.56 - do not include any currency symbols or commas)
• If you fill out data for the country_code field, you must use the country code with capital letters, i.e. FR or US.
• The os field must be one of the following: IOS, ANDROID, MAC_OS, WINDOWS, WINDOWS_PHONE, AMAZON_FIRE, AMAZON_FIRE_TV, ROKU, SAMSUNG, ANDROID_TV, LG, PANASONIC, TV_OS, CHROMECAST, PLAYSTATION, BADA, BEOS, BLACKBERRY, BSD, CENTOS, CHROMIUM_OS, DEBIAN, DRAGONFLY, FEDORA, FIREFOX_OS, FREEBSD, GENTOO, GNU, JOLI, KUBUNTU, LINUX, MANDRIVA, MEEGO, MINT, NETBSD, NINTENDO, OPENBSD, OS_2, RIM_TABLET_OS, SAILFISH, SLACKWARE, SOLARIS, SUSE, SYMBIAN, TIZEN, UBUNTU, UNIX, ZENWALK, XBOX, WEBOS, OTHER, ROBOTS.

Uploads

Let's walk through the features of the Uploads view, and see how to use each in turn.

First, navigate to the File Ingestion tab:

1. Go to the Branch Dashboard and use the left-side navigation bar to click on Ads, which is in the Channels & Links section.

2. Click on ROI Hub.

3. Navigate to the File Ingestion tab within ROI Hub.

   

File Upload

To upload ad partner cost data via the file ingestor:

1. Click on the Upload cost file button in the upper right-side corner.

   

2. You will be taken to the Upload cost file page, where you need to fill out:

   1. Ad partner (required)
   2. Default account ID (optional)
      1. You can find this on the Ad Partner Settings page for the ad partner.
      2. This is important if you are uploading data for the same ad partner multiple times, as it might override existing data uploaded.
   3. Default currency (required)
   

3. In the Select cost data file section, click the Upload button and upload your CSV file.

4. At this point, we recommend using the file validation feature to make sure your file is properly formatted before attempting to process it, since that can take several hours. To validate your file's formatting, click the Run quick validation button.

   

5. If your file is properly formatted, you will see a success message upon validation:

   

6. Now that you have validated the file, click Upload file to begin uploading your cost data.

   

7. You'll be prompted to either Upload another file if you want to add more data, or get taken back to the main File Ingestion tab view using the Go to History button.

   

8. If you click Go to History and return to the File Ingestion tab, you'll notice your file is now in the table and is in the pending state. Please note that it may stay in this state for several hours while the data is being processed.

9. Once your data is processed, it will get included in the data on the ROI Analytics tab.

View File History

Once you have kicked off the upload process for a file, it appears in the table on the File Ingestion tab.

To learn more about the file:

1. Click the View button in the Action column for the file you are interested in.

   

2. When you click this button, you will see file details appear in a module.

   

3. If you click View on a file that failed during the upload process, you will see what the error was that caused the failure.

   

4. You can also click Download file with errors to download a CSV file that contains all the data from your file alongside the errors that occurred when Branch tried to process it.

Filter Uploaded Files

Once you've uploaded some files containing cost data, you can filter them by different attributes. In the example below, we are filtering by ad partner "Impact" and status "Success":

You can also search for the file name if you know any part of it. Please note that this search is case-sensitive.

Error Handling

There are a few different errors that might occur during the upload process, which mainly have to do with formatting.

These are the errors messages you might see, as well as their corresponding meaning:

• Required fields are missing or formatted incorrectly: When any of the three required fields (date, campaign_name or cost) aren’t filled in or have the wrong format.
• Bad datatype or formatting detected: When the data in the column doesn’t match what’s expected (e.g. a value for currency is in the cost column).
• Fields contain values not currently supported: This is when the country or os column has a value that doesn’t match what is expected.
• Required fields do not exist in data file: This is when the column names date, campaign_name, or cost don’t exist in the file, or there are extra columns that don’t match the template file.