Получение подсказок при вводе ФИО

Ахантер позволяет ускорить и упростить заполнение форм, где среди прочих контактных данных персоны нужно указать её фамилию, имя и отчество. Ускорение происходит за счёт использования подсказок, которые наш сервис формирует на лету при вводе человеком своего ФИО.

В данной статье рассказывается, как использовать подсказки от Ахантера, если в вашем приложении или веб-сайте ФИО вводится в одно поле одной строкой. Если ваша форма содержит отдельные поля для фамилии, имени и отчества, то для получения подсказок следует использовать дискретные подсказки, описанные здесь.

Чаще всего наши подсказки для ФИО используются на веб-сайтах интернет-магазинов, когда покупатели оформляют заказ. Также наши подсказки используются в точках реализации кредитных продуктов банков и микрофинансовых организаций, где при оформлении заявки на кредит приходится вводить ФИО клиента. Правильно и быстро ввести ФИО клиента не так-то просто, поскольку при вводе сложных имен возможны ошибки и опечатки. Поэтому, чтобы гарантировать отсутствие ошибок в ФИО клиентов и покупателей, лучше организовать ввод этих данных с помощью подсказок от Ахантера.

Как работают подсказки ФИО

Для получения подсказок мы реализовали в Ахантере специальную функцию, которая предлагает пользователю список наиболее вероятных вариантов завершения ФИО, вводимого им в настоящий момент. При наличии среди предложенных вариантов требуемого, пользователю нужно лишь выбрать его из списка и перейти к вводу следующей части ФИО.

Приведенная ниже форма демонстрирует работу данной функции. Для отображения списка подсказок достаточно начать вводить ФИО в следующее поле.

Варианты в списке ранжируются по убыванию их популярности. При поиске и ранжировании учитывается как самостоятельная популярность предлагаемого варианта завершения вводимой части ФИО, так и его сочетаемость с уже введенными частями. Сочетаемость компонентов имени подразумевает учёт следующей информации.

• Соответствие пола (все компоненты ФИО должны относиться к одному и тому же полу).
• Соответствие национальности (компоненты ФИО с высокой вероятностью относятся к одной и той же или близким национальностям).
• Естественность порядка следования (порядок следования компонентов фамилия-имя-отчество является часто используемым, в то время как вероятность встретить вариант имя-фамилия-отчество очень мала).

Таким образом, если пользователь ввёл, например, грузинское мужское имя, далее ему будут предлагаться подсказки с грузинскими мужскими отчествами и фамилиями. При генерации подсказок учитывается, что слова, составляющие имя (как завершенные, так и вводимое в настоящий момент), могут содержать ошибки. При выполнении поиска осуществляется автоматическое исправление этих ошибок.

Здесь для отображения подсказываемых имён используется наш JavaScript-модуль ahunter_suggest.js, скачать его можно по следующей ссылке. Модуль использует библиотеку jQuery, поэтому, чтобы запустить подсказки у вас на сайте, в дополнение к ahunter_suggest.js нужно будет установить свежую версию jQuery.

Чтобы всё это заработало, мы использовали здесь следующий JavaScript-код.

//готовим опции модуля
var options = { id : 'js-PersonField' };

//запускаем модуль
AhunterSuggest.Person.Solid( options );

Детальное описание этого кода, а также описание подготовки вашего сайта к использованию подсказок приводится далее в этой статье.

В большинстве случаев для работы с подсказками бывает достаточно использовать модуль ahunter_suggest.js. Однако если вам нужно встроить подсказки в отдельное приложение, либо если у вас есть своё JavaScript решение для отображения подсказок, то для получения подсказок от Ахантера нужно будет использовать напрямую его REST API. Соответствующее описание приводится во второй части данной статьи.

Как добавить подсказки для ФИО на веб-сайт

Подготовка сайта для подключения подсказок

