Справочники Sales Ninja

Справочники — самостоятельный публичный контракт Sales Ninja. Они не принадлежат карте спроса или другому отдельному продукту: каждый продукт только выбирает нужные оси и ссылается на общий код или словарь.

Что находится в разделе

Справочник	Что в нём искать
Аудиторные коды	Пол, возраст, устройство, покупательная способность, окружение и время
Интересы	Полное текущее дерево интересов: уровни 1, 2 и 3
Географические словари на этой странице	Страны, регионы и города конкретного контейнера

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

Какие бывают справочники

Значения имеют три разных режима. Режим определяет, где находится полный набор и как потребитель должен реагировать на новый код.

Режим	Примеры	Где находится полный набор	Что делать с новым значением
Закрытый	gender, ageBand, device, dayOfWeek	В справочнике аудиторных кодов	Не подменять похожим кодом; применить безопасное поведение продукта
Открытый нормализованный	browser, operatingSystem, operatingSystemMajorVersion	Набор заранее не закрывается; задан только формат	Принять корректно отформатированную строку
Контейнерный	country, region, city, interest	В dictionaries конкретной выгрузки	Загрузить словарь этой выгрузки до сопоставления условий

Закрытый справочник меняется только как версия контракта. Открытый справочник может получить новое корректное значение без изменения схемы. Контейнерный справочник путешествует рядом с данными, потому что его фактический состав зависит от публикации.

Структура потребления

контракт продукта
├── выбирает допустимые оси
├── использует общие аудиторные коды
└── прикладывает словари конкретной выгрузки
    ├── countries
    ├── regions
    ├── cities
    └── interests

Карта спроса, смарт-фид или будущий внешний контейнер не переопределяет значение кода. Если продукту нужен другой смысл, он вводит другую ось, а не меняет общий справочник под себя.

Географические словари

География образует связанное дерево country → region → city. Идентичность задаётся полем code; названия нужны только для отображения.

{
  "countries": [
    { "code": "RU", "name": "Russia", "russianName": "Россия" }
  ],
  "regions": [
    { "code": "moscow", "name": "Moscow", "countryCode": "RU" }
  ],
  "cities": [
    {
      "code": "moscow-city",
      "name": "Moscow",
      "regionCode": "moscow",
      "countryCode": "RU",
      "population": 13010112
    }
  ]
}

Коды в примере иллюстративны. Полный набор берётся из текущего контейнера. Связи строятся по countryCode и regionCode, а не по отображаемому названию. Поля russianName, englishName, nativeName и population могут отсутствовать.

Общие правила совместимости

1. Сравнивайте ключи и коды с учётом регистра.
2. Не переводите отображаемое название обратно в код.
3. Не заменяйте неизвестный закрытый код ближайшим известным.
4. Не отклоняйте всю выгрузку из-за нового корректного открытого значения.
5. Загружайте контейнерный словарь до условий, которые на него ссылаются.
6. Не сохраняйте и не восстанавливайте внутренние идентификаторы Sales Ninja.
7. Не превращайте отсутствие признака в отдельный код, если продуктовый контракт прямо его не ввёл.

Практический пример потребителя: контракт контейнера карты спроса.