Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase
Guides
Submit a TicketBranch DashboardBranch Dashboard

Cost Data via Scheduled Ingestion

Automate funneling cost data into Branch by setting up a scheduled email cost ingestor.

Suggest Edits

Overview

ROI Hub's Scheduled Ingestion feature does several key things:

  1. It generates a unique email alias that you can give to your ad partner for them to send scheduled data to.
  2. Data sent to the email alias gets piped to your Branch Dashboard reports, where you can analyze campaign performance across multiple ad partners at once.
  3. It lets you test whether the format you and your ad partner are using to report cost data works with Branch.

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 start sending data to Branch through your email cost ingestor, you need to make sure the data 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 email cost ingestor, and also contains the optional columns you can include.

Share this file structure with your ad partner, as well as the requirements below.

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.

Scheduled Ingestion

First, navigate to the Scheduled Ingestion view:

  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.

  4. Click on the Scheduled Ingestion button to start configuring email cost ingestors.

Create Email Cost Ingestor

To create a new email cost ingestor:

  1. Click the Setup email cost ingestor button in the upper right-side corner.

  2. You will be taken to the Setup email ingestion page, where you need to fill out:

    1. Ad partner (required)
    2. 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. Currency (required)
    4. Email cost ingestor name (required)
      1. A unique name for your email cost ingestor.
      2. A name will be generated for you, which you can choose to use or edit.
    5. Permitted domains (required)
      1. Domains that you allow and that Branch should expect, for example monsterfactory.io.
    6. Expected frequency (optional)
      1. How often you expect cost data to get sent to Branch.

  3. The next step is optional, but we recommend uploading a sample CSV file that represents the kind of file you expect to be sent to Branch, so that you can validate the formatting.

    In the Test sample file section, click the Upload button to upload the sample file. Then click the Run quick validation button.

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

  5. Once your file has been validated, click the Generate Email Alias button. This button sets up the email ingestor and also creates an email address alias.

  6. Note the email alias that gets generated.

    You will need to share this email alias with your ad partner for sending scheduled cost data reports to.

Check Email Cost Ingestor Status

To check the status of an email cost ingestor that you have created:

  1. Return to the Scheduled Ingestion view of the File Ingestion tab.

  2. If you recently created a new email cost ingestor, you will see it in the table:

Email Cost Ingestor Status States

An email cost ingestor can be in one of the following states:

  • Pending: This is the initial state that the cost ingestor goes into when you create it. It means the ingestor has been set up, but no emails have come through yet.
  • Active: The first email has been ingested and there were no errors.
  • Error: The latest email ingestion attempt failed. Visit the Error Handling section for more.

Filter Email Cost Ingestors

Once you've created several email cost ingestors, you can begin to filter them by different attributes. In the example below, we are filtering by ad partner "All" and status "Pending":

Error Handling

If your email cost ingestor is in the Failed state:

  1. Visit the Uploads view and find the file that failed.

  2. Click on View in the Actions column for the row that represents the file that failed.

  3. You will see a detailed view of what caused the file to throw an error during ingestion.
    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.

Updated about 1 month ago