Чтобы добавить подсказки для фамилий, имён и отчеств на сайт, как и в случае с адресными подсказками, необходимо выполнить подготовку сайта. А именно, нужно установить jQuery, установить наш JavaScript-модуль ahunter_suggest.js, а также настроить таблицу стилей, чтобы подсказки отображались красиво.

Все эти процедуры детально описаны в подсказках для почтовых адресов по следующей ссылке. Поскольку для адресов используется тот же самый JavaScript-модуль ahunter_suggest.js, подготовка для ФИО будет идентичной.

Подключение подсказок на сайте

Чтобы запустить подсказки, на вашем сайте должна присутствовать форма с полем для ввода ФИО. Этому полю должен быть присвоен идентификатор, чтобы по нему наш модуль ahunter_suggest.js смог найти это поле на странице и запустить для него подсказки. Например, в простейшем случае HTML-разметка с таким полем может иметь следующий вид.

<div>
  <input id="js-PersonField" placeholder="Введите ФИО">  
</div>

Теперь, чтобы запустить подсказки, достаточно где-нибудь на странице добавить следующий инициализирующий скрипт:

<script>
  
  //готовим настройки модуля
  var options = { id : 'js-PersonField' };

  //запускаем модуль подсказок
  AhunterSuggest.Person.Solid( options );
  
</script>

Здесь выполняется заполнение опций options, которые затем передаются модулю подсказок посредством вызова AhunterSuggest.Person.Solid( options ). Этот вызов привяжет функционал подсказок к полю с идентификатором js-PersonField, после чего ввод ФИО в этом поле будет приводить к отображению подсказок.

Объект options позволяет указать и другие опции, влияющие на поведение и внешний вид подсказок. Все они подробно описаны в статье про адресные подсказки здесь. Например, там есть параметр, позволяющий ограничить количество отображаемых на экране подсказок. Также там есть опция, задающая функцию-колбэк, через которую наш модуль будет сообщать вашему приложению, какую именно подсказку выбрал пользователь.

Пример запуска подсказок с разными опциями

Ниже приведён пример инициализации модуля подсказок для ФИО, вводимого в одно поле, с помощью дополнительных параметров.

//Готовим опции для модуля подсказок
var options = 
{ 
  //Наше поле, куда пользователи будут вводить ФИО
  id: "js-PersonField",

  //Веб-адрес облачной версии сервиса
  ahunter_url : "https://ahunter.ru/",

  //Не будем показывать предупреждающее сообщение, когда подсказок нет
  empty_msg : "",

  //Будем показывать только 5 топовых подсказок
  limit : 5,
  
  //Не будем показывать подсказки при возврате фокуса в поле ввода
  suggest_on_focus : false,

  //При выборе подсказки будем выводить её в отладочную консоль
  on_fetch : function( Suggestion, Person ) 
  {
    console.log( Suggestion, Person );
  },
  
  //Указываем свой открытый API-токен, чтобы работал on_fetch
  user : "demotoken"
};

//Запускаем модуль подсказок
AhunterSuggest.Person.Solid( options );

После выполнения этой инициализации всякий раз, когда пользователи будут вводить ФИО в поле js-PersonField, на экране будут появляться подсказки с подходящими ФИО.

REST API подсказок для ФИО

Если вам нужно встроить подсказки для ФИО не на веб-сайте, а в ваше приложение, либо если вы по каким-то причинам не можете подключить наш JavaScript-модуль подсказок ahunter_suggest.js, то в этом случае вам следует напрямую использовать API-команду suggest/person нашего сервиса для запроса и получения подсказок для вводимого пользователем ФИО.

Принципы использования API подсказок при вводе ФИО

Данная команда полагает, что имя персоны вводится пользователем в режиме реального времени. Каждый раз, когда пользователь вводит очередной символ целевого ФИО, увеличивается количество информации, на основе которой сервис может сформировать подсказки для слова, вводимого в настоящий момент.

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

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

Пример простого запроса подсказок

Приведенный ниже запрос отсылает сервису строку "Сидоров А", представляющую собой начало ФИО, введенное к настоящему моменту пользователем. На основании этой информации сервис должен сформировать подсказки для завершения слова, вводимого пользователем в настоящий момент (в данном случае введена лишь первая буква этого слова - "А").

