IdentityLink Extension is a program that is designed to further LiveRamp’s mission to make it safe and easy to connect the world’s data, people, and applications, and enables brand marketers to maintain addressability in a world where privacy regulation and third-party cookie restrictions are the new normal. 

IdentityLink Extension helps marketers maximize their ability to reach consumers and consumer devices (such as desktop or mobile devices) with LiveRamp by leveraging their own authenticated CRM, mobile, site login, or email data in a privacy-conscious manner. In doing so, participants and LiveRamp create a more connected, addressable ecosystem.

There are a number of benefits for you:

  • Increased Reach: Increase your reach and tie together a greater number of data points against your existing database
  • Deeper Insights: Gain deeper marketing insights and improve closed loop attribution of IdentityLink-based measurement workflows 
  • Enhanced Efficiency: Enhance marketing efficiency for use cases such as frequency capping and campaign suppressions.

LiveRamp's Process

The process that is followed varies depending on the type of data being contributed.

How LiveRamp protects data privacy: The online data you contribute will be obfuscated (double-hashed and salted) and then only used to create additional device linkages in our Identity Graph in a non-discoverable manner (i.e., no IdentityLink Extension contributor can be identified). The offline data you contribute will be stored securely in our Identity Graph. No PII (personally-identifiable information) is ever shared with other LiveRamp clients. 

Email Address Contributions

LiveRamp captures hashed email addresses in real time when a consumer logs in to your website or opens a marketing email where you’ve deployed our tag. We then salt and hash the email addresses a second time. LiveRamp uses this salted double-hashed email address to find the consumer’s corresponding LiveRamp IdentityLink (IDL). Once we find that IDL, we store the linkage between the IDL and the user’s cookie ID in our Identity Graph. This process takes milliseconds to complete. The salted double-hashed email that is used to perform this lookup is dropped, and never shared or saved to our Identity Graph.

Mobile Device ID Contributions

LiveRamp collects the hashed email addresses tied to mobile device IDs that you upload to LiveRamp in batch files, and then hashes the email addresses a second time. LiveRamp uses this double-hashed email address to find the consumer’s corresponding LiveRamp IdentityLink (IDL). Once we find that IDL, we store the linkage between the IDL and the user’s mobile device ID in our graph. The hashed email that is used to perform this lookup is dropped, and never shared or saved to our offline graph.

Offline Data Contributions

LiveRamp collects the linkages of two or more raw (unhashed) consumer PII touchpoints that you upload to LiveRamp in batch files and stores them in a secure internal environment. These linkages are added as additional PII touchpoints in our Identity Graph. The raw PII is never exposed when we match client data into the graph - the raw PII is first double-hashed and salted for the purposes of matching.

Overall Steps to Implement IdentityLink Extension

Contact your LiveRamp representative to get started with IdentityLink Extension, which includes the following steps:

  1. Sign IdentityLink Extension terms: If not already a part of your existing contract, sign IdentityLink Extension terms that grant us permission to use your data in our Identity Graph.
  2. LiveRamp Data Ethics reviews your privacy policy: We verify that your consumer-facing privacy policy has adequate language and opt out options, including  specifying how you’re using consumer data. We find that more than half of the time clients are already approved for one or more methods of contribution. If you’re not immediately approved, our Data Ethics team will provide you with specific language that we would suggest you use so that you are compliant with our match policies. 
  3. Implement the appropriate IdentityLink Extension channels: See the appropriate implementation sections below for instructions for the channels you will utilize. If you run into any issues while implementing IdentityLink Extension, email clientmatch@liveramp.com.

If you are currently onboarding PII-based data files with LiveRamp, the preferred method for your CRM data is for us to use those files to build offline linkages. If you choose to authorize that method, you only need to email clientmatch@liveramp.com and your Customer Success Manager to confirm your authorization.

4. LiveRamp resolves your data to LiveRamp IdentityLinks (IDLs) and stores additional IDL/device linkages in our Identity Graph. See the sections below for information on this process for the various IdentityLink Extension channels.

Integrating Offline Data

To integrate your offline data into IdentityLink Extension, we need to collect the PII touchpoints you have for your consumers. 

If you are currently onboarding PII-based data with LiveRamp, the preferred method is for us to use your onboarding files to build offline linkages. If you choose to authorize that method, you only need to email clientmatch@liveramp.com and your Customer Success Manager to confirm your authorization.

