Интеграция со сторонними сервисами

Материал из Alytics Wiki
Перейти к: навигация, поиск

Универсальная интеграция с CRM (подходит для интеграции разных систем)

Чтобы получить полноценную сквозную аналитику, вы можете самостоятельно подготовить выгрузку данных по продажам из CRM по описанию в данном разделе и затем подключить свою CRM к Alytics на странице настроек целей в проекте.

Интеграция описана на примере подключения CRM-системы, но этот способ подойдет для интеграции большинства внешних систем из которых вы хотите передать данные к нам, например систем хранения и анализа данных.

После завершения интеграции вы увидите в Alytics статистику из вашей системы в виде целей с набором переданных показателей. Примерно так:

01 Унив. выгрузка.png

Техническое описание универсальной интеграции с CRM

Описание ниже вы можете использовать как задание для своих разработчиков. По всем вопросам, связанным с интеграцией CRM-системы, пишите нам на support@alytics.ru.

Вам нужно:

1) определить, какие именно данные вы хотите передавать в Alytics (например, успешные сделки из CRM);

2) отдавать эти данные по отдельному URL-адресу защищенному базовой аутентификацией (ссылка должна открывать по логину и паролю). На сервере клиента должна быть реализована базовая аутентификация https://en.wikipedia.org/wiki/Basic_access_authentication . Взаимодействие между Alytics и вашей CRM, а также формат данных описаны ниже.

Alytics будет делать запросы по вашему URL и передавать в параметре запроса дату, за которую мы хотим получить информацию по сделкам CRM. Обратите внимание: в Alytics полученные данные будут сохранены и отображены именно за эту дату.

Запрос имеет следующий формат:


Метод URL Параметры
GET Пользовательский URL date


Пример запроса от Alytics: http://alytics.ru/stat_example/?date=2016-10-12


Ответ должен быть json-формата, следующего вида (ниже приведены примеры транзакций):

{
  "data": {
    "transactions": [
      {
        "id": "2201008",
        "number": "22010081",
        "revenue": 10000,
        "profit": 1000,
        "count": 1,
        "ym_client_id": "123123123123123123123",
        "href": "https://alytics.ru/features/skvoznaya-analitika/",
        "creation_date": "2019-07-20 06:46:55",
        "utm_source": "yandex",
        "utm_medium": "cpc",
        "utm_content": "v2||1234323123||12312311123||алитикс||1||premium||none||search||no",
        "utm_campaign": "alytics-none-brend-poisk-msk-333323",
        "utm_term": "алитикс",
        },
      {
        "id": "2211009",
        "number": "",
        "revenue": 200000,
        "profit": ,
        "count": 1,
        "ym_client_id": "123123123123123123123",
        "href": "",
        "creation_date": "2019-07-20 06:46:55",
        "utm_source": "yandex",
        "utm_medium": "cpc",
        "utm_content": "",
        "utm_campaign": "alytics-none-brend-poisk-msk-333323",
        "utm_term": "",
        },
    ]
  }
}

ВАЖНО: Если данных нет, то ответ должен быть такой:

{
  "data": {
    "transactions": [] 
  }
}


Из ответа по url цели Alytics получает из CRM объекты transaction, каждый объект это отдельная сделка, по каждой сделке мы сохраняем к себе достижение цели со всеми переданными показателями.

Поле Формат Описание Требование к полю
Информация об источнике сделки
utm_source любые символы Рекламный источник. Метка utm_source из сделки. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
utm_medium любые символы Рекламный канал. Метка utm_medium из сделки. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
utm_content любые символы Содержание рекламного объявления. Метка utm_content из сделки. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
utm_campaign любые символы Рекламная кампания. Метка utm_campaign из сделки. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
utm_term любые символы Ключевое слово. Метка utm_term из сделки. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
Специальные поля
client_id цифры и буквы НЕ ИСПОЛЬЗУЕТСЯ (УСТАРЕЛО). Google client id (cid) из CRM, client_id клиента, полученный из куки Google Analytics. НЕ ИСПОЛЬЗУЕТСЯ (УСТАРЕЛО). Передавайте, если используете Google Analytics в качестве основного счетчика в Alytics. Если значения для поля нет, передавайте пустое.
ym_client_id цифры и буквы Yandex Metrika client id (cid) из CRM, client_id клиента, полученный из куки Яндекс Метрики. Передавайте, если используете Яндекс Метрику в качестве основного счетчика в Alytics. Если значения для поля нет, передавайте пустое. В Алитикс сохраняем первые 128 символов из поля.
client_id_date (new) YYYY-MM-DD HH:MM:SS Если вы хотите атрибуцию по мультиканальной цепочке не от даты сделки, а, например, от даты первой покупки клиента (для учета LTV), передайте в этом поле нужные дату и время. В противном случае оставьте поле пустым. Если нет информации по секундам, то передавайте вместо SS значение 59.

