@ken-e/dataform-dv360

Dataform package for processing Display & Video 360 (DV360) data exported via Instant Reporting to BigQuery.

Prerequisites

Before using this package, you must configure a DV360 Instant Report to export daily to BigQuery. This package reads from the report table — it does not read from the DV360 API BigQuery Connector (entity) tables directly.

Setting up the DV360 Instant Report

1. Link BigQuery to DV360:

   • In DV360, go to Partner Settings (or Advertiser Settings) > Linked Accounts
   • Click Link New Account > BigQuery Exporter
   • Enter your BigQuery Project ID and Dataset ID
   • Grant the DV360 service account these IAM roles:
     • BigQuery Job User on the project
     • BigQuery Data Editor on the dataset

2. Create the Instant Report:

   • In DV360, go to Reports > Instant reporting tab
   • Create a new report with these settings:

   Dimensions: | Dimension | Required | |-----------|----------| | Date (UTC) | Yes | | Advertiser | Yes | | Advertiser ID | Yes | | Campaign | Yes | | Campaign ID | Yes | | Insertion Order | Yes | | Insertion Order ID | Yes |

   Metrics: | Metric | Required | |--------|----------| | Impressions | Yes | | Clicks | Yes | | Media Cost (USD) | Yes | | Total Conversions | Yes | | Click-Through Conversions | Yes | | View-Through Conversions | Yes | | Revenue (USD) | Yes | | Post-Click Revenue | Recommended | | Post-View Revenue | Recommended | | Active View: Eligible Impressions | Recommended | | Rich Media Video Plays | Recommended | | Rich Media Video Completions | Recommended |

3. Run an initial backfill:

   • Set the date range to cover all historical data you need
   • Export once to BigQuery to create the historical table

4. Schedule daily incremental:

   • Create a second report (or schedule the same one) with a 14-day rolling window
   • Set schedule to Daily
   • Export to BigQuery

Installation

npm install @ken-e/dataform-dv360

Usage

const dv360 = require("@ken-e/dataform-dv360");

dv360({
  startDate: "2024-12-01",
  daysBack: 14,

  sources: [
    {
      database: "my-project",
      reportSchema: "dv360_reporting_dataset",
      reportTable: "my_dv360_report_table",
      advertiser_id: "1234567890",
    },
  ],

  target: {
    database: "my-project",
    stagingSchema: "my_staging",
    outputSchema: "my_output",
  },
});

Output tables

| Table | Description | |-------|-------------| | dv360_campaigns | Campaign-level daily performance (aggregated from insertion orders) | | dv360_insertion_orders | Insertion order-level daily performance |

Configuration

| Field | Required | Default | Description | |-------|----------|---------|-------------| | sources | Yes | — | Array of source definitions | | sources[].database | No | target.database | BigQuery project with DV360 data | | sources[].reportSchema | Yes | — | Dataset containing the DV360 report table | | sources[].reportTable | Yes | — | Name of the DV360 Instant Report table | | sources[].advertiser_id | No | — | DV360 advertiser ID (for documentation) | | target.database | Yes | — | BigQuery project for output | | target.stagingSchema | No | "propeller_dataform_template" | Staging dataset | | target.outputSchema | No | "propeller_dataform_template" | Output dataset | | startDate | No | "2020-01-01" | Earliest date to process | | daysBack | No | 14 | Rolling refresh window (days) |