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 Digital 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. Factual delivers a detailed analysis of your campaign's performance via a Measurement Intelligence dashboard. Through Factual’s partnership with LiveRamp, we are able to provide this offering to digital campaigns tied to any cookie or custom ID recognized by LiveRamp IdentityLink.

If you have ad exposure log files for your digital campaigns that are tied to a cookie or custom ID, 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 name, 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 using PlatformX, and it measured visits to Amy’s Back-to-Basics Hardware from Jan to Mar 2018, the filename should be: PlatformX-AmysBacktoBasicsHardware-Jan2018-Mar2018.txt

Note: You can only have one cookie partner or ID type per file. So if your ad exposures occurred on multiple platforms that use different cookies, you will need to submit a separate exposure file for each platform you used.

If your campaign was not delivered using a third-party platform, you can use the term Digital 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:

  • 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

Please refer to LiveRamp's documentation on File Formatting requirements for guidelines for formatting files to be processed by LiveRamp. For Factual’s measurement workflow, we recommend that your file be a tab-separated value (TSV) file. 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.

1Cookie or Custom_IDString; requiredThis is the cookie or “Custom ID” that you use to identify a user in your system. You are required to provide only one type of identifier per file, you cannot mix different cookie or ID types in the same exposure file.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)-

Note: For digital campaigns (non-TV), please include headers in the ad exposure file submitted to LiveRamp. Please also send your Factual account representative the ordered list of fields you will be using to ensure correct processing of your file. For example, if your file contains Cookie, Exposure_Timestamp and Campaign_ID (in that exact order), but no other fields, then tell your Factual account representative prior to submitting your exposure file to LiveRamp.

Example File

The following is an example of a compliant file for a digital 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      1495383384           campaignId1    placementId0    adId2
abc123      1495383384           campaignId1    placementId2    adId1
def456      1495383384           campaignId1    placementId0    adId3
def456      1495383384           campaignId1    placementId3    adId2
def456      1495383384           campaignId1    placementId1    adId4
ghi789      1499610910           campaignId1    placementId1    adId4
ghi789      1499610910           campaignId1    placementId4    adId0
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.

The final output will be a conversions data file (spreadsheet) and/or a campaign wrap-up report (pdf) analyzing the results of your campaign in driving traffic to the store. For more details on this deliverable (timing of delivery, sample report, etc.), please contact your Factual account representative.

Updated 10 months ago

MI: Submitting Digital 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.