Message PassingĪll messages to the API must be JSON strings consisting of a root object with a property/field named "PrivacyManagerAPI", which references an object, referred to as the "api object". An object is returned, containing only the field names specified below for each call, labeled 'returns'. Subsequent parameters sent are the ones required by the call, in the order expressed in this document. ) The first parameter passed is the call name. Function CallĪll calls to the API are made through this function : PrivacyManagerAPI.callApi(callName, arg1. This has the dual function of providing version control and allowing for abstract implementations of this API, should a publisher not wish to support all calls. This field will not be mentioned in the document call specs below, as it's in all calls. *unless otherwise authorized to do so API Call Technical InformationĪll API objects will be returned with an array of API calls ('action' parameters) that the Privacy Manager can accept, as a field named "capabilities". For this reason, it may be beneficial for first parties to use message passing as well. However, all parties which use message passing are automatically registered to receive updates when users change their preference.
Third party API callers can only ask about user permission for their own domains*, "their own domain" being the of the page (DOM) on which they are located. The recommended timeout delay is 100ms, but all API callers are encouraged to wait as long as possible. In this way, when loading something time dependent, a third party must implement a timeout mechanism to keep from waiting too long for a response. Realistically, one can expect a roundtrip of calls to take 1-10ms, in some cases with multiple page loads, this can be delayed to 50ms, and it's even possible on poorly designed pages to delay this several seconds.
First party scripts also have the ability to ask for permission for ANY domain, whereas a third party (message passing) can only ask for it's own permission*. Therefore whenever a first party needs the current user settings, the call must be made again.
Truste preference manager update#
When permissions are changed within the mechanism of the API, no notification or update is sent.
An analogy for message passing for non-technical individuals would be school room note passing amongst students. Details of this are to be described later in this document, but basically a "message" is sent from the third party to API, the API then sends a response message. The communication mechanism to be used by third parties (scripts/pages loaded within IFrames) is "message passing". This first party interface exists of only "getters", or calls to retrieve information. Interface into the API exists as one function for these parties, and the API blocks access to itself using any other means.
First party scripts are those that are loaded into the first party web page (DOM), and these parties can use a straight-forward function call, with the appropriate parameters, to retrieve API information. Two different methods are used, depending on the location of the party on the web page, to retrieve this information. This API's main function is to provide user privacy preferences to all parties. At this time, the preferences in the API pertain to any (non asset) information stored on a client machine, collectively referred to in this document as a 'cookie'. The scope of each instance of the API is the first party domain, including subdomain, on which it resides, but callers should not assume preferences to be persistent across session or even page loads. This document is to describe an overview of the design of this API as well as a light technical overview of the technologies involved. The purpose of this API is to facilitate distribution of user privacy preferences set through a website privacy preferences manager to all parties on a web page, so that these outside parties may honor the user's preferences.