Skip to main content

LiveRamp Local Encoder

The LiveRamp Local Encoder allows you to access some of the benefits of LiveRamp Onboarding or Addressability solutions without having to move your consumer data outside of your control.

Local Encoder enables you to generate securely-encoded RampIDs for your consumer data files within your own cloud environment and then utilize that data for onboarding or addressability use cases, depending on your needs. In this way your consumer data is never exposed to an external network, while still enabling full use of the LiveRamp solutions. The encoded RampIDs produced by the application cannot be decoded back to the original consumer identifiers.

Depending on your needs, the Local Encoder has several RampID output options that determine how Local Encoder generates your output file:

  • RampID packets: Used for Onboarding by brands and marketers, these RampID packets can be delivered to LiveRamp, where they can be transformed into RampIDs and used to generate fields and segments in your LiveRamp application.

  • Identity envelopes: Typically used by publishers and platforms who want to get RampIDs into the bidstream to safely engage with the programmatic advertising ecosystem.

    Note

    Identity envelope output is only available with Local Encoder Version 1.6 or later.

  • RampIDs: Typically used by publishers and platforms who want to create a RampID mapping.

See the diagrams below for the differences between LiveRamp-hosted ID creation and Local Encoder ID creation (RampID packet example shown).

I-Local_Encoder-LiveRamp_Hosted_ID_creationg.png
I-Local_Encoder-Local_Encoder_ID_creationg.png

Local Encoder is run as a Docker image, distributed via the AWS Elastic Container Registry. Local Encoder can be run on any infrastructure that supports running Docker images. Contact your LiveRamp representative to see if the Local Encoder is suitable for your needs.

For additional details, see the sections below. Once you're ready to deploy the Local Encoder, see the following articles for more information:

Local Encoder Security

No matter which method you use to implement the Local Encoder, the security protocols listed below apply.

  • Local Encoder is distributed as a Docker image. You obtain the Docker image from LiveRamp’s AWS ECR repository.

  • The application will need read-only access to an input location and write access to an output location. The input location is owned and controlled by you, and the output location is either owned by you or by the LiveRamp platform.

  • LiveRamp manages the keys and secrets. The application has read-only access to these resources.

  • The only network calls made are to cloud key management services.

Using Local Encoder for Onboarding

Brands or marketers can use Local Encoder to get their consumer data into LiveRamp for onboarding and activation at destination platforms without having that consumer data leave their environment.

For example, you might be a brand with CRM data who wants to send that data to destination platforms for targeting but not allow your consumer PII to leave your control. You can use Local Encoder to generate RampID packets containing derived RampIDs from your data files, which LiveRamp first ingests into your Connect or Safe Haven account and then uses to create segments from that data. You can then use your LiveRamp application to distribute those segments to your desired destinations, where they’ll be available for activation.

Note

For Onboarding use cases, you can receive RampID packets. You cannot receive RampIDs or identity envelopes.

Using Local Encoder for Addressability

Platforms and publishers can use Local Encoder to build a mapping between their platform users and RampIDs or identity envelopes without having consumer data leave their environment. This mapping can then be used to allow marketers to use LiveRamp to activate on RampID in their platform for improved matching. This mapping can also be used to transact on RampIDs (by means of identity envelopes) in the bidstream.

For example, you might be a platform who wants to transact on RampIDs in the bidstream with SSPs but not allow your consumer PII to leave your environment. You can use Local Encoder to generate identity envelopes (which contain derived RampIDs). These envelopes can then be used to create a mapping between your platform users and their envelopes. When a mapped user visits your website, you can pass their associated envelope into the bidstream, where they are utilized by SSPs in bid requests.

Note

For Addressability use cases, you can receive RampIDs or identity envelopes. You cannot receive RampID packets.

You might also want to create a mapping between your platform users and RampIDs so that brands and marketers can use LiveRamp applications to distribute segments tied to RampIDs to your platform.

How Local Encoder Works

