In this guide, we will guide you through the steps to connect your custom media data to Billy Grace. By syncing your media with 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 adding it to Paid Performance; (if you send a correct bg_source parameter!)
Model the effect of impressions on other channels in the Unified Marketing Measurement attribution model;
An example of media data can be TV advertising, radio advertising, DOOH or any custom-made display network solution.
Importing custom media data is not available in all pricing plans. Please contact your Customer Success Manager for more information.
There are two main ways of sending us 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 ingest it correctly:
If you share data with an incorrect schema with us, we will not be able to ingest it into your dashboard.
The schema we expect is listed below. Next to this, it is important that the orders are available for ingestion at the correct time:
Data should reach us before 3AM (containing the orders of the day before). For example, a file containing media data for the 29th of July needs to reach us before 3AM on the 30th of July. If you fail to do this, there might be up to a week lag before you see correct attribution for this channel.
More information on the specific schema we expect and how to connect the different methods is given below.
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 or GRP's | 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 | 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 when you want MTA results otherwise optional |
Considerations
The fields campaign, adset and ad indicate hierarchy we process them with, they can also be used for other items. I.e. if you are sharing radio data, you fill them with other data that indicates the hierachy in your advertising.
Campaign_id and campaign_name need to be filled. If you leave adset and ad fields empty, we will impute them with the values of the higher hierarchy.
If you are sharing TV or radio data, please input GRPs or similar into the impression's column.
We expect ad_id to be unique and not shared among campaigns. Please contact us when that is not the case.
If you want MTA to include attribution for the channel, you need to send with your UTMs the bg_source and bg_source_id parameters. Here, bg_source={bg_source} where {bg_source} is the value from your bg_source column (needs to be the same for all rows). Next to this, we expect bg_source_id={ad_id} where {ad_id} is the value in the ad_id column.
Example of hierarchy when sharing radio data with Billy Grace.
source = radio
campaign_name = 538
This will show in Billy Grace like this:
How to connect via BigQuery?
Follow these steps to share the specific table with schema from above.
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 you've done this, please share with us the following information:
the project name
the database name
the table name
How to connect via SFTP?
Contact our CSM team (support@billygrace.com). They will provide you with a host, username and password specific to you.
You need to set up a daily file dump yourself, where you ensure a CSV or parquet file containing the schema specified above reaches us daily at the correct time.
After setting it up, please contact us to send the naming structure you've chosen for the files (i.e. live_orders_<date>).