Метка Openstat

Abstract

Метка Openstat предоставляет возможность точной идентификации переходов на целевой сайт с внешних ресурсов путем анализа только запросов к целевому сайту (не имея доступа к сведениям о том, что происходит на внешних ресурсах).

Введение

В данном документе описана формат метки версии 1.0. Нестрогое описание метки расположено в http://marker.openstat.ru/spec.html. Данный документ является точной и полной спецификацией, любые разночтения с другими источниками следует трактовать в пользу этого описания.

Формат метки

Метка Openstat представляет из себя строку символов из набора Unicode (Unicode). Строка состоит из 4 частей, разделенных символом ";" (U+003B SEMICOLON):

openstat_service

идентификатор сервиса, предоставляющего услуги

openstat_campaign

идентификатор рекламной кампании

openstat_ad

идентификатор рекламного объявления

openstat_source

идентификатор площадки, раздела, страницы, места на странице, на котором было показано соответствующее рекламное объявление

Внутри каждой частей разрешено использование любых символов из набора Unicode, за исключением:

• Управляющих и форматирующих символов (символов Unicode с General Category равной Cc и Cf)
• "&" (U+0026 AMPERSAND)
• ";" (U+003B SEMICOLON)
• "=" (U+003D EQUALS SIGN)

Каждая из частей может быть пустой.

Формальных ограничений на длину частей метки или всю метку не накладывается, но на практике всегда будут существовать ограничения на среду передачи метки, максимальную длину URL и т.д. Для безопасного использования метки рекомендуется ограничивать длину.

Кодирование метки

Для применения метки она записывается в виде последовательности байт в кодировке UTF-8 (UTF-8) и добавляется в URI страницы (URI), на которую будет идти ссылка. Т.к. происходит добавление в общем случае более широкого набора символов, чем допускается к использованию в URI, то метку необходимо кодировать одним из двух способов:

• Обычное URL-кодирование (Percent encoding) (URI, 2.1) — каждый из запрещённых в URI байтов заменяется на "%" и две шестнадцатеричные цифры. Этот способ облегчает отладку и визуальную идентификацию метки, т.к. большинство современных браузеров будут показывать такую метку в декодированном виде открытым текстом. Этот способ не рекомендуется к использованию, если в строке много символов, подлежащих кодированию (например, букв русского алфавита — в таком случае каждая буква, занимающая 2 байта в UTF-8, будет занимать 6 байт).
• URL-safe base64-кодирование (Base64, 5) — вся строка кодируется в соответствии с указанным алгоритмом. Это предпочтительный способ для кодирования меток, содержащих много не-ASCII-символов (в этом случае буква русского алфавита будет занимать 2⅔ байта). Алгоритм URL-safe Base64 по определению выдает строки, которые не требуют дальнейшего URL-кодирования для использования в URL.

Последовательность байт, полученная в результате такого преобразования называется закодированной меткой.

Сравнение способов кодирования:

Характеристика	Percent encoding	Base 64
Легкость визуальной идентификации, читаемость для посетителя сайта	Легко	Сложно
Длина получаемой метки в байтах
— при кодировании 1 символа, разрешенного в URI (1 байт UTF-8)	1	1⅓
— при кодировании 1 ASCII-символа, не разрешенного в URI (1 байт UTF-8)	3	1⅓
— при кодировании 1 символа русского алфавита (2 байта UTF-8)	6	2⅔
— при кодировании 1 символа иероглифического алфавита (3 байта UTF-8)	9	4

Добавление метки

После того, как подготовлена закодированная метка, необходимо добавить её в URI страницы (URI), на которую будет идти ссылка, одним из двух способов:

• Добавление в часть URI query в качестве одного из аргументов GET-запроса, т.е.:
  • если в URI отсутствует часть query — то она создается путем добавления к URI "?_openstat=" + закодированная метка.
  • если в URI присутствует часть query — то добавляется дополнительный аргумент путем добавления к URI строки "&_openstat=" + закодированной метки.
• Размещение в части URI fragment происходит путем замещения поля fragment целиком на строку "_openstat=" + закодированную метку. Такой способ не рекомендуется, т.к. при его использовании невозможно использовать поле fragment по прямому назначению.

Модифицированный таким образом URI готов к использованию в качестве ссылки, на которую нужно ссылаться из тех рекламных объявлений, которые отражены в метке.

Канонические алгоритмы

Во избежание различий в поведении различных систем, поддерживающих метку Openstat, все системы ДОЛЖНЫ (MUST) использовать для записи (кодирования) и чтения (декодирования) метки одни и те же канонические алгоритмы.

Кодирование метки

• ВХОД:
  • исходный_URI
  • openstat_service
  • openstat_campaign
  • openstat_ad
  • openstat_source
  • использование_base64
  • использование_fragment
• метка := openstat_service + ";" + openstat_campaign + ";" + openstat_ad + ";" + openstat_source
• ЕСЛИ использование_base64
  • ТО закодированная_метка := Base64 encode(метка)
  • ИНАЧЕ закодированная_метка := URL encode(метка)
• разобрать исходный_URI на компоненты: URI_scheme, URI_auth, URI_path, URI_query, URI_fragment
• ЕСЛИ использование_fragment
  • ТО
    • URI_fragment := "_openstat=" + закодированная_метка
  • ИНАЧЕ
    • ЕСЛИ URI_query — непустая, ТО URI_query := URI_query + "&" * URI_query := URI_query + "_openstat=" + закодированная_метка
• собрать URI_с_меткой из компонент: URI_scheme, URI_auth, URI_path, URI_query, URI_fragment
• ВЫХОД: URI_с_меткой

Декодирование метки

