Getting started

Overview

The Ezoic Identity product allows publishers to share a hashed version of a user's email with vendors such as Google and Prebid's User Identity modules and bidders. Sharing hashed emails or phone numbers can provide a large uplift as it allows advertisers to better reach their target audiences without the use of cookies. This document will guide you through the steps to get started.

Please ensure compliance with any applicable regulations regarding disclosures and obtain required consent before sharing user data with upstream vendors.

Passing Hashed or Unhashed User Emails

Call the following function to pass either sha256, md5, or sha1 hashes of a user's plaintext email address. You may also submit an unhashed email which Ezoic will hash for you for maximum coverage before passing it to our vendors.

Unhashed Email

1window.ezoicIdentity = window.ezoicIdentity || {};
2window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
3window.ezoicIdentity.queue.push(function(){
4    window.ezoicIdentity.setIdentity({
5        email: PLAINTEXT_EMAIL
6    });
7});

Hashed Email

When passing a hashed email address, please note the following:

  • Validate the email address, e.g., through use of a regular expression
  • Remove leading and trailing whitespace
  • Convert all characters to lowercase
  • hash the email using sha256, md5, or sha1 (sha256 is recommended)
  • In gmail.com email addresses, remove the following characters from the username part of the email address:
    • Periods: john.smith@gmail.com should look like johnsmith@gmail.com before hashing
    • Plus signs and any characters following up until the @: johnsmith+home@gmail.com to johnsmith@gmail.com

At least one hashed email address must be passed to the function. If you have multiple hashed emails, you can pass them all. SHA256 is recommended, but you can pass any combination of the three hashes.

1window.ezoicIdentity = window.ezoicIdentity || {};
2window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
3window.ezoicIdentity.queue.push(function(){
4    window.ezoicIdentity.setIdentity({
5        md5: MD5_HASHED_EMAIL,
6        sha256: SHA256_HASHED_EMAIL,
7        sha1: SHA1_HASHED_EMAIL
8    });
9});

Integrated Email Service IDs

If you've already integrated your email service provider with Ezoic, you can pass the custom user ID, also known by zuserid or zid, via the JS.

1window.ezoicIdentity = window.ezoicIdentity || {};
2window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
3window.ezoicIdentity.queue.push(function(){
4    window.ezoicIdentity.setIdentity({
5        userid: USER_ID
6    });
7});

Phone Number (Hashed or Unhashed)

When providing a phone number, you are able to pass in either a hashed or unhashed phone number. If you pass in only an unhashed phone number, Ezoic will hash it for you before passing it to our vendors. You are also able to hash the phone number yourself using the SHA-256 algorithm and provide only the hash when calling the function. When hashing the phone number, please note the following before hashing:

  • Ensure the phone number is in E.164 format, e.g., through use of a regular expression
  • E.164 phone numbers can have a maximum of fifteen digits
  • Normalized E.164 phone numbers use the following syntax with no spaces, hyphens, paraenthesis, or other characters:
    • [+][country code][area code][local phone number]
    • US Example: 1(234)567-8901 would be normalized to +12345678901
    • Signapore: 65 1234 5678 would be normalized to +6512345678
    • Sydney, Australia: (02) 1234 5678 is normalized to drop the leading zero for the city then prepend the country code to +61212345678
1window.ezoicIdentity = window.ezoicIdentity || {};
2window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
3window.ezoicIdentity.queue.push(function(){
4    window.ezoicIdentity.setPhoneNumber({
5        phone: UNHASHED_PHONE_NUMBER,
6        sha256: SHA256_HASHED_PHONE_NUMBER
7    });
8});

Integrated Phone Service IDs

If you've already integrated your phone notification service provider with Ezoic, you can pass the custom user ID, also known by zuserid or zid in the phone service provider, via the JS.

1window.ezoicIdentity = window.ezoicIdentity || {};
2window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
3window.ezoicIdentity.queue.push(function(){
4    window.ezoicIdentity.setPhoneNumber({
5        userid: USER_ID
6    });
7});

Testing

The function creates a cookie in the browser's session storage called ezidentity that holds the hashes that were passed through. To test the implementation simply look for the ezidentity cookie.