Skip to content

Latest commit

 

History

History
142 lines (97 loc) · 5.98 KB

linker-id-receiving.md

File metadata and controls

142 lines (97 loc) · 5.98 KB
Raw

Linker ID Receiving

Overview

This document illustrates in detail how the linker param is constructed, so that analytics vendors or publishers implementing their own solutions are able to ingest this parameter on the destination page.

Format

The linker param will be formatted in the following structure:

<paramName>=<version>*<checkSum>*<idName1>*<idValue1>*<idName2>*<idValue2>...

The asterisk * is used to seperate each piece of data.

  • paramName - Name of parameter given in configuration.
  • version - The version of the linker used to create the param.
  • checkSum - A unique value generated by the linker. Details about how this value is generated are here
  • idName1*idValue1 This is where any key value pairs in the ids object will be included. The values will be "URL Safe" base64 encoded, while the keys will remain in their raw form.

Example

Take this example linker configuration:

"linkers": {
  "linker1" : {
    "ids" : {
      "cid": "CLIENT_ID(_ga)",
      "uid" "QUERY_PARAM(uid)"
    },
    "proxyOnly" : false,
    "enabled": true
  }
}

The above config would generate a parameter similar to the following: linker1=1*5epghs*cid*YW1wLVNsQjJnZmlpXzExZFdxdFNyM3pUNHc.*uid*MTIzNA...

There are several parts to this url parameter. First, the name of the param linker1 matches the name from the configuration above. The param value contains several pieces of data seperated by the *delimiter.

  • The first value 1 indicates the version number of the linker used.
  • The second value 5epghs is a checksum generated by the linker.
  • After that, the two key value pairs given in the ids object. The linker has resolved any macros that may exist, base64 encoded them in a url-safe format, and then appended them to the parameter. This results in cid*YW1wLVNsQjJnZmlpXzExZFdxdFNyM3pUNHc., and uid*MTIzNA...

Checksum

The checksum is a unique value generated by the linker that can be used to prevent accidental Id sharing. Publishers and/or anayltics vendors can generate this checksum on the destination page and ensure that it matches. Since this checksum contains a time input, a common practice is to check it against a few values generated by adding or subtracting a time tolerance.

It is generated from the following formula.

base36(CRC32(fingerprint*timestampRoundedInMin*key1*val1*key2*val2...))

  • fingerprint - A semi-unique value for page visitors. Generated by using User Agent + * + timezone + * + language.
  • minutesSinceEpoch - Time since epoch. Floored to minute resolution.
  • key1... - Each key value pair that will be passed along. The key will remain in its raw form, while the value will be url-safe base64 endcoded.
  • CRC32 - A standard CRC32 implementation.
  • base36 - The result of the CRC32 algorithm is base36 encoded.

You can find all the code for our implementaion in the linker.js

Test Cases

If you are implementing your own logic to verify these checksums, please ensure that you are using our test vectors located in test-linker.js

Receiving Linker Params on AMP Pages

The <amp-analytics>'s cookies feature can be used to extract information from the document url and write to the origin domain.

Configuration

A cookies example configuration looks like

'cookies': {
  'enabled': true,
  'cookieName1': {
    'value': 'QUERY_PARAM(example)',
  },
  'cookieName2': {
    'value': 'LINKER_PARAM(exampleParamName, exampleIdName)',
  },
}

The enabled value can be used to override default vendor settings.

Cookie Names

Each key within the cookies config object defines the cookie name. It's value needs to be an object. The key should be named value, and its value should be the macro that determines the information stored in the cookie.

Note: The following key values are reserved, and cannot be used as cookie names. They are ['referrerDomains', 'enabled', 'cookiePath', 'cookieMaxAge', 'cookieSecure', 'cookieDomain', 'sameSite', 'SameSite', 'secure'].

Cookie Values

Each cookie to write is defined by an object, where the value is defined by the required value field.

Two macros are supported for the value field. QUERY_PARAM and LINKER_PARAM.

If there's error resoving the value, or the value is resolved to empty string. Nothing will be written to the cookie.

SameSite Cookies

To specify a SameSite value for a cookie, include a key-value pair where the key is sameSite and the value is one of Strict, Lax or None. If sameSite is set to None, we pair it with the Secure attribute as recommended to prevent the cookie from getting rejected.

There are 2 ways to set SameSite cookies:

  1. Set the SameSite attribute for all cookies using the sameSite key and value as one of Strict, Lax or None in the cookies config object, such as:
'cookies': {
  'sameSite': 'Strict',
  'cookieName1': {
    'value': 'QUERY_PARAM(example)',
  },
  'cookieName2': {
    'value': 'LINKER_PARAM(exampleParamName, exampleIdName)',
  },
}

This will set SameSite=Strict for cookieName1 and cookieName2.

  1. Set or override the SameSite attribute using the sameSite key on an individual cookie object, such as:
'cookies': {
  'sameSite': 'None',
  'cookieName1': {
    'value': 'QUERY_PARAM(example)',
    'sameSite': 'Strict',
  },
  'cookieName2': {
    'value': 'LINKER_PARAM(exampleParamName, exampleIdName)',
  },
}

This will set the SameSite=None for cookieName2 and override cookieName1 to SameSite=Strict.

LINKER PARAM

LINKER_PARAM takes two arguments, the name and the value. It will verify the checksum and read the idName1*idValue1 key value pair from the linker param. The value ('idValue1' here) will be returned.