Guides

Media Delivery Integration Setup

Suggest Edits

The Media Delivery integration uploads information about transacted impressions into the Scope3 system for modeling and inclusion in reports, dashboards, and other analytic tools. The integration is set up and managed through Scope3's Integrate feature.

Media Delivery use cases

  • GMP reporting and compensation
  • Media Reporting
  • Custom reporting dashboards

The Media Delivery integration has many input parameters, and the data you choose to send will be based on your specific use case. We suggest learning more about Media Delivery here, where you can also learn what data input fields are required for this process.

Schemas allow the data fields in your input file to be automatically mapped to the fields required by Scope3’s Media Delivery Integration. To see all available fields for Media Delivery, visit this documentation.


Sample data and settings

Below is an example of Media delivery input data. The file includes impression delivery data for two publishers.
Field names cannot start with a number or character. For example, +datewould be invalid and fail to upload.

row_identifier  ,date       ,impressions ,inventory_id    ,channel ,country
theguardian-web ,2024-01-05 ,       1000 ,theguardian.com ,web     ,US
cnn-web         ,2024-01-05 ,       1000 ,cnn.com         ,web     ,US

If required, you can mark Media Delivery input data as GMP with the boolean flag of is_gmp.

You may also set all media delivery as GMP automatically by going to Settings > Integrations and toggling Categorize all "media delivery reports" as "GMP reports" under the Media Delivery Settings section.



1. Create a Schema Mapping

To begin, we will first create a new schema. Navigate to Integrate > Schema mapping and click the Add mapping button. From the Data Type drop-down field, select Media Delivery. Click the Choose File button and select the input file you want to use for your field mapping.


Details

In the Data Source field, provide a name for the schema, along with a Version and Description for it.

For the date field used in your input, select the correct date format, as incorrect format selection can cause errors.
The data format in our example data is yyyy-MM-dd. However, many other formats are supported in Scope3, as long as they are selected correctly in this process.

When all required fields are filled, click the Next button to continue to the next step.


Map Headers

The Map Headers section is where we will map the column headers from our uploaded file to the fields required by the Media Delivery API.
On the left side, you will see the headers of your provided file. On the right side, you will see dropdowns with the Scope3 fields that can be mapped to those headers.

From the Scope3 Field dropdown list, select the field that aligns with the headers in your file. The following Scope3 fields must be mapped to successfully import the data:

  • utc_datetime
  • impressions / plays
  • inventory_id / seller_name / seller_domain

Additionally, if your file contains specific values to map, you may enable the Map specific data values in addition to headers toggle. When enabled, the Map Values section will appear on the left side of the modal.

When all headers have been mapped to their appropriate Scope3 fields, click the Next button to continue to the next step.


Map Values (if toggled)

Value mapping enables you to bring in fields and values from your ad tech platform and map them to Scope3-acceptable fields.

Device types from platforms are often reported as mobile phone, desktop, connectedtv, iPhone
whereas Scope3 accepts fields for device type as phone, pc, tv

You can map your platform values to Scope3 values by inputting them into our accepted fields.
On the left side, you will see the fields to provide the values found in your uploaded file. On the right side, you will see dropdowns with the Scope3 fields that can be mapped to each value.

From the Scope3 Field dropdown list, select the field that aligns with the values in your file.
Value mapping is available for the following fields:

  • device_type
  • app_store
  • channel
  • transaction_method
  • network

When your values have been mapped to their Scope3-acceptable values, click the Next button to continue to the next step.


Export Fields

When all fields are mapped to your liking, continue by pressing the Export Fields button on the left side.
It is possible to map multiple input fields to a single Media delivery input. For example, both the domain and app bundle IDs can be mapped to the inventory_id input.

The export fields section is where you can configure the output report. Drag any fields you wish to see in the final report into the To be exported column. Consumer device emissions numbers can be added to a report here. Include parser_error and calculation_error if you wish to see detailed error reporting.

When the fields have been mapped, we can test the mapping to confirm that the headers have been mapped correctly.
If you do not wish to test your schema mapping file, click the Save button to finish saving your schema mapping. Otherwise, continue to the next step.

Test Mapping

To test a file using the schema mapping you've set, first click the grey box and select the file you would like to use as a test.
Press the Test Mapping button to process to the next step, where we will run the test.
Testing your schema mapping is optional, but Scope3 suggests regularly testing any new schemas to prevent any issues in your integration process.

📘

The test upload only allows files up to a specific size, which will depend on the amount of rows, columns, and content within the file. If you run into an error, Scope3 suggests reducing the file size used for testing and rerunning the test.

To run the test, click the Test File button. The test will begin immediately.

Once the test has been resolved, the results will be displayed in the Test results section, including any issues with the file. This will allow you to make adjustments and continue troubleshooting until you have a file suitable for use in Scope3.

Once you have reviewed your successful test results, click the Save button to finalize your schema mapping.

2. Upload

Now that we have a schema and a valid file that has been tested, we may upload the file(s) into Scope3 and see the emissions reports they generate.

Navigate to Integrate > Activity. Click the Upload file button, found in the upper right.

📘

Media delivery supports the following file types: .csv, .ndjson, .jsonl, .parquet, and .avro.

From the drop-down menus, please select the file’s Data Type and the Schema you created.
Once selected, click the Choose File button and select the file you want to upload.



When a file has been successfully uploaded, it will be marked as Pending Review and ready for you or a member of your team to review.


