FreeWheel Data Suite

Reach streaming and CTV viewers by activating your audience segments across FreeWheel's premium video inventory.

Overview

FreeWheel Data Suite is FreeWheel's data activation offering for its TV platform. With the FreeWheel Data Suite destination, you can create segments in FreeWheel's Audience Manager and keep their membership in sync with your warehouse data, reaching viewers across streaming and connected TV inventory. If your model doesn't already contain FreeWheel-supported identifiers, you can enrich it with them using Match Booster.

Hightouch is a registered FreeWheel audience partner and delivers your data through FreeWheel's Audience Manager S3 ingestion pipeline. You don't need to provide AWS credentials or run any infrastructure of your own.

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Between runs, Hightouch computes which users entered or left your audience and delivers those changes to FreeWheel as incremental additions and removals. FreeWheel's detailed ingestion specification isn't publicly hosted; FreeWheel distributes it to partners during onboarding.

Connect to FreeWheel Data Suite

Before connecting, ask your FreeWheel account manager to enable audience delivery from Hightouch for your network. FreeWheel provisions your network ID for both its staging and production ingestion environments, and FreeWheel recommends validating your first syncs on staging before switching to production.

Go to the Destinations overview page and click the Add destination button. Select FreeWheel Data Suite and click Continue.

Enter the following fields into Hightouch:

• Environment: Which FreeWheel ingestion environment to deliver to, Staging or Production.
• Client network ID: Your FreeWheel network ID, which FreeWheel provides during onboarding. Use your own network ID for first-party data, or -1 to make segments available to all networks as third-party data. Staging and production use different network IDs, so update this field when you switch environments.
• Data provider name: An optional friendly name recorded as the data provider on the segments you create, typically your company name. If left blank, FreeWheel attributes segments to Hightouch as the delivering audience partner.

Deliver to a custom bucket

By default, Hightouch delivers files directly to FreeWheel's ingestion buckets for the environment you selected. If your FreeWheel arrangement instead ingests from a different location, such as an S3 bucket your company owns or a secondary bucket FreeWheel has assigned you, enter that bucket name or S3 Access Point ARN as the Bucket override under Advanced.

When delivering to a bucket your company owns, grant write access to Hightouch's delivery role by adding a statement like this to your bucket policy:

{
  "Sid": "AllowHightouchFreeWheelDelivery",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::010438485252:role/freewheel-datashare"
  },
  "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"],
  "Resource": [
    "arn:aws:s3:::your-bucket-name",
    "arn:aws:s3:::your-bucket-name/audience_partner=hightouch/*"
  ]
}

Hightouch writes all files under the audience_partner=hightouch/ prefix, following the same layout FreeWheel's ingestion expects. Coordinate with FreeWheel to confirm they ingest from your bucket before relying on this setup.

Sync configuration

Once you've set up your FreeWheel Data Suite destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the FreeWheel Data Suite destination you want to sync to.

Audiences

Create a FreeWheel segment and keep its membership in sync with your model, or manage the membership of a segment that already exists in FreeWheel.

Create a new segment

Creating a new segment is the most common configuration. Hightouch registers the segment with FreeWheel on every sync run, so its definition in FreeWheel always tracks your sync configuration. New segments are created with the ID hightouch-sync-<your sync's ID>.

Configure the following segment attributes:

• Segment name: If left blank, Hightouch uses the name of your model or audience. You can customize the name with templating, like Audience_{model.id}, and convey hierarchy with > separators, for example Provider > Category > Segment. See available variables in the filename templating docs.
• Segment description: An optional description of the segment in business terms.
• CPM price: The CPM price advertisers pay to use this segment. Leave blank for first-party segments that only their owner uses.
• Time to live (TTL) in days: How many days segment members persist in Audience Manager after ingestion before expiring, from 0 to 90. If left blank, FreeWheel applies the default TTL configured for your integration.

You can also set optional taxonomy attributes. Leave these unset unless FreeWheel has instructed you to use them:

• Use restrictions: Any value here prevents the segment from showing in FreeWheel's UI, for segments subject to data-policy restrictions.
• Custom: Mark the segment as a custom or first-party segment rather than syndicated.
• SPI Indicator: Flag the segment as containing sensitive personal information.
• Federated: Mark the segment as federated.
• Geo: For geo segments only, how FreeWheel should interpret the segment's external ID: zip code, postal code, or country.

Sync to an existing segment

To manage the membership of a segment that already exists in FreeWheel, select the existing segment option and enter its FreeWheel segment ID. Hightouch only delivers membership changes for existing segments; it never modifies the segment's name, pricing, TTL, or other attributes, so a segment created outside Hightouch stays exactly as its owner configured it.

Map ID types

Select one or more FreeWheel ID types to sync and map each to a column in your model:

• AAID (Android)
• IDFA (Apple)
• CTV device ID
• IPv4 address
• IPv6 address
• FreeWheel cookie
• Experian ID (LUID)
• LiveRamp ID (IDL)
• Tapad household ID

Hightouch delivers one membership file per ID type on each sync run. Columns containing arrays of identifiers are expanded into one identifier per row, so a single user can contribute several device IDs. All streaming device IDs, such as Roku, Fire TV, Samsung Tizen, and Apple TV, are delivered under the single CTV device ID type.

Configure delete behavior

Audience syncs run in All mode: users who leave your audience are automatically delivered to FreeWheel as removals on the next run. Under Advanced, you can also set a full resync interval, which schedules a periodic full refresh that re-delivers your entire audience. This is useful as a safety net in case FreeWheel's copy of the segment ever drifts from your model, for example after a segment reset on FreeWheel's side.

Tips and troubleshooting

Validate your setup

After your first sync completes, verify the results in FreeWheel:

• Find the segment in Audience Manager. Segments created by Hightouch have the ID hightouch-sync-<your sync's ID> and the name you configured, or your model's name if you left the name blank.
• Confirm the membership count is in the range you expect once FreeWheel finishes ingesting. Allow time for FreeWheel's ingestion to process newly delivered files before concluding that data is missing.
• If you started on the staging environment, repeat the validation after switching the destination to production. Remember that production uses a different client network ID.

If nothing arrives, confirm with your FreeWheel account manager that audience delivery from Hightouch is enabled for your network ID in the environment you selected.

Common errors

To date, our customers haven't experienced any errors while using this destination. If you run into any issues, please don't hesitate to reach out. We're here to help.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.