Обработка параметров start (UTM)

Что такое параметр start?

Параметр start - это единственный способ передать данные в бот при его запуске. Чтобы его использовать нужно к обычной ссылке на бот добавить строку ?start={ ваши данные }, такие ссылки называются Deep links.

Как получить эти данные в боте?

Пример ссылки на бот: https://t.me/Graspil_bot?start=docs

Значение, которое получит бот docs

Когда пользователь запускает бот, вам приходит Update типа Message. В нем есть параметр text который равен /start, в случае с deep link параметр text будет равен /start docs

Пример

{
   update_id":10000,
   "message":{
     "date":1441645532,
     "chat":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "message_id":1365,
     "from":{
        "last_name":"Test Lastname",
        "id":1111111,
        "first_name":"Test",
        "username":"Test"
     },
     "text":"/start docs" // <----- данные переданные в start
   }
}

Существует ограничение в 64 символа на длину строки в параметре start

Для чего он используется в Graspil?

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

1. Отслеживание источника пользователей (UTM) — разбить строку на пары параметр=значение, чтобы видеть, откуда пришёл пользователь, фильтровать и строить отчёты. Это классический сценарий, ему посвящена основная часть этой страницы. Подробнее — в блоге.

2. Регистрация в реферальной программе — ссылка вида ?start=ref-<код> (имя параметра настраивается) регистрирует пользователя как чьего-то реферала. См. Реферальная система.

3. Запись значения в доп. поле пользователя — конкретный параметр из start можно направить прямо в доп. поле вместо UTM-метки (или вместе с ней) — см. раздел «Маршрутизация параметра в доп. поле» ниже.

4. Перенос данных, собранных на вашем сайте или по внешней ссылке — скрипт для сайта и редирект-ссылки tlin.cc кладут в start/startapp специальный токен li1…; при запуске бота Graspil находит по нему UTM-метки, геолокацию и доп. поля, собранные ранее для этого посетителя.

Эти сценарии можно совмещать: например, одна ссылка может нести реферальный код в одном параметре и UTM-источник в другом, а токен li1 заменяет всю строку целиком и переносит всё, что было собрано на сайте.

Как graspil обрабатывает параметр start?

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

Так как в start можно передать только одну строку, мы добавили правила с помощью которых такую строку можно разделить на разные параметры.

Например, вам нужно передать источник перехода по ссылке и тип источника (например email). Для этого вы можете использовать строку такого вида start=source-news1_medium-email и задать нужные настройки для ее обработки.

В graspil все такие параметры преобразовываются в параметр=значение иными словами в таблицу, с которыми в дальнейшем можно работать (строить отчеты, фильтровать данные).

Параметр	Значение
source	news1
medium	email

Настройка обработки параметра start

Вы можете настроить правила обработки для каждого бота. Для этого перейдите в раздел Мои боты и выберите нужного бота. На странице информации о боте найдите пункт "UTM-метки" (правила обработки start) и перейдите к их настройке.

Страница настройки правил обработки состоит из двух частей:

1. Форма настроек (о ней ниже)

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

Упрощенный режим

Этот режим выбран по умолчанию для всех новых ботов

Упрощенный режим не обрабатывает параметр start и используется как есть. Этот режим подойдет в том случае, если не нужны дополнительные параметры. Например, строка start=docs будет обработана так:

Параметр	Значение
none	docs

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

Тип обработки

Тип обработки строки позволяет исключить какие-то параметры. Это поле дает 3 варианта выбора:

1. Все параметры — будет учитывать все параметры

2. Только указанные параметры — будет учитывать только те параметры, которые вы укажите

3. Все кроме указанных параметров — будет учитывать все параметры кроме тех, которые вы укажите

Список параметров

Если "тип обработки" равен "только указанные параметры" или "все кроме указанных параметров", то в этом поле вы можете задать список этих самых параметров.

Разделитель параметров и Разделитель значений

Это символы, которые будут делить строку для определения параметра и их значений. На изображении ниже разделитель параметров равен "_", а разделитель значений равен "—"

Алгоритм обработки строки source—google_campaign—cpc будет следующий:

1. Делим строку по разделителю параметров "_", получаем

   1. source—google

   2. campaign—cpc

2. Полученный результат делим по разделителю значений "—", получаем:

Параметр	Значение
source	google
campaign	cpc

Маршрутизация параметра в доп. поле

На той же странице настроек, в блоке «Параметры в кастомные поля», можно направить конкретный параметр прямо в доп. поле, вместо того чтобы учитывать его как UTM-метку. Это удобно для идентификаторов, которые бесполезны как метка: внешний id, номер партнёра и т. п.

Для каждого маршрута задаются:

• Параметр — имя параметра в строке start (после разбора по правилам выше).

• Поле — в какое доп. поле записать значение.

• Оставить также в UTM-метках — по умолчанию выключено; если включить, значение запишется в доп. поле и останется среди UTM-меток.

• Не перезаписывать заполненное поле — поведение first-touch: если поле уже заполнено, новое значение из start его не заменит.

Маршрутизация в доп. поля не работает в упрощённом режиме, так как в нём строка start не разбирается на именованные параметры.

Что дальше

• Реферальная система — как параметр start превращается в реферальный трекинг и начисления.

• Доп. поля — все способы заполнить доп. поле, включая маршрутизацию, описанную выше.

• Скрипт для сайта — перенос данных, собранных на вашем сайте, в бота через start.