If you do not want us to use your onboarding files, below are instructions for how to send us your consumer PII data.

  1. Create a file containing all known PII touchpoints for the consumers in your CRM. Each record must include two or more PII touchpoints for that record to be utilized. Examples of PII touchpoints include:
  • Name and Postal Address (First Name, Last Name, City, State, Street Address, and ZIP Code)
  • Email Address
  • Phone Number

2. Format and name the file according to the instructions below. 

3. Upload the file to LiveRamp. 

Format the File

Files must strictly follow the guidelines listed below:

  • Your file must use one of our allowed delimiters (commas, tabs, or pipes), and be one of our allowed file types (.csv, .tsv, .psv, or .txt). We cannot accept Microsoft Excel (".xls" or ".xslx") files.
  • The delimiter must be consistent throughout the file. 
  • If any values contain the delimiter character (for example, a comma), ensure that those values are escaped with quotes. 
  • The file must be rectangular (have the same number of columns for every row). If you do not have information for any field in a given row, leave it blank.
  • Identifier data elements cannot span multiple columns (except for Name & Postal Address). 
  • Your file must contain the following columns:
  1. CCID (Client Customer ID) 
  2. FIRSTNAME
  3. LASTNAME
  4. ADDRESS1
  5. ADDRESS2
  6. CITY
  7. STATE
  8. ZIP
  9. EMAIL1
  10.  EMAIL2
  11.  EMAIL3
  12.  PHONE1
  13.  PHONE2

The first field ("Client Customer ID") is used as the audience key, allowing us to de-duplicate rows in the uploaded file (in case a file has multiple rows related to the same person). The entries in this field should be unique and persistent across all files you upload. Contact your LiveRamp representative if you are not using a Client Customer ID to identify records so that we can use a PII touchpoint as the audience key instead.

  • The first row of the file must be a header row. Files cannot be processed without a header row. Feel free to use the headers in the example as a template: 

CCID,FIRSTNAME,LASTNAME,ADDRESS1,ADDRESS2,CITY,STATE,ZIP,EMAIL1,EMAIL2,EMAIL3,PHONE1,PHONE2

  • File data example:

56498,Joe,Smith,123 Main Street,Apt 23,San Francisco,California,94108,joe@gmail.com,,,,

435276,Sally,Thompson,5 Park St,,Chicago,Illinois,60605,,,,,

  • Do not include segment data in the file.

Name the File

File names must be in the following format (.csv example):

LiveRamp_<Your_Company_Name>_IdentityLink_Extension_<MMDDYYYY>.csv

Do not use special characters or spaces in the filename.

File name example (.csv example):

LiveRamp_BobsAuto_IdentityLink_Extension_08012019.csv

Upload the File

Upload the file using LiveRamp’s SFTP server, your SFTP server, or our Connect UI. You can also have us pull files from an AWS S3 bucket. See “Ways to Get Your Data Into LiveRamp” for more information.

If you upload files via LiveRamp's SFTP server, the SFTP server and credentials to use for offline data files are different than the ones you might use to upload IdentityLink Extension mobile app files. Make sure to use the correct SFTP information.

Files uploaded to Connect cannot be larger than 500MB and file uploads to Connect cannot be automated. For these reasons, we recommend either uploading via SFTP or having us pull files from an S3 bucket.

  • To upload files using LiveRamp’s SFTP: Use the credentials provided for you by your technical contact once the privacy review has been completed and follow the instructions in “Upload a File Via LiveRamp’s SFTP”.
  • To upload files using your SFTP: Follow the instructions in “Upload a File Via Your SFTP”. 
  • To upload files using Connect: Log into Connect with the credentials provided for you by your LiveRamp representative and then follow the instructions in “Upload a File Via Connect”.

After uploading the first file, email the Client Match team at clientmatch@liveramp.com to confirm that you have uploaded a file.

For future uploads, you do not have to email LiveRamp to confirm that you have uploaded data.

Implementing the Website Tag

To utilize the site traffic from your website in IdentityLink Extension, we need you to deploy a tag onto your website. The IdentityLink Extension Website Tag is a line of javascript that transfers pseudonymized data to LiveRamp’s system in the form of a hashed email address / cookie ID linkage. It should be placed on your website and called wherever a user’s email addresses can be populated. 

To implement:

  1. Deploy the tag.
  2. Test your hash function.
  3. Test the tag.

Deploy the Tag