В данном запросе используются следующие параметры.

• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• query=%D0%A1%D0 ... %20%D0%90 - закодированное с использованием URL-encoding введенное пользователем начало ФИО "Сидоров А" в кодировке UTF-8, для которого необходимо получить подсказки.

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

Параметры команды

Обязательные параметры для выполнения запроса.

• http://ahunter.ru/site/suggest/person - URL-команды.
• output=json или output=xml - формат, в котором требуется вернуть результат выполнения команды.
• query=строка запроса - строка, содержащая введенное пользователем начало ФИО, для которого требуется получить подсказки.

Опциональные параметры.

• output=pretty - опция, применимая только в случае использования JSON формата ответа сервиса. Данная опция требует, чтобы сервис выполнил "красивое" форматирование возвращаемого JSON-текста, расставив в нем переносы строк, отступы и пробельное прореживание. Опция может быть полезна при отладке взаимодействия пользовательского приложения с сервисом. Если этот параметр не задан, JSON-ответ будет возвращен в виде сплошной строки.
• output=cp1251 - опция, применимая только в случае использования XML формата ответа сервиса. Данная опция требует, чтобы сервис вернул XML-ответ в кодировке windows-1251. Если этот параметр не задан, данные возвращаются в кодировке UTF-8.
• input=utf8 или input=cp1251 - кодировка UTF-8 или windows-1251, в которой представлены входные данные в параметре query. Если этот параметр не задан, полагается, что данные получены в кодировке UTF-8.
• personlim=число - ограничение на число возвращаемых подсказок. Если данное значение превышает установленный администратором сервиса порог, равный 20 подсказкам, то данное значение будет принудительно уменьшено до этого допустимого порога. Если в запросе данный параметр не указан, то в качестве лимита будет выступать установленное администратором сервиса умолчальное значение, равное 10 подсказкам.

Пример запроса подсказок с дополнительными опциями

Приведенный ниже запрос отсылает сервису на обработку введенное пользователем начало ФИО "Ломоносов М" с дополнительными параметрами.

В данном запросе используются следующие параметры.

• input=utf8 - сообщает сервису о том, что обрабатываемая строка представлена в кодировке UTF-8.
• output=json|pretty - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво".
• query=%D0%9B%D0 ... %20%D0%9C - закодированное с использованием URL-encoding введенное пользователем начало ФИО "Ломоносов М" в кодировке UTF-8, для которого необходимо получить подсказки.
• personlim=3 - сообщает сервису, что следует вернуть только три наиболее подходящие подсказки для вводимого ФИО.

Результат запроса: подсказки ФИО в формате JSON

Ниже приведен ответ сервиса с результатом формирования подсказок по введенному пользователем началу ФИО "Иван Т". Полагается, что пользователь вводит ФИО некой персоны, имеющей имя "Иван", и сейчас начинает вводить фамилию или отчество этой персоны, начинающееся с буквы "Т".

Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста, а также с опцией personlim=3, чтобы ограничить число выводимых подсказок тремя штуками

{
  "query" : "Иван Т",
  "request_process_time" : 17,
  "suggestions" : [
    {
      "first_name" : "Иван",
      "last_name" : "",
      "patronym" : "Тимофеевич",
      "value" : "Иван Тимофеевич"
    },
    {
      "first_name" : "Иван",
      "last_name" : "",
      "patronym" : "Трофимович",
      "value" : "Иван Трофимович"
    },
    {
      "first_name" : "Иван",
      "last_name" : "",
      "patronym" : "Тихонович",
      "value" : "Иван Тихонович"
    }
  ]
}

Результатом формирования подсказок для вводимого ФИО является JSON-объект со следующими элементами.

• suggestions - массив с вариантами подсказок для обработанного ФИО.
• query - строка, содержащая исходный обработанный запрос.
• request_process_time - время обработки всего запроса в целом в миллисекундах.