Once you have the Local Encoder configured, the typical workflow consists of these overall steps:

  1. You format your consumer data file(s) and then upload them to the input location of your secure VPC (virtual private cloud).

  2. You run the encoding operation within your VPC:

    1. The data is normalized and hygiene is performed.

    2. The identifiers in the data are converted into derived RampIDs.

    3. If appropriate, the derived RampIDs for each record are encoded into secure RampID packets or identity envelopes.

    4. The input identifiers are removed and replaced with the appropriate RampID output type (RampIDs, RampID packets, or identity envelopes).

  3. For Onboarding use cases the following steps are performed:

    1. The output containing RampID packets is delivered to LiveRamp.

    2. LiveRamp decodes the RampID packets into their individual derived RampIDs.

    3. LiveRamp matches those derived RampIDs to their associated maintained RampIDs.

    4. LiveRamp creates the appropriate fields and segments from the segment data in your LiveRamp platform (such as Connect or Safe Haven).

  4. For Addressability use cases the following steps are performed:

    1. The output containing RampIDs or identity envelopes is output to the destination of your choice.

    2. You leverage the output to build a mapping table of your customer IDs to RampIDs or identity envelopes.

See the diagram below for an overview of the Local Encoder workflow.

I-Local_Encoder-Local_Encoder_workflow.png

Data You Can Send

The Local Encoder process starts when you upload a column-based file containing your customer records to an input location that you own and control. Each row of the file should contain the identifiers you want to have translated into your desired output. For Onboarding use cases, you can also include segment data which will be used to create fields and segments in your LiveRamp platform.

Supported identifier fields for translation to RampIDs:

  • Plaintext email addresses

  • SHA256-hashed email addresses

  • Plaintext phone numbers

  • SHA256-hashed phone numbers

  • Plaintext name and postcode (which consists of first name, last name, and postcode or ZIP Code)

  • Mobile device IDs (IDFAs and AAIDs)

Note

Name and postcode, mobile device ID, and IMEI are not supported for Addressability use cases. They are only supported for Onboarding use cases.

Other fields you can include:

  • Row IDs (RIDs)

  • Segment data (for Onboarding use cases)

Output Options

See the sections below for more information on the output options for Local Encoder. For examples of output files and more information on how they're created, see the "Output Examples" section below.

RampIDs

RampIDs are LiveRamp’s proprietary, pseudonymous identifiers for representing individuals. RampID creation involves hashing, salting, and private key encryption in order to prevent consumer data from being re-identified. RampIDs are unique per each LiveRamp client and have a partner-specific encoding.

For RampID output, all consumer identifier data in a row is transformed into derived RampIDs.

RampIDs form the basis for using the LiveRamp product. Once your data has been converted to RampIDs, you are able to use the LiveRamp platform for collaboration, activation, and measurement activities.

RampID Packets

For Onboarding use cases, Local Encoder can generate RampID packets by bundling individual RampIDs for a given consumer record and then adding an additional layer of encryption that involves a randomly-generated code. The randomly-generated code provides an added layer of protection, ensuring that the same client record (with the same RampID) will produce a packet which looks different every time the application runs.

The packets produced by the application are sent to LiveRamp, where they are unpacked and the included RampIDs are loaded into the client’s LiveRamp account.

Identity Envelopes

Identity envelopes are typically utilized by publishers and platforms who want to get RampIDs into the bidstream to safely engage with the programmatic advertising ecosystem or who want to enable brands and marketers using LiveRamp to distribute RampID-based data for improved targeting.

Note

Identity envelope output is only available with Local Encoder Version 1.6 or later.

An identity envelope is an opaque and encrypted structure containing RampIDs and metadata. Each envelope is created with a client-specific encryption key that makes it unique. An envelope is valid for 15 days from the date of creation (the output file contains the expiration date and time for each envelope).

Note

To refresh expired envelopes, reprocess the data.

For identity envelope output, all consumer identifier data is transformed into derived RampIDs. A selection logic is applied, and then the RampID is additionally obfuscated and encrypted into an identity envelope. Only one identity envelope is returned per row of data.

An envelope is represented as a Base64-encoded string.

