Version 3 (Latest)

First party API / Microprofile

As discussed in the previous version 2, most common use for first party microprofile is to store CMP consents and other metadata on it. In version 3 we have added a whole new set of features to manage observations, consents and key rings with in the microprofile.

New features:

  • Supports Key Rings, Consents and events
  • Data compression enabled by default
  • Third-party to First-party ID fusion
  • More options to get the audit trail.

The data properties of the Version 3 of the api looks like below.

{
  "i": "<microprofileid>",
  "r": "<originDomain>",
  "v": "v3",
  "e": {
    "key1": "value1",
    "key2": "value2"
  },
  "k": [ //key value pairs
    {
      "i": "keyId",
      "k": "KeyName",
      "v": "keyValue",
      "t": <timestamp>
    },
    {
      "i": "keyId",
      "k": "KeyName",
      "v": "keyValue",
      "t": <timestamp>
    }
  ],
  "c": [
    {
      "i": "consentId",
      "c": "consentName",
      "s": true,
      "t": <timestamp>
    },
    {
      "i": "consentId",
      "c": "consentName",
      "s": true,
      "t": <timestamp>
    }
  ]
}

The property values in the V3 are mainly short forms to reduce space in the requests. You can refer the full form here.

Timestamp for each entity is auto-generated by Gravito 1st party end point itself to help you keep track of different values when merging data across domains.

  • k : Key Rings
    • i: Key Id
    • k: Key Name
    • v: Key Value
    • t: Timestamp
  • c: Consents
    • i: Consent Id
    • k: Consent Name
    • v: Consent Value
    • t: Timestamp
  • e: Events
  • i: Id
  • r: Referrer
  • v: version

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:

(function gtoFirstPartyV3() {
    var xhr = new XMLHttpRequest();
    var params = {
    "e": {},
    "k": [],
    "c": []
    };

    xhr.open("POST", "https://gto.<<domain>>/api/v3/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(JSON.stringify(params));
})();

Please get in touch with is for a detailed Postman collection to get details of different use cases of this API. We will be happy to help. We can help you get started with sample GTM tag samples which enables simple profiling to complex cases which can enable Thirdparty to FirstParty Id fusion.

Connect cookies across domains

Under the Key value pair ("e"), similar to the version 2 you can still use the matchOnId to connect profiles to different domains. This for example can be done using a users Id when they login. (e.g. logged in user has UID known) 

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. A user with a matchOnId can be dealt with in 3 different ways to change the particular Id associated in 3 different ways.

  • reset
    • Reset value for the matchOnId can be used to clear all the values from the events key value pair temporarily.
  • disconnect
    • Disconnect value for the matchOnId can be used to remove the matchOnId from the events key value pair.
  • delete
    • Delete keyword for the matchOnId can be used to delete the whole events and the existing microProfileId provided.
    • This operation will reset the microProfileId and give you a new one.

Note: In all these cases passing the matchOnId value for a particular ID (e.g. logged in user has UID known) can resurface the whole profile again for your convenience.