Если вы будете использовать данное поле, напишите нам об этом, указав номер или логин проекта, на support@alytics.ru.

Поле не обязательное. Добавляется специально для фичи LTV.
Информация о сделке
id цифры и буквы Идентификатор транзакции из CRM. Максимальный размер str — 1024 символа. Если больше — сохраняются первые 1024. Также поддерживаются числовые значения int/float, которые при сохранении конвертируются в строку.

Если поле пустое то сделка не будет отображаться в фиче «Просмотр сделок».

Поле обязательно должно присутствовать в ответе. Значение id должно быть уникальным для целей каждой отдельной сделки.
number (new) цифры и буквы Номер транзакции (заказа) из CRM, если в вашей CRM он есть. Номер — это отдельный от id параметр сделки, используется для гибкой и удобной нумерации сделок, доступен не во всех CRM. Поле не обязательное. Может отсутствовать в ответе.
href (new) url адрес на страницу сделки Ссылка на страницу транзакции в CRM.

Обратите внимание: нужно передавать полную ссылку на страницу сделки в CRM, начиная с указания протокола (http/https).

Поле не обязательное. Может отсутствовать в ответе.
creation_date (new) YYYY-MM-DD HH:MM:SS Дата и время создания сделки из CRM. Если нет информации по секундам, то передавайте вместо SS значение 59. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
Показатели
revenue число с точностью до сотых Выручка по сделке из CRM. Если придет пустое, сохраним как 0. Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте пустое.
profit число с точностью до сотых Прибыль по сделке из CRM.

Если вы будете использовать данное поле, напишите нам об этом, указав номер или логин проекта, на support@alytics.ru.

Если придет пустое, сохраним как 0.

Поле не обязательное. Может отсутствовать в ответе.
count цифры Количество.

Для сделок CRM всегда равно 1, в случае с другими системами показатель зависит от вашей бизнес-логики.

Если придет пустое, сохраним как 1.

Поле обязательно должно присутствовать в ответе. Если значения для поля нет, передавайте 1.


Передача дополнительных полей (кастомных деменшенов)

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

Как это сделать? Добавьте в начале json документа словарь extra_fields, который содержит описание дополнительных полей (до 15 полей). А для каждой сделки внутри transactions значение дополнительного поля.

В словаре extra_fields для каждого дополнительного поля указывайте описание в следующих параметрах:

Поле объекта словаря extra_fields Описание Как используется Формат
field Системное название Используется в массиве transactions при передаче данных Цифры, латинские буквы, подчеркивания.

Название должно содержать префикс cd_

human Название поля для отчета. Это название будет отображаться в интерфейсе c отчетами в Alytics Цифры и буквы (кириллица, латиница)
type Тип дополнительного поля Используется Alytics для корректной обработки данных string, number, datetime

формат datetime - YYYY-MM-DD HH:MM


Для каждого объекта в transactions внутри массива extra_fields вам нужно добавить значение дополнительного поля, в формате: "Системное название дополнительного поля (из словаря extra_fields)": "значение".

Пример выгрузки с дополненными полями:

Добавлено:

словарь extra_fields в начале документа, массив полей extra_fields внутри объекта в transactions.

{
  "data": {
    "extra_fields": [
        {
         "field": "cd_manager",
         "human": "Менеджер",
         "type": "string"
        },
        {
         "field": "cd_shop",
         "human": "Магазин",
         "type": "string"
        },
        {
         "field": "cd_geo",
         "human": "Регион",
         "type": "string"
        }     
    ],
    "transactions": [
      {
        "id": "1035217398",
        "number": "1035217398",
        "external_id": 103322161,
        "revenue": 0,
        "profit": 0,
        "count": 1,
        "href": null,
        "client_id_date": null,
        "creation_date": "2021-01-05 08:45:54",
        "utm_source": "",
        "utm_medium": "direct",
        "utm_content": "",
        "utm_campaign": "",
        "utm_term": "",
        "ym_client_id": "123123123123123123123",
        "last_update": "2021-01-22 07:25:37",
        "extra_fields":  {
            "cd_manager": "Белов",
            "cd_shop": "Алтуфьево",
            "cd_geo": "Москва"
        }
      }
    ]
  }
}

Требования и ограничения:

1. Максимальное количество пользовательских полей в словаре extra_fields – 15.

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

3. Название полей в словаре extra_fields должны быть уникальными и не могут дублироваться. В противном случае данные не будут загружены.

4. Системное название пользовательских полей (поле field) должно начинаться с префикса cd_. В противном случае данные не будут загружены.

