¶ Introduction to TrueLink
TrueLink is presently in its alpha phase. Participation in testing is limited to ID5 partners on an invitation only basis.
TrueLink is an additional client-side integration method that can complement a standard ID5 JS API or Prebid (version 9.2.0 and above) implementation. With a TrueLink integration, ID5 can create a cross-domain identifier called the TrueLink ID for a single user within a specific browser.
This TrueLink ID is utilized by ID5 for user identification and the generation of a high-quality ID5 ID. Publishers also have the option to access a publisher specific version of the TrueLink ID, which remains unique for a user across their owned and operated properties within a given browser environment. The client specific TrueLink ID can be used as a proprietary first-party identifier powering various use cases such as cross-domain audience building and activation, all without relying on third-party cookies. It may also be used as a PPID within Google.
¶ Library Source
The TrueLink bootstrap JavaScript library source code is accessible via a private GitLab repository. To obtain access, kindly contact your ID5 Representative and provide the email addresses of the users who require access to the repository.
We compile a minified, public version of the library directly from the repository and host it on our CDN at the following location: https://cdn.id5-sync.com/bootstrap/id5-bootstrap.js.
You should not use the library directly from our CDN. The TrueLink bootstrap library needs to be served through the domain of the webpage.
¶ Integration Guidelines
A TrueLink integration cannot be used independently of an ID5 JS API integration.
- The TrueLink bootstrap library must be served through a first-party domain. So if the webpage is
your-domain.comorsub.your-domain.comthe bootstrap library should be made available at eg.your-domain.com/id5-bootstrap.jsoryour-domain.com/assets/boot.js(thepathpart does not matter). The ways this can be achieved are described in the first-party hosting section. - The bootstrap library should be loaded and initialized in the
<head>section of the webpage, ideally before any other scripts, so the redirect (if it's needed) will happen as fast as possible and the browser won't start rendering content. It is required to pass your ID5 partner ID to the init method. For example, if your ID5 partner ID is99:<head> <title>Your domain</title> <script type="application/javascript" src="https://your-domain.com/id5-bootstrap.js"></script> <script type="application/javascript"> window.id5Bootstrap.initTrueLinkId(99) </script> </head> - The script will register a global object
window.id5Bootstrapwith methodinitTrueLinkIdwhich should be called directly after including the script. CallinginitTrueLinkIddoes few things:- The process checks whether ID5 has previously obtained consent on the page and whether the user has consented to ID5 (in applicable regions). If the user has consented and the TrueLink ID is either absent or requires a refresh, the redirect process will proceed. However, if there is no consent information or if the user hasn't consented to ID5, the redirect process will be terminated.
- Checks if there is a first-party cookie with the TrueLink ID - if yes (and it isn't expired), it returns, if not - it redirects the user to ID5 TrueLink server (https://id5-sync.com/true-link) which will redirect back to the original page with encrypted TrueLink ID in the URL.
- Checks if there is a TrueLink ID the URL - if yes, it sets it as a first-party cookie and returns.
- You must be using the latest version of ID5 API, available through our CDN
The id5-bootstrap.js operates using encrypted values of the TrueLink ID, which change with each call to the TrueLink endpoint even if the underlying value remains the same. These encrypted values are not intended for direct use. Instead, you should obtain the decrypted TrueLink ID using the ID5 API library methods like described in the example below.
¶ Serving id5-bootstrap.js as First-Party
The TrueLink integration library id5-bootstrap.js must be served as a "first-party" script in order to be able to work. In this sections we document a few possibilities.
¶ Proxy Method (Preferred)
We suggest proxying the TrueLink id5-bootstrap.js library version provided by ID5 through our CDN. This involves fetching the contents of the id5-bootstrap.js script from the CDN on demand or periodically and serving it as a regular asset on your domain.
Alternatively you can set up a proxy rule on your serving or load-balancing infrastructure.
The method for accomplishing this depends heavily on your specific technology stack. If you encounter any issues or have questions, please don't hesitate to reach out to us with a description of your tech stack so we can offer assistance.
This method is preferred since you will benefit from improvements ID5 makes to the id5-bootstrap.js library automatically.
¶ Static Method
An alternative method to achieve first-party hosting is to either copy the TrueLink id5-bootstrap.js library from our CDN or build it from source and then serve the content as you would for any other javascript asset on your webpage.
While this method gives you full control over the contents of the id5-bootstrap.js library, you will be required to update the contents of the script whenever ID5 makes changes to it (to introduce new functionality, bugfixes, etc.) as we don't support outdated integrations.
¶ Retrieving the Publisher-Specific Version of the TrueLink ID
¶ Id5 JS API
The publisher specific version of TrueLink ID will be available to retrieve through the ID5 API. After creating an ID5 API instance, upon availability of the ID5 ID you can can call the getPublisherTrueLinkId() method. If TrueLink was initialized and is available on a given page - it will be returned.
Example:
let id5Instance = ID5.init({partnerId: 173});
// You can use any of the available callbacks in the id5-api.js instance
id5Instance.onUpdate(function(){
let trueLinkId = id5Instance.getPublisherTrueLinkId();
});
¶ Prebid
The publisher specific version of TrueLink ID is available as a userId in prebid module if ID5ID module is enabled and TrueLink Id is integrated on a given page. To retrieve it you can use pbjs.getUserIds() under key trueLinkId or pbjs.getUserIdsAsEids() with source true-link-id5-sync.com.
TrueLinkId can be provided as a PPID - to use it, true-link-id5-sync.com needs to be provided as a ppid source in prebid userSync configuration:
pbjs.setConfig({
userSync: {
ppid: 'true-link-id5-sync.com',
userIds: [], //userIds modules should be configured here
}
});
¶ Metrics
ID5 recommends to continue collecting and monitoring your usual business metrics, such as traffic numbers by browser, and to let us know if you notice any impact.
¶ TrueLink Workflow
The below workflow describes how the TrueLink ID is generated and made available. Please note, users will only be redirected if there is no TrueLink ID set or it requires refreshing. Initially, ID5 only plans to refresh the TrueLink ID once per user per 7 days but may adjust this.
¶ Demo Pages
To illustrate how ID5 creates the encrypted and publisher-specific TrueLink IDs for users across publisher media properties, we created the following demo pages - Domain A and Domain B. To see the demo, please start with Domain A and follow the step-by-step commentary to learn more about the actions taking place on each page.