• ВХОД: URI_с_меткой
• разобрать URI_с_меткой на компоненты: URI_scheme, URI_auth, URI_path, URI_query, URI_fragment
• ЕСЛИ URI_query — непустая,
  • ТО
    • разделить URI_query по разделителю "&" (U+0026 AMPERSAND) и сохранить как список_пар
    • ДЛЯ КАЖДОЙ пары В списке_пар:
      • разделить пару на ключ и значение по разделителю "=" (U+003D EQUALS SIGN)
      • ЕСЛИ ключ равен "_openstat", ТО закодированная_метка := значение
• ЕСЛИ URI_fragment начинается с "_openstat="
  • ТО
    • закодированная_метка := подстрока URI_frag, начинающаяся сразу после "_openstat=" невключительно
• ЕСЛИ закодированная_метка содержит ";"
  • ТО
    • метка := URL decode(закодированная_метка)
  • ИНАЧЕ
    • метка := Base64 decode(закодированная_метка)
    • ЕСЛИ невозможно сделать декодирование, ТО метку невозможно декодировать
• разделить метку по разделителю ";" и сохранить как список_элементов
• ЕСЛИ список_элементов содержит ровно 4 элемента
  • ТО последовательно присвоить 4 элемента в (openstat_service, openstat_campaign, openstat_ad, openstat_source)
  • ИНАЧЕ метку невозможно декодировать
• ВЫХОД:
  • openstat_service
  • openstat_campaign
  • openstat_ad
  • openstat_source

Примеры

Приведенные ниже примеры можно использовать для тестирования корректности работы алгоритмов.

Корректные метки

URI	Метка	openstat_service	openstat_campaign	openstat_ad	openstat_source	Комментарии
http://www.example.org/path?_openstat=openstat.ru;camp1;ad1234;top-left-corner	openstat.ru;camp1;ad1234;top-left-corner	openstat.ru	camp1	ad1234	top-left-corner	Простая метка с использовании только допустимых в URL символов
http://www.example.org/path?key1=value1&key2=value2&_openstat=openstat.ru;camp1;ad1234;top-left-corner	openstat.ru;camp1;ad1234;top-left-corner	openstat.ru	camp1	ad1234	top-left-corner	Метка в query, добавленная к существующим аргументам
http://www.example.org/path?key1=value1&_openstat=openstat.ru;camp1;ad1234;top-left-corner&key2=value2	openstat.ru;camp1;ad1234;top-left-corner	openstat.ru	camp1	ad1234	top-left-corner	Метка корректно функционирует и при размещении в середине списка аргументов в query
http://www.example.org/path?_openstat=openstat.ru;;;	openstat.ru;;;	openstat.ru				Минимальная метка, заполнено всего 1 обязательное поле
http://www.example.org/path?_openstat=b3BlbnN0YXQucnU7Y2FtcDE7YWQxMjM0O3RvcC1sZWZ0LWNvcm5lcg	openstat.ru;camp1;ad1234;top-left-corner	openstat.ru	camp1	ad1234	top-left-corner	Обычная метка, закодированная в Base64
http://www.example.org/path?_openstat=openstat.ru;camp%201;ad%201234;top%20left%20corner	openstat.ru;camp 1;ad 1234;top left corner	openstat.ru	camp 1	ad 1234	top left corner	Метка с пробелами, URL encoded
http://www.example.org/path?_openstat=%D0%BE%D0%BF%D0%B5%D0%BD%D1%81%D1%82%D0%B0%D1%82.%D1%80%D1%84;1;ad%203;%D0%B2%D0%B5%D1%80%D1%85	опенстат.рф;1;ad 3;верх	опенстат.рф	1	ad 3	верх	Метка с русскими буквами и пробелами, URL encoded
http://www.example.org/path?_openstat=0L7Qv9C10L3RgdGC0LDRgi7RgNGEOzE7YWQgMzvQstC10YDRhQ	опенстат.рф;1;ad 3;верх	опенстат.рф	1	ad 3	верх	Метка с русскими буквами и пробелами, Base64
http://www.example.org/path?query#_openstat_openstat=openstat.ru;camp1;ad1234;top-left-corner	openstat.ru;camp1;ad1234;top-left-corner	openstat.ru	camp1	ad1234	top-left-corner	Метка, размещенная во fragment

Некорректные метки

Приведенные примеры некорректных меток ДОЛЖНЫ (MUST) игнорироваться любым алгоритмом декодирования — так, как если бы метки не было. Алгоритм кодирования должен не допускать создания таких меток.

http://www.example.org/path?_openstt=openstat.ru;camp1;ad1234;top-left-corner

ошибка в названии аргумента _openstat

http://www.example.org/path?_openstat=%1B;camp1;ad1234

метка содержит не ровно 4 поля

http://www.example.org/path?_openstat=%1B;camp1;ad1234;top;left;corner

метка содержит не ровно 4 поля

http://www.example.org/path?_openstat;camp1;ad1234;top-left-corner=

не задано обязательное поле openstat_service

http://www.example.org/path?_openstat=%1B;camp1;ad1234;top-left-corner

управляющий символ в поле openstat_service

http://www.example.org/path?_openstat=openstat.ru;camp%1B;ad1234;top-left-corner

управляющий символ в поле openstat_service

Библиография

Unicode

The Unicode Standard. http://www.unicode.org/versions/latest/

URI

Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, T. Berners-Lee, R. Fielding and L. Masinter. January 2005. http://www.ietf.org/rfc/rfc3986.txt

UTF-8

UTF-8: A Transformation format of ISO 1064. RFC 3629, F. Yergeau. IETF, November 2003. http://www.ietf.org/rfc/rfc3629.txt

Base64

The Base16, Base32, and Base64 Data Encodings. RFC 4648. S. Josefsson. SJD, October 2006. http://tools.ietf.org/html/rfc4648#section-5