Метка 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
Topic revision: r1.1 - 04 Apr 2011
 

Copyright 1999-2016 © by Openstat
Есть идеи, вопросы или проблемы, связанные с Openstat? Свяжитесь с нами