# Getting started

Source: https://docs.ezoic.com/docs/identity/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
```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.setIdentity({
        email: PLAINTEXT_EMAIL
    });
});
```

### 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.

```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.setIdentity({
        md5: MD5_HASHED_EMAIL,
        sha256: SHA256_HASHED_EMAIL,
        sha1: SHA1_HASHED_EMAIL
    });
});
```

### 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.

```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.setIdentity({
        userid: USER_ID
    });
});
```

### 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](https://en.wikipedia.org/wiki/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`

```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.setPhoneNumber({
        phone: UNHASHED_PHONE_NUMBER,
        sha256: SHA256_HASHED_PHONE_NUMBER
    });
});
```

### 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.

```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.setPhoneNumber({
        userid: USER_ID
    });
});
```
### Deleting an Identity
If you need to remove a previously set identity from the page, you can call `deleteIdentity()`. This will clear any identity values stored in memory for the current session and remove any Ezoic Identity cookies / storage values that may have been created.

```javascript
window.ezoicIdentity = window.ezoicIdentity || {};
window.ezoicIdentity.queue = window.ezoicIdentity.queue || [];
window.ezoicIdentity.queue.push(function(){
    window.ezoicIdentity.deleteIdentity();
}); 
```

### 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.