Once your LiveRamp rep has provided you with your tag ID, add the tag below to all website pages where a user’s email addresses can be populated. These might include the following types of locations:

  • Post-registration pages
  • Post-login pages
  • Returning-user pages

Tag:

<script src="https://pippio.com/api/sync?pid={TAG_ID}&it=4&iv={MD5}&it=4&iv={SHA1}&it=4&iv={SHA256}" async></script>

It is not important where on the page the javascript is placed. Generally, it is added to the universal footer or into a tag manager, such as Google Tag Manager.

A populated pixel might look like this:

<script src="https://pippio.com/api/sync?pid=2228&it=4&iv=3cb7232fcc48743000cb86d0d5022bd9&it=4&iv=790d12777b2a83253a14c748a1b1cb09b3a91cca&it=4&iv=899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6" async></script>

Here are the macro values you will populate:

  • {TAG_ID} is your tag ID. Replace this with the tag ID provided by LiveRamp. Email clientmatch@liveramp.com if you are unsure of your tag ID. 
  • {MD5}, {SHA1}, and {SHA256} are the three email hash types we accept. You must replace all three values with the respective hashes of the email address. To maximize addressability and, therefore, match rates and reach, include all three hash types.

Ensure all email addresses meet the requirements below:

  • The hash input is a valid, non-empty email address.
  • The email address is lowercased.
  • Any whitespace or extra text is removed from the beginning and end of the email address.
  • The email address is hashed via the appropriate function and produces the hexadecimal digest.

For privacy reasons, LiveRamp does not accept raw (plaintext) email addresses from IdentityLink Extension partners.

Test Your Hash Function

Hash the email address ‘Test@Foo.com’ to verify that your hash function is working properly. ‘Test@Foo.com’ should produce the following alphanumeric strings:

  • MD5: 3cb7232fcc48743000cb86d0d5022bd9
  • SHA-1: 790d12777b2a83253a14c748a1b1cb09b3a91cca
  • SHA-256: 899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6

Test the Tag

Once you have verified your hashes, test your implementation either on a staging site or “in the wild”. Use the steps below to conduct your audit.

  1. Open an incognito window in Chrome and navigate to a URL where the pixel has been placed.
  2. Open Chrome developer tools. In the ‘network’ tab check off "preserve log”.
  3. Click through until you’ve submitted a test email.
  4. Search for ‘pippio.com’ and/or your tag ID (listed as “PID number”) in the ‘network’ tab filter.

Confirm the items below from your test:

  • The pippio.com javascript tag is firing successfully with status 200 or 204.

  • The PID (tag ID) is correct.
  • The hashes are correct, lowercased, and trimmed.

Implementing the Email Tag

To utilize the email addresses from your marketing emails in IdentityLink Extension, we need you to deploy the IdentityLink Extension Email Tag in the header of your marketing emails. The tag contains a block of 5 image pixels that transfer pseudonymized data to LiveRamp’s system in the form of a hashed email address / cookie ID linkage. 

To implement:

  1. Deploy the tag.
  2. Test your hash function.
  3. Test the tag.

Deploy the Tag

Place the image pixels below within the HTML of your email templates. 

Tag placement: We recommend placing the pixels in the header of the email, since some email clients do not load images below the fold. However if formatting is a concern, you may place them at the bottom of the email body.

<img src="https://pippio.com/api/sync?pid={TAG_ID}&_=1&it=4&iv={MD5}&it=4&iv={SHA-1}&it=4&iv={SHA-256}" width="1" height="1" border="0" style="display:none;overflow:hidden">

<img src="https://pippio.com/api/sync?pid={TAG_ID}&_=2&it=4&iv={MD5}&it=4&iv={SHA-1}&it=4&iv={SHA-256}" width="1" height="1" border="0" style="display:none;overflow:hidden">

<img src="https://pippio.com/api/sync?pid={TAG_ID}&_=3&it=4&iv={MD5}&it=4&iv={SHA-1}&it=4&iv={SHA-256}" width="1" height="1" border="0" style="display:none;overflow:hidden">

<img src="https://pippio.com/api/sync?pid={TAG_ID}&_=4&it=4&iv={MD5}&it=4&iv={SHA-1}&it=4&iv={SHA-256}" width="1" height="1" border="0" style="display:none;overflow:hidden">

<img src="https://pippio.com/api/sync?pid={TAG_ID}&_=5&it=4&iv={MD5}&it=4&iv={SHA-1}&it=4&iv={SHA-256}" width="1" height="1" border="0" style="display:none;overflow:hidden">

