Introduction to TrueLink

TrueLink is an advanced client-side integration method designed to enhance your existing ID5 setup, whether you're using the standard ID5 JS API or a Prebid implementation (version 9.2.0 and above). By implementing TrueLink, ID5 generates a persistent cross-domain signal for individual users within a specific browser, fully independent of third-party cookies. This is achieved by redirecting users through an ID5-operated domain and storing the ID as a first-party cookie. ID5 leverages this deterministic signal to enhance user identification and produce a high-quality ID5 ID.

Since the ID5 ID is informed by signals derived from the TrueLink integration, publishers may want to optionally want to access a publisher first-party user identifier called the ID5 Guarded Publisher ID (GPID). The GPID is a publisher specific version of the ID5 ID which remains unique for a user across their owned and operated properties within a given browser environment. It's quality is implicitly linked to the provision of signals such as hashed emails and TrueLink signals. The GPID can be used to facilitate 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 Ad Manager.

During the beta phase and for a limited time, partners with owned and operated inventory integrating TrueLink can optionally access and use a partner-specific version of the TrueLink ID as a PPID. However, please note that since TrueLink is currently supported only in web environments, its coverage is more limited compared to the GPID.

Integrating TrueLink

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.com or sub.your-domain.com the bootstrap library should be made available at eg. your-domain.com/id5-bootstrap.js or your-domain.com/assets/boot.js (the path part 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 is 99:
```
<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.id5Bootstrap with method initTrueLinkId which should be called directly after including the script. Calling initTrueLinkId does 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.

TrueLink Integration