API Link Manager

Краткое содержание

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

Пример использования
Маркетолог Толя использует API Link Manager для создания одной ссылки, которая ведёт:

• на страницу товара в браузере
• на карточку товара в приложении через диплинк
• в магазин приложений (если приложение не установлено)

Поддерживаемые сценарии
Ссылка может открываться:

• в браузере (если приложение не установлено)
• в приложении (если оно установлено и определена ОС)
• в магазин приложений

Предварительные действия

• Авторизоваться в сервисе и зарегистрировать поддомен
• Настроить приложение (если требуется)
• Получить Flow ID от МТС Аналитики

Работа с API

• Для get-запросов требуется разрешение на аналитику потока
• Для post, put, delete — разрешение на управление потоком
• Доступ можно запросить на почту analytics.support@mts.ru

Шаг 1. Скачать спецификацию
Файл link-manager-api.json содержит примеры запросов и параметры для работы с API.

Шаг 2. Создать шаблон
Шаблон используется для создания множества ссылок. В нём указываются:

• flowId (обязательный)
• name, alias, subdomain (обязательные)
• noAppLongLinks и appLongLinks (адреса для разных сценариев)
• apps (ключи подписи приложения от разработчика)

Действия с шаблоном

• Удаление удаляет шаблон и связанные ссылки
• Получение — поиск по id
• Изменение — редактирование параметров (кроме alias и subdomain)

Шаг 3. Создать ссылку
Ссылка связана с шаблоном и используется для ретаргетинга. Параметры:

• flowId, templateId, name, alias, mediaSource (обязательные)
• noAppLongLinks и appLongLinks заполняются автоматически из шаблона

Работа со ссылками
Универсальная ссылка формируется как https://<subdomain>.<домен>/<alias>. При открытии в приложении в Аналитику отправляется событие shortlink с параметрами:

• maClickId (идентификатор клика)
• maLinkId (идентификатор ссылки)

UTM-метки
Параметры с UTM-метками передаются в Аналитику, но статистика пока недоступна.

С помощью API Link Manager вы сможете работать с универсальными короткими ссылками и создавать шаблоны для быстрой настройки перенаправления. Это позволит:

• увеличивать конверсию в совершение целевых действий
• управлять разными сценариями взаимодействия клиента с вашим продуктом
• оценить эффективность рекламных кампаний и каналов

Пример применения

Толя — маркетолог. Его задача — запустить рассылку с рекламой нового средства от головной боли. Толя понимает, что ссылку из такой рассылки клиенты могут открыть и в браузере, и в приложении. Важно, чтобы в приложении ссылка вела на конкретную карточку товара.

Чтобы убить двух зайцев, Толя хочет создать одну короткую ссылку для всех платформ. Для этого он использует API Link Manager.

Через сервис он сможет создать единую и универсальную ссылку, которая отправит пользователя:

• на страницу товара в браузере
• на карточку товара в приложении через диплинк
• в магазин приложений (если оно не установлено)

Поддерживаемые сценарии

1. Ссылка открывается НЕ с мобильного устройства — приложение открывается в браузере.
2. Ссылка открывается с мобильного устройства:

• ссылка открывается в браузере (например, если приложение не установлено)
• запускается приложение (например, если приложение установлено и определена ОС)
• ссылка ведёт в магазин приложений

Предварительно проверьте

1. Вы авторизовались в сервисе Link Manager и зарегистрировали ваш поддомен. Подробнее.
2. Разработчик настроил приложение, если вы планируете направлять трафик в приложение. Подробнее.
3. Вы получили идентификатор потока Flow ID от команды МТС Аналитики.

Кто задействован

• разработчик
• маркетолог или продуктолог

Работа с API

Доступы для выполнения запросов

• get — разрешение на аналитику потока

• post, put, delete — разрешение на управление потоком

Как получить доступ

Для получения доступа напишите на почту analytics.support@mts.ru с темой «Доступ к API Link Manager».

Шаг 1. Скачать спецификацию

Файл содержит все примеры запросов к системе в рамках Link Manager API (спецификацию). Далее описаны параметры запросов как раз из этого файла.

Шаг 2. Создать шаблон

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

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

Заполните:

1. flowId — идентификатор потока (получили ранее от команды МТС Аналитики). Обязательный параметр.

2. name — название шаблона. Например, название приложения. Обязательный параметр.

3. alias — код шаблона, указывается в URL короткой ссылки. Можно заполнить самостоятельно, или он сгенерируется автоматически. Например, «1a2b».

