Web SDK Quickstart

2.1 Quickstart for Web SDK

The ADARA Web SDK 1.0 is a client-to-server JavaScript SDK that enables you to:

1. Pass identity data such as user ID or SHA-256 hashed email
2. Pass detailed web events such as page view and search details
3. Request an ADARA Privacy Token

The SDK will pass the data to our privacy-safe data ingestion pipelines for secure onboarding. Then, the SDK will set cookies in the first-party context for only the domains and subdomains that you specify.

Step 1: Installing the SDK

Here is the default code for installing the SDK. The code can be placed in either the head or body of your web pages. This can also be done through your tag management system, such as Google Tag Manager, Tealium, etc. Be sure to pass the API Key as a string and the Data Partner ID (DP_ID) as an integer.

xxxxxxxxxx

<script>

  window.adara = window.adara ||

  function () {

    (window.adara.q = window.adara.q || []).push(arguments);

  };

  adara('init', 'REPLACE_API_KEY', REPLACE_DP_ID);

</script>

<script async src="https://js.adara.com/index.js"></script>

Step 2: Sending Identities

Use the identity method to pass the unique identifier for a single user. In the following example, the customer is passing an email as SHA-256 hashed value.

Our implementation is very flexible and driven by configuration. The configuration allows you to pass multiple objects or identities into the identity method. The only requirement for the identifier type is applicable to a unique user ID, such as SHA-256 email.

xxxxxxxxxx

<script>

  window.adara = window.adara ||

  function () {

    (window.adara.q = window.adara.q || []).push(arguments);

  };

  adara('init', 'REPLACE_API_KEY', REPLACE_DP_ID);

  adara('identity', {

    "email_sha256":"REPLACE_EMAIL_SHA256"

  });

</script>

<script async src="https://js.adara.com/index.js"></script>

We strongly recommend SHA-256 hash email. However, email can be passed in clear text, but we will not store it as clear text so your data is secure and user privacy is protected. Email may not be available if the user does not sign in or register. As an alternative, we ask that you add the unique user ID from your tag manager system, the analytics ID, or an unique user identifier that you use internally.

Here are recommended identifiers we expect to receive. We recommend sending SHA-256 hashed email and one of the other unique identifiers for cases when a user has not yet signed on. However, you can send more than one in any combination. The ADARA technical consultants can provide support if you have any questions.

Here is an example of the identity method with two identifiers. You can add an additional identifier by adding a new element to the second argument, which is a JavaScript map object.

xxxxxxxxxx

adara('identity', {

  "email_sha256":"REPLACE_EMAIL_SHA256",

  "visitor_uid":"REPLACE_UID"

});

The key names above are the recommended labels. However, our integration is configurable so it can handle the key names that match your data layer instead of being restricted to email_sha256 or visitor_uid.

Here are further details about recommended formats of identifiers and data elements.

Step 3: Sending Sessions

Use the session method to pass your identifier for the user web session. This is not required, but we recommend passing it. The session ID should be the string value of a number, an alphanumeric string, GUID, or any identifier of string format.

xxxxxxxxxx

<script>

  window.adara = window.adara ||

  function () {

    (window.adara.q = window.adara.q || []).push(arguments);

  };

  adara('init', 'REPLACE_API_KEY', REPLACE_DP_ID);

  adara('identity', {

    "email_sha256":"REPLACE_EMAIL_SHA256"

  });

  adara('session', 'REPLACE_SESSON_ID');

</script>

<script async src="https://js.adara.com/index.js"></script>

Step 4: Sending Event Data

The send method serves two purposes:

1. Sets the web data that represents the user interactions and events such as the email signup, search details, online purchase, etc.
2. Sends all data set by all the SDK methods: init, identity, session, send

Below is an example of the send method passing the parameters of a flight search.

xxxxxxxxxx

<script>

  window.adara = window.adara ||

  function () {

    (window.adara.q = window.adara.q || []).push(arguments);

  };

  adara('init', 'REPLACE_API_KEY', REPLACE_DP_ID);

  adara('identity', {

    'email_sha256':'REPLACE_EMAIL_SHA256'

  });

  adara('session', 'REPLACE_SESSION_ID');

  adara('send', {"event":"search",

                 "start_date":"2021-08-13",

                 "end_date":"2021-08-16",

                 "origin":"DFW",

                 "destination":"ORD",

                 "num_travelers":2

  });

