factual

Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

MI: Submitting TV Ad Exposure Data to Factual via LiveRamp

Factual's Measurement Intelligence solution enables you to measure the impact of your campaign by having Factual receive your campaign’s ad exposures and then tie them to post-ad-exposure store visits for attribution. Through Factual’s partnership with LiveRamp, we are able to provide this offering to the TV ecosystem in addition to digital campaigns.

If you have ad exposure log files for your TV campaigns that are tied to your custom ID (e.g. TV ID) and IP address, you can submit that data to LiveRamp who will then initiate Factual’s measurement workflow for your campaign. This document describes general guidelines for how to format your ad exposure files for delivery to LiveRamp.

Delivery Setup

If you do not have a LiveRamp IdentityLink agreement that covers exposure data use cases — Factual will create a LiveRamp IdentityLink client on your behalf and configure the SFTP filepath where you can upload your ad exposure log files. Please contact your Factual account representative for details on how to initiate this setup process. Note that this may take ~1-2 weeks to setup.

If you do have a LiveRamp IdentityLink agreement that covers exposure data use cases — Please reach out to your LiveRamp account team for specific details on how to initiate the LiveRamp IdentityLink for Measurement workflow with Factual.

File Naming

For the filename, please include the platform vendor, chain name, campaign start month, and campaign end month in the file name, separated by dashes (“-”). Use the following format: [PlatformName]-[ChainName]-[MonYYYY]-[MonYYYY].txt

Do not include any non-alphanumeric characters (spaces, underscores, apostrophes, etc.) in the platform name, chain name or in the start or end dates. As an example, if your campaign was delivered over a connected TV vendor called StreamXYZ, and it measured visits to Amy’s Back-to-Basics Hardware from Jan to Mar 2018, the filename should be: StreamXYZ-AmysBacktoBasicsHardware-Jan2018-Mar2018.txt

If your campaign was not delivered over a specific platform vendor, you can use the term TV in place of a platform name. If you are measuring visits to more than one chain, you can simply use the name of the largest chain or the name of the category in place of a chain name (e.g., HomeImprovementStores).

File Format

The exposure file you send to LiveRamp must be:

  • Pipe-delimited text file (.txt)
  • Rectangular (same number of fields in each row; individual records should be delimited by a newline)
  • Flat (no internal hierarchy)
  • No fewer than 25 records in length

Your file should contain the fields described in the table below.

You must ensure the columns in the exposure file(s) are ordered as indicated by the index numbers below.

IndexFieldTypeDescriptionExample
1Custom_IDString; requiredThis is the identifier that you use to identify a TV device in your system. It must be persistent and tied to the physical device itself (if the IP address changed, this Device ID would remain constant).abc123
2Exposure_TimestampString; requiredNumber of seconds since the Unix epoch — 00:00:00 UTC on 1 January 1970.1524252104
3Campaign_IDString; optionalCampaign identifier.BrandX_Campaign123
4Placement_IDString; optionalPlacement identifier.US_App_BusinessTravelers_25to40
5Ad_IDString; optionalAd creative identifier.320x50_BrandX_ProductZ
6Ext1String; optionalOptional custom parameter (up to 5 custom parameters supported)Channel X
7Ext2String; optionalOptional custom parameter (up to 5 custom parameters supported)Publisher Y
8Ext3String; optionalOptional custom parameter (up to 5 custom parameters supported)-
9Ext4String; optionalOptional custom parameter (up to 5 custom parameters supported)-
10Ext5String; optionalOptional custom parameter (up to 5 custom parameters supported)-
11Event_IDString; optionalA unique ID for each logged request.123456
12IP_AddressString; optionalIPv4 address on which the CID was observed (IPv6 support is in development by LiveRamp)11.12.13.14

Providing Control Group Exposures to Factual

If you have set aside your own control group for Factual to conduct a conversion lift study, you must designate a placement or placements for the control group and provide the corresponding ID(s) of those control group placements to your account manager. Control group impression data must follow the same format as described above. A timestamp must be provided. Impressions can either be included in the main exposure file or in a separate file. Factual will then be able to do the conversion lift study in the course of generating the Measurement Intelligence dashboard.

If you do not set aside your own control group, but want Factual to conduct a conversion lift study, Factual will to generate a control group for a conversion lift study.

Example

The following is an example of a compliant file for a TV campaign to be submitted to LiveRamp. Note the header is included in the first line of the file.

Custom_ID|Exposure_Timestamp|Campaign_ID|Placement_ID|Ad_ID
abc123|1495383384|campaignId1|placementId1|adId0
abc123|1496684990|campaignId1|placementId1|adId0
def456|1495383384|campaignId1|placementId1|adId0
def456|1496684990|campaignId1|placementId1|adId0
def456|1499610910|campaignId1|placementId2|adId1
ghi789|1495383384|campaignId1|placementId2|adId1
ghi789|1496684990|campaignId1|placementId2|adId1
ghi789|1499610910|campaignId1|placementId2|adId1

Additional Details

When setting up Factual measurement for your campaign, you will need to tell your Factual account representative what places you want to measure visits to (e.g., a nationwide retail chain, a retail chain’s locations in specific DMAs, etc.). We recommend utilizing locations from Factual’s Global Places for your campaign. If you need to use your own custom list of places, you may do so by following this guideline.

After your campaign’s end date, you will need to deliver the exposure file as described above. LiveRamp will then activate the IdentityLink for Measurement workflow with Factual and Factual will tie the matching store visits to the corresponding exposures for attribution.

Updated 10 months ago

MI: Submitting TV Ad Exposure Data to Factual via LiveRamp


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.