4. subdomain — поддомен, который вы зарегистрировали в Link Manager. Например, «mtsanalytics». Обязательный параметр.

5. noAppLongLinks — адрес страницы направления пользователей, у которых нет приложения продукта (для iOS, Android, десктопов и других платформ). Например, ссылка на страницу товара или лендинг. Для ссылки могут быть указаны дополнительные параметры. Пример формата

    "ios": {
      "link": "https://link-for-some-os/myapp",
      "params": {
        "param1": "value1",
        "param2": "value2"
       }
    }

Важно

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

6. appLongLinks — адрес страницы направления для пользователей, у которых есть приложение продукта. Платформы: Android, iOS, default (если приложение установлено, но не определена ОС).

7. apps — ключ подписи приложения (SHA256), packageName для Android и Team ID, Bundle ID для iOS. Их предоставит разработчик.

В дальнейшем шаблон можно запросить, изменить и удалить. Подробнее — в спецификации.

Действия с шаблоном

Действие	Что произойдёт
Удалить	Удалится шаблон и все связанные с ним ссылки
Получить	Найти конкретный шаблон по id
Изменить	Можно редактировать все параметры, кроме alias и subdomain (для нового поддомена создаётся новый шаблон)

Результат

Вы создали шаблон, получили ответ с alias и id шаблона (templateId). Описание возможных ошибок — в файле.

Для разработчика

Для корректной работы универсальных ссылок нужно подтвердить, что домен в ссылке принадлежит конкретному приложению, которое должно открыться по клику. Такое связывание доменов делается с помощью assetlinks.json для Android и .aasa файл для iOS. Файл будет создан после создания шаблона.

Файл обновляется, когда шаблон изменяется или удаляется.

Шаг 3. Создать ссылку

Ссылка направляет пользователей на веб-страницу или в приложение в зависимости от их устройства.

Отличие шаблона от ссылки

Шаблон	Ссылка
«Основа» для всех коротких ссылок ресурса. Удобно использовать, чтобы при создании каждой новой ссылки не заполнять некоторые параметры заново	Конечная кликабельная ссылка, которая связана с шаблоном и используется для ретаргетинга

Заполните:

1. flowId — идентификатор потока (получили ранее от команды МТС Аналитики). Обязательное поле.

2. templateId — идентификатор шаблона, который вы получили на шаге 2. Обязательное поле.

3. name — название ссылки. Пример: «Лендинг». Обязательный параметр.

4. alias — код ссылки, указывается в URL короткой ссылки. Можно заполнить самостоятельно, или он сгенерируется автоматически. Например, «7a9b678k». Если заполняете поле сами, alias должен быть уникальным, иначе в ответе придёт ошибка.

5. mediaSource — источник трафика. Например, email или SMS. Обязательный параметр.

6. Не заполняйте поля: ttlSeconds, reattributionWindowDays, isRetargetingEnabled, partnerId.

7. noAppLongLinks и appLongLinks — значения этих полей заполнятся автоматически из шаблона. Если вы хотите задать другие значения, заполните поля.

Сценарии заполнения полей

Как будет работать перенаправление, если заполнить или не заполнить поля noAppLongLinks, appLongLinks в шаблоне и при настройке ссылки

В шаблоне	В ссылке	Куда в итоге направляем
https://a.mts.ru/analytics/flows	https://a.mts.ru/tm	https://a.mts.ru/tm
Поле не заполнено	https://a.mts.ru/analytics/flows	https://a.mts.ru/analytics/flows
https://a.mts.ru/analytics/flows	Поле не заполнено	https://a.mts.ru/analytics/flows
Поле не заполнено	Поле не заполнено	404

В дальнейшем ссылку можно запросить, изменить и удалить. Подробнее — в спецификации.

Результат

Вы создали ссылку и получили alias и id ссылки. Описание возможных ошибок — в спецификации.

Работа со ссылками

Универсальная ссылка имеет конечный вид:

Пока в Аналитике нет возможности «собрать» её автоматически, добавьте полученные alias шаблона и ссылки к поддомену самостоятельно.

Для приложений

Если по клику на ссылку открывается приложение, в Аналитику отправляется событие shortlink c полным URL короткой ссылки c обязательными и дополнительными параметрами, которые вы указали при настройке.

Передаваемые параметры

Параметр	Описание
maClickId	Идентификатор клика по ссылке
maLinkId	Идентификатор ссылки, по которой перешёл пользователь

UTM-метки

Важно

Все параметры переходов по ссылкам с UTM-метками передаются и сохраняются в Аналитике, но статистика пока недоступна. Мы уже работаем над этим.