Sync Injector

Explaining MetaRouter's Sync-Injector and how to use it.

Overview

This guide is intended to provide an overview of MetaRouter’s Sync Injector and how it interacts with the browser, its calls and cookies, and the critical IDs they contain. It also describes how the Sync Injector functions within the MetaRouter Platform and how it is configured.

What is the Sync Injector?

The Sync Injector is a client-side library that builds a comprehensive partner identity graph within the 1st-party context of your site, and passes that graph through with all events your MetaRouter cluster and its server-side forwarders. This allows MetaRouter to empower server-to-server identification and attribution within your advertising and marketing tools in the absence of client-side tags and libraries.

The Sync Injector also ensures a significant improvement in page performance, as it is able to cache retrieved (or posted) identities for a customizable time-frame (eg. 180 days), and diminish the total number of repeated or duplicative identity requests made from the page.

MetaRouter negotiates these specific identity and attribution pathways with each vendor it builds integrations with, to ensure that both the vendor and our customers maintain maximum attribution when moving to this more secure and performant server-to-server integration framework. MetaRouter keeps these identity pathways up to date with its integration partners, so customers don't have to.

How Does the Sync Injector Work

The goal of the Sync Injector is to centralize key identifiers and parameters that are typically handled by 3rd-party tags and libraries. These IDs are collected and negotiated using a wide variety of methods, which MetaRouter allows its customers to tune and configure based on their preferences. While key identifiers and parameters are traditionally stored within disparate cookie spaces, URL parameters, and data layers, the Sync Injector enables the translation and organization of that information into a highly available and addressable graph within each event.

The Sync Injector is a lightweight Javascript library that is served to the page from a client’s domain, typically along with the MetaRouter Analytics.js library. On page initialization of brand new user sessions, the Sync Injector performs a number of vendor-specific actions with 3rd-party vendors before events are generated within the browser, and stores those values either as 1st-party cookies or rows within IndexedDB, depending on the customer's preference. Some examples of these actions include:

  • Setting anonymous External IDs with vendors to power vendor-side match tables.
  • Making sync calls to translate 3rd-party cookies to the 1st-party context, such as those placed by advertising platforms like DSPs and DMPs.
  • Making sync calls to translate 2nd-party cookies to the 1st-party context, such as those placed by social media platforms or direct ad channels.
  • Scraping URL, UTM, or click parameters and storing them in the 1st-party context.
  • Requesting or delivering Hashed PII.
  • Requesting global ID or cohort-based identities, like Google's FLoC, TradeDesk's UID 2.0, or Neustar's Fabrick.
  • Requesting, setting, or capturing other critical IDs or parameters necessary from the client, such as consent data, session logic, or probabilistic information.

On subsequent page sessions, if MetaRouter cannot find the necessary identifying information that a given vendor requires, then MetaRouter will begin executing collection processes for the vendors that the Sync Injector has been configured for.

If it does find all the IDs it needs, it will do nothing. First-party Sync Injector data will continue to persist until the cookie is either expired or deleted. MetaRouter provides a default age for the values based on vendor preference, but this can be overridden by customers.

How Do I Use the Sync Injector?

The Sync Injector is a component of the MetaRouter Analytics.js file that we provide you with and can be enabled upon request. If used alongside the MetaRouter-provided Analytics.js file, the Sync Injector will automatically perform all functionality on its own upon initialization.

For non-Analytics.js event streams, the Sync Injector will provide a callback function. The callback executes after identity syncing is complete, and returns the identity graph in the form of a JSON object - making it enrichment into the customer's chosen event stream simple.

How Do I Know the Sync Injector Is Working?

The result of a successful ID sync is the placement of the retrieved vendor IDs into your initial event payload. The IDs are inserted into a providers object, which is included along with the rest of a user's events. Those IDs, as previously mentioned, are retrieved from a vendor, stored in a first-party cookie, and pulled into an event whenever one is triggered by the user.

When your events are generated, you should see a new object in the event payload that looks something like this, except with your chosen vendors' IDs included:

"providers": {
     "google_doubleclick": {
       "dclid": "123abc",
       "external_id_set": true
     },
     "mediamath": {
       "mm_uid": "xyz123",
       "mm_clickid": "456abcdef"
     }
  }


# data and structure simplified for example purposes only

Sync Injector-Compatible Integrations

The Sync Injector currently is compatible with the below integrations. Keep in mind that we are constantly adding new compatible integrations:

Sync Injector / Client-Side Identity Graph Frequently Asked Questions

Is this exclusive to Web Applications, or is it also available for Mobile Applications?

The Sync Injector is not available for Native Mobile Applications as it is not necessary to create a Client-Side Identity Graph on the device. Instead, Mobile Device OS provide a Mobile Advertising ID that is used to attribute marketing behavior for an individual that is unique to their device. This is the standard for Mobile Applications and is the preferred Mobile ID for Vendors.

Using the Mobile Advertising ID does require the phone owner's permission before it can be accessed and shared, an action that is seen as an opt-in. The Mobile SDKs that are compatible with the MetaRouter platform will automatically collect and append this ID to events once a user provides permissions. Typically, the SDKs will locate these IDs within context.device.advertisingId. You can review all available fields for context.device, which manages device marketing IDs and preferences, by reviewing our Common Fields documentation.

Keep in mind when designing your data schema that Mobile Advertising ID is not a replacement for User or Anonymous ID, just a supplement that can be shared with Marketers when the user opts in.