TTD Connector for Databricks: Audience and conversion data SDK

NOTE: This guide describes one method for uploading offline conversion events. For all available methods, see Upload offline conversion events. If you're uploading event data as part of the product catalog integration workflow, first complete Step 2: Upload product catalog data.

The TTD Connector for Databricks enables you to onboard conversion or segment data to The Trade Desk from your Databricks account or to manage optouts and deletions.

This connector is a Python SDK that simplifies sending advertising data to The Trade Desk DSP. It can substantially reduce the time, effort, and complexity of authoring your integration. This SDK solution encapsulates complex functionality such as retries, external API handshake, and error handling.

IMPORTANT: Although this is a simplified solution, using it requires writing code, managing credentials such as secrets, and having a solid working knowledge of Databricks features such as notebooks and delta tables.

Your specific implementation of the SDK runs in your Databricks instance, and requires ongoing operational work.

Databricks marketplace listing

The following listing for audience and conversion data is available in the Databricks marketplace:

• TTD Connector: Audience & Conversion Data SDK

Key resources

Unlike other offerings from The Trade Desk that offer a higher level of assistance from The Trade Desk personnel, this solution is supported primarily by written documentation on the Python Package Index (PyPI) site and notes on the OpenTTD portal.

The following table provides information about additional key resources for getting started with The Trade Desk connector for Databricks.

Key capabilities

The TTD Connector for Databricks supports management of the following functions and types of data:

• First-party targeting data for advertisers and onboarders

• Third-party targeting data for data providers and commerce partners

• Offline conversion data for advertisers, providers, and commerce partners

• Deletion/opt-out workflows for managing advertising identifiers

• Automatic UID2 generation from hashed or unhashed email addresses or phone numbers (Email, HashedEmail, Phone, HashedPhone). The Data API SDK converts the data that you provide to UID2s before sending it to The Trade Desk, using the UID2 Operator that you specify in the UID2Config object. The SDK can also generate EUIDs if you are using an EUID Operator.

  NOTE: The Data API SDK never sends raw emails or phone numbers to The Trade Desk. It converts them to UID2s or EUIDs and sends the UID2s or EUIDs.

Authentication

Here's what you need to know about authentication for this SDK:

• The SDK uses API token authentication. This is the only valid method of authentication for the SDK.
• The token is required when you create the client; the same token is then automatically included with every request.

Deployment

The connector is distributed as a Python package (ttd-databricks) via PyPI and is designed to run inside a Databricks environment. The deployed package includes the following:

• A library of capabilities of the base implementation from The Trade Desk, managing fundamental aspects of sending audience and event data to The Trade Desk DSP.
• SDK usage examples that you can personalize for your specific implementation.

The connector supports the following processing modes:

• Ad hoc (push_data): This sends a DataFrame immediately and returns results inline.
• Batch (batch_process): This reads from a Delta input table and tracks progress across runs so that each execution only processes new records. Request batching, schema validation, and per-row error tracking are handled automatically.

To install, run this command:

pip install ttd-databricks

When installation is complete, you can use the TTD Connector for Databricks to send audience and conversion data to The Trade Desk Data API. For details, refer to the project page on the PyPI site or the GitHub README file: see Key resources.

Support

Full documentation is available in the package README on PyPI. It covers installation, available endpoints, schema requirements, error handling, and advanced configuration (custom HTTP client, server URL overrides, backfill runs).

Next steps

If you uploaded event data only for measurement, your integration is complete.

If you uploaded event data as part of a product catalog integration, the next step is to activate the data through your product catalog. To share access, continue to Step 4. Manage product catalog access. After an advertiser has access to the catalog, they can create product lists to build audiences and measure sales performance.