Ниже приведено детальное описание этих элементов.

JSON-массив suggestions

Поскольку при формировании подсказок полагается, что ФИО введено не полностью, вариантов завершения написания слова, вводимого пользователем в настоящий момент, в общем случае может быть несколько. Каждый из вариантов завершения вводимого слова является подсказкой для пользователя, которую тот может выбрать в качестве целевого слова. Каждому предлагаемому сервисом варианту соответствует отдельный элемент JSON-массива suggestions. Количество предлагаемых вариантов может лимитироваться с помощью опционального параметра personlim, передаваемого в рамках запроса.

Пример JSON-объекта, соответствующего одному варианту подсказок для вводимого ФИО, приведен ниже.

{
  "first_name" : "Иван",
  "last_name" : "",
  "patronym" : "Тимофеевич",
  "value" : "Иван Тимофеевич"
}

Каждый элемент массива suggestions представляет собой JSON-объект со следующими элементами.

• first_name - имя подсказываемого ФИО.
• last_name - фамилия подсказываемого ФИО.
• patronym - отчество подсказываемого ФИО.
• value - полное подсказываемое ФИО одной строкой. Компоненты ФИО, предлагаемые сервисом в этой строке, приведены в стандартизованном виде с исправленными ошибками.

Поскольку формирование подсказок происходит в режиме реального времени, никакой дополнительной информации по каждой подсказке сервис не возвращает. Это обусловлено необходимостью минимизировать сетевой трафик и время отклика сервиса. Чтобы получить исчерпывающую информацию по итоговому ФИО, которое ввел или выбрал из предложенных подсказок пользователь, приложению пользователя следует использовать команду стандартизации ФИО: cleanse/person.

Результат запроса: подсказки в формате XML

Здесь и далее приводится описание ответа сервиса в случае использования формата XML. По существу, возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

XML-ответ сервиса в результате формирования подсказок по введенному пользователем началу ФИО "Иван Т" имеет следующий вид.

<ProcessSuggestResult>
  <Query val="Иван Т"/>
  <Suggestion first_name="Иван" 
              last_name="" 
              patronym="Тимофеевич" 
              val="Иван Тимофеевич"/>
  <Suggestion first_name="Иван" 
              last_name="" 
              patronym="Трофимович" 
              val="Иван Трофимович"/>
  <Suggestion first_name="Иван" 
              last_name="" 
              patronym="Тихонович" 
              val="Иван Тихонович"/>
</ProcessSuggestResult>

Результатом формирования подсказок для вводимого ФИО является XML-документ со следующими дочерними элементами.

• Query - данный XML-элемент содержит обработанную строку запроса. Эта строка передается с помощью атрибута val этого XML-элемента. Данный элемент является полным аналогом JSON-элемента query, возвращаемого в JSON-ответе сервиса.
• Suggestion - данный XML-элемент соответствует одному предложенному сервисом варианту подсказки. Поскольку при формировании подсказок полагается, что ФИО введено не полностью, таких вариантов может быть несколько. В связи с этим в XML-ответе может присутствовать несколько элементов Suggestion. Список из всех XML-элементов Suggestion является аналогом JSON-массива suggestions, возвращаемого в JSON-ответе сервиса.

Ниже приведено детальное описание этих XML-элементов.

XML-элемент Suggestion

Элемент Suggestion содержит информацию об одной подсказке из предложенного сервисом списка подсказок по вводимому ФИО. Пример данного элемента приведен ниже.

<Suggestion first_name="Иван" 
            last_name="" 
            patronym="Тимофеевич" 
            val="Иван Тимофеевич"/>

Данный элемент содержит следующие атрибуты.

• first_name - отдельное имя подсказываемого ФИО.
• last_name - фамилия подсказываемого ФИО.
• patronym - отчество подсказываемого ФИО.
• val - полное подсказываемое ФИО одной строкой. Компоненты ФИО, предлагаемые сервисом в этой строке, приведены в стандартизованном виде с исправленными ошибками.