In this guide, we will guide you through the steps to connect your online media data to Billy Grace. Custom Imports will grant you:
The ability for users to import data from channels that Billy Grace doesn't have an integration with.
Import results of custom online media solutions to gain insight in impression effects
By importing your online media in Billy Grace, we will be able to provide you with:
Insight into metrics such as (Blended) ROAS;
Incorporate it into our Multi-Touch Attribution and add it to Paid Performance*;
Model the effect of impressions on other channels in the Unified Marketing Measurement attribution model;
*MTA will only show results if you add the right UTM-parameters to your landing page URLs. Read on for examples on how to match the UTM with your import.
An example of online media data can be a marketing channel where Billy Grace doesn't have an integration with or any custom-made display network solution.
Importing media data is not available in all pricing plans. Please contact your Customer Success Manager for more information.
Import Method
There are two main ways of importing custom media data:
SFTP: you can share a daily .csv or parquet file with the orders.
BigQuery: you can share access to a BigQuery table, from which we will import the data.
It is essential that the data you share has the correct schema, so that we will be able to import it correctly. If you import data with an incorrect schema, we will not be able to ingest it into your dashboard.
Schema
The schema of the data we expect is listed below:
Field Name | Data Type | Description | Required |
source | String | Name of the channel you are connecting | Yes |
date | String | Date in format YYYY-MM-DD. | Yes |
clicks | bigint | Clicks | No |
impressions | bigint | Impressions | Yes |
spend* | float | Spend | Yes |
campaign_name | String | String containing the campaign name | Yes |
adset_name | string | String containing the adset name | No |
ad_name | string | String containing the ad name | No |
campaign_id | string/int | The ID of the campaign (add random if no ID is available) | Yes |
adset_id | string/int | The ID of the adset | No |
ad_id | string/int | The ID of the ad | No |
bg_source | string | String. The value you will send in bg_source= as parameter (i.e. bg_source=my_channel) | Yes for MTA results |
bg_campaign | string/int | The ID of the campaign or adset. | Only include if you don't have a unique ad_id. |
checkout_token | string/int | The ID used for purchase_started events | No |
*Should be separated by a point and not contain a currency symbol
Schedule the import
It is important that the media data is available for ingestion at the correct time. Data should reach us before 02:00 AM CET (containing the statistics of the day before).
For example: a file containing media data for the 29th of July needs to reach us before 02:00 AM on the 30th of July. If the data is not available at that time, there might be up to a week lag before you see correct attribution for this channel.
Furthermore, the CSV file must contain all the data you want to have in Billy Grace. If any data is no longer included in the CSV, it will not be part of the sync and will no longer be visible in Billy Grace.
Example of CSV import
The CSV template is attached to this knowledge article. You can find it at the end of the article.
Considerations
The fields campaign, adset_id and ad_id are used as subsections in the data tables in Billy Grace.
Example of Display advertising with multiple levels and a UTM:
The import table columns are:
Source = display
Campaign_name = campaign-name
Adset_name = adset-name
This will be displayed like this in reports:
etc.
Example UTM: bg_source=display&bg_source_id={ad_id}
Each channel should have only one import setup. It is not possible to create a new import for the same channel every month. If multiple imports are created for the same channel, we cannot identify that they belong to the same source. However, this is unnecessary because:
SFTP: You can simply place multiple files in the designated folder.
BigQuery: New data can be appended as new rows in the existing table.
It is not possible to include multiple channels within a single import (see the explanation above).
Campaign_id and campaign_name need to be filled. If you leave adset_id and ad_id fields empty, we will assign them with the values of the higher hierarchy.
We need at least 20 days of data (since pixel installation) before we can model results in the Unified Marketing Measurement (UMM) model.
Unified Marketing Measurement trains its models once a week on Thursday night. After uploading media data, UMM results will be available next Friday.
We expect ad_id to be unique and not shared among campaigns.
UTM For your import
If you want MTA to include click attribution for the imported channel, you need to send the bg_source and bg_source_id parameters. Example on how to send them:
Value from bg_source column (needs to be the same for all ads) = bg_source
Value from ad_id column = bg_source_id
Example
If you want to import the following display data:
The UTM parameters for the first ad (row) should be:
?bg_source=display&bg_source_id=ad_12
For the second ad the parameters should be:
?bg_source=display&bg_source_id=ad_13
If the ad_id in your import is not unique, you have to add bg_campaign into the UTM parameters. This has to match the bg_campaign import values. Example UTM: bg_source=display&bg_source_id={ad_id}&bg_campaign={campaign_id}
In the above example import, bg_campaign is not added to the import. But let's say for the first row there was another column with bg_campaign=5, the UTM would be:
?bg_source=display&bg_source_id=ad_12&bg_campaign=5
Import in Billy Grace
If you are finished with setting up the import, the data will be available in reports after 24 hours. Please take into consideration that the models behind UMM train once a week on Thursday, so when you add display data on Tuesday, UMM results will be available on Friday.
Unified Marketing measurement needs at least 20 days of data. Any upload with less than 20 days of data will not have significant UMM effects.
You can see the newly imported Channels and its results in the Paid Performance report.
How to connect via SFTP?
Navigate to Settings -> Import Custom Data. Here, you'll find personalized credentials, including a host, username, and password.
You're required to establish a daily file dump on your own, ensuring that a CSV or Parquet file, following the previously mentioned schema, is sent to us daily at the designated time.
Once set up, please create an export on the same page where you obtained your credentials by completing the form that appears when you click on 'Add Custom Import'.
How to connect via BigQuery?
First, upload the schema with the correct information into a BigQuery table.
Follow these steps to share the specific table with Billy Grace
Granting Permissions via IAM:
Go to the IAM & Admin section in their Google Cloud Console.
Click "Add" at the top of the IAM page.
Enter service account email (data-retriever@billy-grace.iam.gserviceaccount.com)
Assign appropriate roles that your service account needs to access the required resources (e.g., Viewer, Storage Object Viewer, etc.).
Click "Save".
Granting Permissions on Specific Resources:
If the service account needs access to specific resources, please grant permissions at the resource level (e.g., on a particular Cloud Storage bucket or BigQuery dataset).
For example, to grant access to a Cloud Storage bucket:
Go to the Cloud Storage section in the Google Cloud Console.
Select the bucket.
Click on "Permissions".
Click "Add" and enter your service account email (data-retriever@billy-grace.iam.gserviceaccount.com).
Assign the necessary roles (e.g., Storage Object Viewer).
Click "Save".
After completing this step, please navigate to Settings -> Import Custom Data and complete the form to activate your export.
Frequently asked questions
Is it correct that we will receive the data retrospectively from the import?
Spend, impressions and clicks will be available in reports based on the entire data import. This allows us to backfill all available data. This can only be attributed if the proper UTMs were sent.