To validate and accept the file, click it in the list of uploaded files to open its Review Activity page. Please review all the upload details, including the total number of rows, the number of successfully uploaded rows, and a summary of impressions and inventory.

🚧

The file acceptance portion of the Review Activity page is a critical step in the integration setup process. Without file acceptance, the process cannot continue.


If you want to accept this file, please click the Accept this file option, click the confirmation checkbox, and then click the Save button.
Selecting Ignore this file will reject the file, leaving it unaccepted and unable to be reported upon. To reprocess the file, select the Reprocess this file option.

Once you have reviewed the activity and chosen to accept your file, click the Save button to finalize the process.

Congratulations! Your emissions data is now available in the CSP. You may now click the View Report button to open your emissions report.
You may download the report information by clicking the Download results button at the top right.

This system is sufficient for many users to get the required insights. For others, however, automating this process can reduce the manual effort of daily file uploads. To learn how to automate this process, please continue reading.


3. Add your bucket

Automations into Scope3 are dependent on cloud buckets. The process looks like the following:

  1. Input data is added to a cloud bucket that you manage.
  2. Scope3 reads the newly added data in that cloud bucket and calculates emissions accordingly.
  3. Emissions reports for newly added data are generated and posted back into your bucket.

To guarantee that data is written back to the cloud bucket, please add both the read and write permissions.

Navigate to Integrate > Cloud Storage. Click the Add Bucket button and select your appropriate platform from the Platform dropdown list.

Please provide that bucket's Bucket URL and Description, and select ‘Read/Write’ from the Permissions list.

When all fields have been filled and chosen, click the Add Bucket button.


4. Configure the automation

To create an automation, navigate to Integrate > Overview and click the Add Automation button.
Toggle whether your Uploaded files require manual review.

Select the Data Type from the dropdown, select the Schema and Bucket to use in this automation, and provide the file path for input files.
Also, please choose whether to Filter files by last modified date and, if so, provide the Last modified condition and Last modified date.

Choose whether to Write calculated files back to the bucket. If you choose to do so, please provide the Bucket, File type, Compression format, and the Path and file name to use when writing those files back.

🚧

Please use the {uuid} macro when providing the 'Path and filename' to prevent data from being overwritten in this process.

Click the Save button to finish saving this automation.

Now that the automation is saved, it can also be edited, refreshed, or disabled as needed by clicking the ... button and selecting the appropriate action.

5. Push the file

With the automation saved, we can push the file to our now-enabled cloud bucket. Each file should have a unique name. For example, if data is delivered daily, then scope3-delivery-data-2024-06-06 would be a sensible naming convention.

The Media Delivery integration checks your bucket every hour for new files. Duplicate files — those with the same file name — are ignored. Scope3 does not delete files from your bucket; you do not need to delete them manually.

Please navigate to the Integrate > Activity page, click the file, and accept it, as only accepted files can be pushed back.

📘

Disabling the Uploaded files require manual review toggle will allow for automating the file push in this process.

6. Review response

Scope3 checks buckets for new files every hour. For testing purposes, it may be beneficial to see more immediate results to review the success of the file push automation.
To immediately run the file check, click the Refresh data button, pictured below. The data will be pulled within a few moments.

Once the data has been pulled in, you can review how well the automation worked and feel confident that you will receive automated reports as expected.

Below is an example of a Media Delivery .csv report that has been pushed back to a bucket. It includes the export fields set when creating the schema.

channel ,country ,impressions ,inventory_id    ,utc_datetime        ,row_identifier  ,inventory_coverage ,emissions_breakdown                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ,emissions_framework   ,total_emissions_grams
web     ,US      ,       1000 ,cnn.com         ,2024-01-05 00:00:00 ,cnn-web         ,modeled            ,"[{""breakdown"":{""adSelection"":{""breakdown"":{""adPlatform"":{""emissions"":144.14783646188533}},""total"":144.14783646188533},""creativeDelivery"":{""breakdown"":{""adPlatform"":{""emissions"":0},""dataTransfer"":{""emissions"":0.4699678050999183}},""total"":0.4699678050999183},""mediaDistribution"":{""breakdown"":{""corporate"":{""emissions"":49.018915},""dataTransfer"":{""emissions"":0.5310414263298526}},""total"":49.54995642632985}},""framework"":""scope3""}]" ,scope3                ,  194.1677606933151
web     ,US      ,       1000 ,theguardian.com ,2024-01-05 00:00:00 ,theguardian-web ,modeled            ,"[{""breakdown"":{""adSelection"":{""breakdown"":{""adPlatform"":{""emissions"":25.889889979195292}},""total"":25.889889979195292},""creativeDelivery"":{""breakdown"":{""adPlatform"":{""emissions"":0},""dataTransfer"":{""emissions"":0.4699678050999183}},""total"":0.4699678050999183},""mediaDistribution"":{""breakdown"":{""corporate"":{""emissions"":49.018915},""dataTransfer"":{""emissions"":0.4171963981488689}},""total"":49.43611139814887}},""framework"":""scope3""}]" ,scope3                ,   75.795969182444068

FAQ

  • When using integrate and Media delivery for GMP, why do I see double the number of expected impressions in the GMP report? Scope3 shows impressions that are both pending review and finalized, so you can see what it would be before it's finalized.
  • Will files be deleted from my bucket when pulled into the Scope3 system with the Integrate automation? Your files will not be deleted. The information is copied, so your data remains safe and sound.
  • What is the file size limit for uploads into the cloud bucket? There is currently no hard limit, but we suggest keeping files to a maximum of 1GB.

Updated 2 months ago