First party API

First party domain means the domain your website operates. e.g. website.com. To avoid third party cookies being blocked (occurs already on many browsers) you can configure the CMP to set the cookies under first party domain or you can use Gravito’s first party API to store and retrieve other valuable profile data.

To get started with first party setup, you first need to set up domain in Gravito’s admin panel, https://admin.gravito.net

Setup of first party domain, step 1.

Once you have configured your domain gto.website.com, you need to do the DNS changes for your domain. These steps are varying between different DNS providers, generally you have to configure three records:

First party domain configuration, step 2.

After you have made the DNS records (A, TXT and CNAME), allow the changes to propagate to DNS servers (few minutes at least) and then press “Validate” button. After succesful validation you should see domain status as “Validated”:

First party domain configuration, step 3.

Now you are ready to go and consume the first party API services. There are two layers on it.

  1. First party microprofile, ie. persistent first party, server side cookie is set to store identity for the device on that particular domain and simultaneously the cookie is able to host other data like identities (keyring), events or segments.
  2. First party CDP profile, same as above but data is stored to backend system and consumable not only by the client but also orchestration on Gravito backend.

First party API / Microprofile

Most common use for first party microprofile is to store CMP consents and other metadata on it. That configuration is automatically generated by CMP configurator, just select “with backend” option when generating the deployment script and choose right first party domain from the menu.

If there would be other needs to use microprofile to act as keyring store, store context analytics results (e.g. segments) or something similar, the calls to first party API microprofile would look something like this:

Get profile

(function gtoFirstParty() {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://gto.<<domain>>/api/v2/firstparty', true);
  xhr.withCredentials = true;
  xhr.onreadystatechange = function(response) {
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {
      console.log("1P echo : " + response.target.response);
    }
  }
  xhr.send();
})();

Send data to profile

(function gtoFirstParty() {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://gto.<<domain>>/api/v2/firstparty?attribute1=value1', true);
  xhr.withCredentials = true;
  xhr.onreadystatechange = function(response) {
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {
      console.log("1P echo : " + response.target.response);
    }
  }
  xhr.send();
})();

Connect cookies across domains, this can be done e.g. using user ID:
(function gtoFirstParty() {​
  var xhr = new XMLHttpRequest();​
  xhr.open("POST", 'https://gto.<<domain>>/api/v2/firstparty?matchOnId=123', true);  ​
  xhr.withCredentials = true;​
  xhr.onreadystatechange = function(response) {​
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {​
      console.log("1P echo : " + response.target.response);​
    } ​
  }​
xhr.send();​
})();

matchOnID is the only reserved key value pair, it allows retrieving the cookie set for particular ID (e.g. logged in user has UID known) from other domain.

First party API / CDP profile

To extend the use cases from microprofling to full device (and account) profile(s) stored into Gravito CDP you can alter above calls to:

Get CDP profile

(function gtoFirstParty() {​
  var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://gto.<<domain>>/api/op', true);
  xhr.withCredentials = true;​
  xhr.onreadystatechange = function(response) {
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {​
      console.log("1P echo : " + response.target.response);​
    }
  }
  xhr.send();​
})();

Send data to profile

(function gtoFirstParty() {​
  var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://gto.<<domain>>/api/op/listen?attribute=value', true);
  xhr.withCredentials = true;​
  xhr.onreadystatechange = function(response) {​
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {​
      console.log("1P echo : " + response.target.response);​
    }​
  }​
  xhr.send();​
})();

Get CDP profile with full history

(function gtoFirstParty() {​
  var xhr = new XMLHttpRequest();
  xhr.open("POST", 'https://gto.<<domain>>/api/op?includeSharedProfileHistory=true', true);
  xhr.withCredentials = true;​
  xhr.onreadystatechange = function(response) {
    if(xhr.readyState == XMLHttpRequest.DONE && xhr.status == 200) {​
      console.log("1P echo : " + response.target.response);​
    }
  }
  xhr.send();​
})();