In this guide, we will guide you through the steps to connect your custom media data to Billy Grace. We have this feature because 1) Billy Grace does not have a UTM for all channels, and 2) we want to allow users to import data from all channels as long as it's following a similar schema. 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 add it to Paid Performance; (if you send a correct bg_source parameter!)
E.G. bg_source=display&bg_source_id={ad_id}
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 media data is available for ingestion at the correct time. Data should reach us before 02:00 AM (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 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 (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 when you want MTA results otherwise optional |
Considerations
Example of subdividing when sharing radio data with Billy Grace.
source = radio
campaign_name = 538
This will show in Billy Grace like this:
Another example of Display advertising with multiple levels and a UTM:
In the above screenshots, the import table columns are:
Source = display
Campaign_name = campaign-name
Adset_name = adset-name
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).
The fields campaign, adset_id and ad_id are used as subsections in the data tables in Billy Grace. 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 hierarchy in your advertising. (see example below)
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.
If you are sharing TV or radio data, please input GRPs (Rough impressions for TV) or similar into the impressions' column.
We need at least 20 days of data (since pixel installation) before we can add it to the model.
Unified Marketing Measurement trains its models once a week on Thursday night. After uploading TV or Radio data, UMM results will only be available after the training moment on Thursday night.
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 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
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?
Follow these steps to share the specific table with schema from earlier in this article.
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.