</script>

<script async src="https://js.adara.com/index.js"></script>

In the previous example, the values were explicit and meant only as examples. The actual implementations will use your variables. The following example shows possible user-defined variables from a Google Tag Manager implementation. This is the typical implementation where the variables are passed as elements in a map object.

xxxxxxxxxx

adara('send', {"title":{{page_title}},

               "event":{{page_event}},

               "start_date":{{departure_date}},

               "end_date":{{return_date}},

               "origin":{{origin_airport}},

               "destination":{{destination_airport}},

               "num_travelers":{{num_passengers}}

});

You can also directly pass a data layer object in the send method. Please discuss this option with the ADARA technical consultant since they would then set up a configuration to transform the data for onboarding.

xxxxxxxxxx

adara('send', dataLayerObj);

Step 5: Requesting a Privacy Token

The identity method also allows you to tokenize your user identities and retrieve ADARA Privacy Tokens in return. The pattern for tokenization is as follows:

1. Pass an identifier, such as email address, for a single visitor in the identity method.
2. The SDK will invoke the Tokenization Service to create a token for the identifier. With our tokenization algorithms, the identifier will be converted into a token that is represented by an alphanumeric string.
3. The token will be written to the Look-up Service so the token can be later redeemed with the ADARA Identity Services.
4. The token will be written to the ID Graph so the submitted identifier can be connected to other identifiers for the person in the graph.
5. There is a parameter in the identity method that is a callback function which can be used to retrieve the token in the SDK code.
6. The management and storage of the token is determined by you for your own use cases. You will minimally need the ability to link the token value returned to the identifier that was submitted.

ADARA Privacy Token Overview

The ADARA Privacy Token offers a durable entity to exchange identities and data through a secure, privacy-safe mechanism. Each token will be unique to the requestor. Two organizations may have the same identifier, such as a hashed email, for the same person, but they will never have the same token.

A token is a handle into the ADARA Identity Graph that enables an access mechanism to a user’s identity, but no Personally Identifiable Information (PII) is exposed in the data exchange. You may have a data set of customers whose identities you have tokenized. You can pass a set of tokens representing those customers through the ADARA Identity Services. A partner that has also tokenized its data assets with ADARA can receive a list of your customers as a set of tokens so they can match it to their own customer data set.

The ADARA Identity Services will facilitate the token exchange by translating the tokens you submitted to a matching set of tokens for the receiving organization. Now, you are able to match your customers with another organization without any need to exchange PII.

Our initial release will support the tokenization of emails. You will receive a single token from a single email address. In the near future, we will support different identifiers like mailing addresses, phone numbers, membership account numbers, etc. This will open up data exchanges between organizations that may not have the same set of identifiers.

Here is the code sample for tokenizing a SHA-256 hashed email.

• We set the token value to the variable token. Use this variable to pass the value to a backend service.
• The last parameter is optional. It returns the error object for debugging.

xxxxxxxxxx

let token = "";

adara('identity', 

  {"email_sha256": "51294fa9e2aafaf3cd7294a327fb5a28d5856880f8f3678943f3f0896a5e776f"}, 

  res => token = res.data.token,

  error => console.log(error)

);

The above example was for SHA-256 hashed email. In the first release, we will also support clear-text emails.

As detailed in earlier sections, you can onboard other data in addition to identities. You would implement the send method after the identity method.

<script>

  window.adara = window.adara ||

  function () {

    (window.adara.q = window.adara.q || []).push(arguments);

  };

  adara('init', 'REPLACE_API_KEY', REPLACE_DP_ID);

​

  let token = "";

​

  adara('identity', 

    {"email_sha256": "51294fa9e2aafaf3cd7294a327fb5a28d5856880f8f3678943f3f0896a5e776f"}, 

    res => token = res.data.token,

    error => console.log(error)

  );

  adara('send', {});

</script>

<script async src="https://js.adara.com/index.js"></script>