Here are the macro values you will populate:

  • "{TAG_ID}" is your tag ID. Replace this with the tag ID provided by LiveRamp. Email clientmatch@liveramp.com if you are unsure of your tag ID. 
  • "{MD5}", "{SHA1}", and "{SHA256}" are the three hashes we accept. You must replace all three values with the respective hashes of the email address.
  • "&_=[1 to 5]" is the cachebuster. The cachebuster allows us to perform ID syncs with your partner destinations, so that we can deliver data for this consumer to those destinations on your behalf. Including all 5 instances of the tag will have the biggest boost to match rates. The “&_=” parameter helps us keep track of the simultaneous requests so that we call the correct partners for a sync.

Ensure all email addresses meet the requirements below:

  • The hash input is a valid, non-empty email address.
  • The email address is lowercased.
  • Any extra whitespace or text is removed from the beginning and end of the email address.
  • The email address is hashed via the appropriate function and produces the hexadecimal digest.

For privacy reasons, LiveRamp does not accept raw (plaintext) email addresses from IdentityLink Extension partners.

Test Your Hash Function

Hash the email address "Test@Foo.com" to verify that your hash function is working properly. “Test@Foo.com” should produce the following alphanumeric strings:

  • MD5: 3cb7232fcc48743000cb86d0d5022bd9
  • SHA-1: 790d12777b2a83253a14c748a1b1cb09b3a91cca
  • SHA-256: 899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6

 Test the Tag

To test the Email Tag, follow the steps below. 

  1. Send a test email with the image pixels to a webmail client that directly loads images, such as Hotmail, Outlook, AOL, or Yahoo. Note: Do not test using Gmail.
  2. Log in to the email account in a new Chrome incognito window.
  3. Open Chrome developer tools. Under the "network" tab, check off “preserve log”.
  4. Open the test email. Note: If the email client doesn’t display images by default, click the button to load images.
  5. Sort by "name" and scroll down to find "{sync?pid}". 
    • The "name" column should display the email hashes in the call after the "{iv=}" parameters. 
    • The "domain" column should read “pippio.com” for five calls, and each call should fire a status 302, 307, 200, or 204.

6. Locate the pippio.com pixel calls in the code. In the "elements" tab, search for “pippio.com”. Mouse-over the pixels to see where they are in the email. Make sure that there is nothing visible in the email body.

You may also have a LiveRamp account manager test the tag for you by sending a test email to "PippioTest@hotmail.com", "PippioTest@aol.com", or "Pippio.Test@outlook.com". Email the Client Match team at clientmatch@liveramp.com if you are sending a test email.

Uploading Mobile App Files

To utilize your mobile app activity in IdentityLink Extension, you must send log files of your mobile app registrations and logins to LiveRamp. LiveRamp transfers pseudonymized data to LiveRamp’s system in the form of a hashed email address / mobile device ID linkage. 

To implement:

  1. Format the file.
  2. Test your hash function.
  3. Name the file.
  4. Upload the file via SFTP. 

Format the File

Create a file that follows the guidelines listed below:

  • Deliver files in .psv (pipe separated value) or .csv (comma separated value) format, gzipped, with unix line endings.
  • Include all of the columns listed in the table below.
  • Provide all three hash types for email addresses. Make sure all email addresses are lowercased and all whitespace is removed before hashing.
  • Do not hash mobile device IDs.
  • Remove any duplicate records from your file. Leave the most recent timestamped record in the upload. 
ColumnHeader LabelDefinitionExample
Mobile Device IDadvertising_idThe mobile device ID (mobile advertising ID) of the device.69A2109A-0134-4EEC-B4AF-65855133B008
ID Typeid_typeMobile Device ID Type - Apple Identifier for Advertising (“IDFA”) or Google Android Advertising ID (“AAID”).IDFA
User Agentuser_agentUser Agent string of the device."iPhone 6; iPhone OS 9.2"
IP Addressip_addressIP address of the device (IPv4 or IPv6).70.212.10.74
TimestamptimestampUnix Timestamp (seconds since Unix epoch) of when the user was active/logged in.1455172609
MD5 Hashmd5_hashEmail address using MD5 hashing.a010407ea27f6a9ccc70e5d149a7818f
SHA-1 Hashsha1_hashEmail address using SHA-1 hashing3b31875f46abd81fb6c003d7a84492f6ef1b2d5e
SHA-256 Hashsha256_hashEmail address using SHA-256 hashing.7f0098da19b0f540dbcde477f969fec3e4d8b40f6d1686c6b24d4c2aaea48fea
Opted-Outopted-out“1” indicates that the user has explicitly opted out (otherwise the value should be  “0”). If “1”, all fields except Mobile Advertising ID and ID Type should be empty.0