5. Названия полей в словаре extra_fields и значения полей в массиве extra_fields объекта transactions должны соответствовать указанному формату. В противном случае данные не будут загружены.


Как передавать сделки в разных статусах

Часто возникает потребность передавать данные из CRM в нескольких статусах, например, при построении воронки продаж. Вы можете сделать несколько выгрузок из CRM, чтобы передать их в Alytics. Сделайте выгрузку из CRM заявок в одном из статусов, который вы хотите отслеживать, по правилам, размещенным выше. Например, ваша ссылка на эту выгрузку выглядит так: сайт.ru/. В таком случае, для второй цели ссылка должна выглядеть так: сайт.ru/1/. По этой ссылке нужно передавать данные для второй цели. Для третьей цели ссылка будет выглядеть так: сайт.ru/2/ и так далее.

ОБРАТИТЕ ВНИМАНИЕ: для корректной работы интеграции основная ссылка и ссылки на другие выгрузки должны обязательно заканчиваться на слеш "/"

Логин и пароль к следующей выгрузке (статусу, цели) должны быть такими же, как у первой выгрузки.


Требования к данным

— Выгрузка должна быть в json-формате и кодировке UTF-8.

— Часовой пояс всех временных параметров в выгрузке должен быть такой же, как в вашей Яндекс Метрики.

— URL выгрузки должен быть без параметров (в параметрах мы передаем нужную дату).

— В выгрузке обязательно должны присутствовать все обязательные поля указанные в таблице выше.

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


Обязательные настройки и процедуры при подключении CRM

— Если у вас происходит обновление информации по сделкам за старые даты, напишите нам об этом на support@alytics.ru и мы настроим регулярные обновления.

— Если вы передаете в выгрузке фактическую прибыль в поле «profit», напишите нам об этом на support@alytics.ru, указав номер или логин вашего проекта, и мы проверим, что обработка данных идёт корректно.

— Если вы передаете в выгрузке дату начала атрибуции в поле «client_id_date», напишите нам об этом на support@alytics.ru, указав номер или логин проекта, чтобы мы проверили, что в вашем проекте есть все необходимые данные.


Особенности отображение данных

— ОБРАТИТЕ ВНИМАНИЕ: данные в Alytics будут отображаться не за дату из поля "creation_date", а за дату в запросе (из параметра URL). Т.е. мы просим вас отдать сделки за 01.01.2019 и отобразим у себя все полученные сделки за 01.01.2019.


Рекомендации по передаче данных

— Если вы передаете сделки из оффлайн-источников, мы рекомендуем указывать им соответствующий источник в полях utm_source и utm_medium. Например: utm_source=”Magazin na Sokole” и utm_medium="Offline". Таким образом вы явно отделите эти сделки в отчетах. Если вы просто передадите пустые значения в полях utm-меток и ym_client_id, сделка попадет в источник «Прямой трафик», что может быть некорректно.

Если у вас возникли какие-либо трудности при подготовке выгрузки, напишите на support@alytics.ru и мы поможем вам.



Как подключить выгрузку из CRM к проекту

Зайдите в проект в Alytics, затем в меню Настройки -> Настройка целей. Найдите блок «Данные из CRM» и нажмите «Зеленый плюсик».


Подключение OWOX.png



Укажите базовую ссылку с выгрузкой, Логин и Пароль:

M5.png



После того как поля для авторизации заполнены, Alytics сделает тестовый запрос для проверки корректности введенных данных. В случае успешного подключения в настройках проекта появится цель в разделе «Данные из CRM». По умолчанию она называется «Продажи из CRM», переименуйте её, задав удобное для вас название. Для этого нажмите на изображение карандаша в правой части плашки с целью:

Изменение цели.png



Если у вас несколько выгрузок (например, для разных статусов) и вы хотите добавить еще одну цель, то нажмите «Создать цель».

Создать цель 2.png



У вас создастся вторая цель, которая соответствует выгрузки оканчивающейся на /1/, назовите её так, как вам удобно:

  1. Введите название цели.
  2. Обратите внимание на предупреждение о том, что url второй выгрузки Alytics назначает сам, вы должны сделать выгрузку строго по тому url'у, который отобразится в настройке.

Интеграция с CRM 3.png



Создавайте столько целей, сколько у вас подготовлено выгрузок. Цели добавляются последовательно и последовательно соответствуют выгрузкам с окончаниями /1/, /2/, /3/, /4/, и т.д.

Чтобы эти цели отображались в отчетах Сквозной аналитики, нужно нажать «Зеленый плюсик» около цели и сохранить. Данные появятся в проекте Alytics на следующий день.

Добавление целей.png



Обратите внимание: после подключения интеграции нужно обязательно написать нам на support@alytics.ru с указанием номера проекта для включения дополнительных настроек со стороны Alytics.