Identity envelope string example

AY3SYJlFDI1RqsMv9gZOjOab6hGuwWKmbE4K70Z-Zex27DD6M9U0Jg

The string is different each time an envelope is created for the same underlying data as a result of randomization.

Envelopes can be decrypted using the Envelope Decryption API or by SSPs running the Sidecar application.

Output Examples

See below for examples of output files, based on output type.

RampID Packet Output

For RampID packet output, all consumer identifier data in a row is transformed into derived RampIDs, packaged into one data structure and encrypted again, yielding a RampID packet.

See below for an example of an output file for RampID packet output, based on the input file shown below:

RID|EMAIL1|MOBILE1|FIRSTNAME|LASTNAME|POSTCODE|DOG_OWNER|NUM_DOGS
123|solomon@mac.com|(629) 555-1536|Solomon|Gumbel|10012|true|3
456|maratb@gmail.com|(365) 555-0786|Marta|Baldwin|94602|false|0

The output file will follow the format shown below:

RID|RampID_PACKET|DOG_OWNER|NUM_DOGS
123|dVd8HezBpkyxiOpiUwh1+iYBBRx+RrBMM02rnvDoZT8i=|true|3
456|Tt16SRP6Svrnc2CQPrnHsLEcDR+WWLscjWdYmY2JR5h=|false|0

RampID Output

For RampID output, all consumer identifier data in a row is transformed into derived RampIDs in the form of a JSON string in a “RampID” column:

  • Each plaintext email address returns a derived RampID for each hash type (MD5, SHA1, and SHA-356)

  • Each SHA-256 hashed email address returns one derived RampID

  • Each phone number returns one derived RampID

See below for an example of an output file for RampID output, based on the input file shown below:

RID|EMAIL1|MOBILE1
123|solomon@mac.com|(629) 555-1536
456|maratb@gmail.com|(365) 555-0786

The output file will follow the format shown below:

RID|RampID

The JSON string might look like the example below:

RID, [
  {
    "header": "EMAIL1",
    "RampID": {
      "MD5": "Xi2247b9-ap-AcsWdsKFquY8vUnNig7fYQC-zkiqN9MKJQLvXaq_dppPrOiQBIy8PUYN2h",
      "SHA1": "Xi2247LbvDme7s-hRJXnG1NXe6CwFpRlNC60vFHOOpQXROEBiSF0LZYmdGYcbMcechi_iL",
      "SHA256": "Xi2247FbP--uJe0dFhLUrVD1MOTO6Iuncg5XbBOrR3MFywWgJMP9gzt2pdnVfCWQiUo-d_"
    }
  },
  {
    "header": "MOBILE1",
    "RampID": {
      "NONE": "Xi2247zPBI2V6OAVfpzBWhKy3ay8WJ66flt_1_hDYr0-y3mcf1HHDt2ZgRTyvhWxqp08Y0"
    }
  }
]

Identity Envelope Output

For identity envelope output, all consumer identifier data is transformed into derived RampIDs. A selection logic is applied, and then the RampID is additionally obfuscated and encrypted into an identity envelope. Only one identity envelope is returned per row of data.

An envelope is valid for 15 days from the date of creation. A timestamp column is appended to the end of each row. This column gives the expiration date and time for the identity envelope in Unix format (timezone UTC). You can use this timestamp column to determine when you need to refresh the envelope by reprocessing the data.

See below for an example of an output file for identity envelope output, based on the input file shown below:

RID|EMAIL1|MOBILE1
123|solomon@mac.com|(629) 555-1536
456|maratb@gmail.com|(365) 555-0786

The output file will follow the format shown below:

RID|ENVELOPE|TIMESTAMP
123|AY3SYJlFDI1RqsMv9gZOjOab6hGuwWKmbE4K70Z-Zex27DD6M9U0Jg|1701715163
456|ApKVQQBzOR41WDJQoK_iWEaJNsvVUcOHgOWEwB_SzNSRvHPNegb8-EpxIu3G-1ikxzGUwJZQcHOZLsZLySU|1701715163