File Examples 

Here is an example of what the header row should look like:

advertising_id|id_type|user-agent|ip_address|timestamp|md5_hash|sha1_hash|sha256_hash|opted-out

A populated row might look like this:

AEBE52E7-03EE-455A-B3C4-E57283966239|IDFA|"Mozilla/5.0 (iPhone; CPU iPhone OS7_1_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Version/7.0 Mobile/11D201 Safari/9537.53"|208.185.26.20|1441137534|3cb7232fcc48743000cb86d0d5022bd9|790d12777b2a83253a14c748a1b1cb09b3a91cca|899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6|0

Populating the User Agent 

The user-agent string describes the software (app or browser) and device of a user. This field allows LiveRamp to to perform additional validation on the mobile device IDs. 

We recommend that you obtain the user agent with the codes below.

For Android devices:

 final String userAgent = System.getProperty("http.agent");

 For iOS devices:

NSString *userAgent;

{

struct utsname systemInfo;

uname(&systemInfo);

UIWebView *webView = [[UIWebView alloc] initWithFrame:CGRectZero];

NSString *baseAgent = [webView stringByEvaluatingJavaScriptFromString:@"

navigator.userAgent"];

NSString *hardware = [NSString stringWithCString:systemInfo.machine encoding:

NSUTF8StringEncoding];

userAgent = [NSString stringWithFormat:@"%@ [FBDV/%@;PPOSDK/%@]", baseAgent,

hardware, kPPOSDKVersion, nil];

}

Populating the Opted-Out Column

The opted-out column should be set to ‘1’ only if you have a policy that allows your mobile app users to explicitly opt out of data collection. Click here for an example of an opt-out policy.  

Do not set the opted-out column to ‘1’ if you detect a ‘do not track’ or ‘limit ad tracking’ signal from the device or operating system. Do not send us any records for devices where you find ‘do not track’ or ‘limit ad tracking’.

Test Your Hash Function

Ensure all email addresses meet the requirements below before hashing:

  • The hash input is a valid, non-empty email address.
  • The email address is lowercased.
  • Any whitespace or extra text is removed from the beginning and end of the email address.

For privacy reasons, LiveRamp does not accept plaintext email addresses for the mobile implementation of IdentityLink Extension.

Hash the email address ‘test@foo.com’ to verify that your hash function is working properly. ‘test@foo.com’ should produce the following alphanumeric strings:

  • MD5: 3cb7232fcc48743000cb86d0d5022bd9
  • SHA-1: 790d12777b2a83253a14c748a1b1cb09b3a91cca
  • SHA-256: 899d3387a5c5a7555d51d2f0a0b7b50e397fe481fd9a58fafb389b7dc94e11f6

Name the File

Name your file using the exact naming syntax below. 

idlx_{TIMESTAMP}.psv.gz

Files will be rejected from our servers if a different syntax is used. 

"{TIMESTAMP}" = date and time on the Internet in RFC 3339 timestamp standard.

An example file name might look like this: 

idlx_2019-10-28T15:04:05.psv.gz

Renaming a File for Re-Upload

 A LiveRamp account manager may ask you to re-upload a file if the first upload fails. When you re-upload a file, be sure to give it a unique name. Once we process a file successfully, we will not reprocess another one with the same name even if it is modified.

For example, if you re-upload a file called ‘idlx_2015-11-02T09:07:15.psv.gz’ , change the name to ‘idlx_2015-11-02T09:07:15_part02.psv.gz’. 

Upload the File

Use your SFTP credentials and the information below to upload the file via SFTP. 

The SFTP server and credentials to use for IdentityLink Extension mobile app files are different than the ones for the LiveRamp SFTP server you might use to upload other LiveRamp files. Make sure to use the correct SFTP information.

We recommend using the open source client “Cyberduck”. 

  • Server: sftp.pippio.com
  • Port: 4222

Upload your files daily to maximize your match rates and device reach.

If you do not have credentials for this SFTP server, email the Client Match team at clientmatch@liveramp.com for assistance.

Your feedback is vital to improve our help content.

Updated 4/20/20.